[clangd] Add a toy VS Code integration for development purposes

[krasimir]

Summary

This patch adds bare-bone VS Code integration for development purposes of clangd.

[mprobst]

clangd/clients/clangd-vscode/src/extension.ts

2

ES6 modules are always in strict mode, you can drop this here.

8

use /** JSDoc comments */ so that you get these comments on hover in the IDE.

12

prefer to always use const for variables that don't get re-assigned.

18

.h?

24

remove the tutorial comments?

29

this comment does not seem to fit the next line

clangd/clients/clangd-vscode/test/extension.test.ts

3

remove the tutorial comments?

clangd/clients/clangd-vscode/tsconfig.json

8

As this runs in a recent Node with pretty complete ES6 support, consider including:

• ES2015.Core
• ES2015.Collection
• ES2015.Generator
• ES2015.Iterable
• ES2015.Promise
• ES2015.Symbol
• ES2016.Array.Include

These add declarations for a bunch of useful library builtins, e.g. for array iteration, String.repeat, and so on.

11

tsc supports a bunch of strictness options that you should enable. See here for the reference: https://www.typescriptlang.org/docs/handbook/compiler-options.html

Enable:

• alwaysStrict
• noEmitOnError
• noFallthroughCasesInSwitch
• noImplicitAny
• noImplicitReturns
• noImplicitThis

The following are a bit questionable (I prefer to use tslint for them as they break the workflow):

• noUnusedLocals
• noUnusedParameters

clangd/clients/clangd-vscode/vsc-extension-quickstart.md

2

drop or update?

[krasimir]

• Address review comments

[bkramer]

lgtm

[mprobst]

clangd/clients/clangd-vscode/test/extension.test.ts

1

nit: use @fileoverview for, well, fileoverview comments :-)

7

// TODO(krasimir): ...

clangd/clients/clangd-vscode/.gitignore

+out
+node_modules
 No newline at end of file

clangd/clients/clangd-vscode/.vscode/launch.json

+// A launch configuration that compiles the extension and then opens it inside a new window
+{
+    "version": "0.1.0",
+    "configurations": [
+        {
+            "name": "Launch Extension",
+            "type": "extensionHost",
+            "request": "launch",
+            "runtimeExecutable": "${execPath}",
+            "args": ["--extensionDevelopmentPath=${workspaceRoot}" ],
+            "stopOnEntry": false,
+            "sourceMaps": true,
+            "outFiles": [ "${workspaceRoot}/out/src/**/*.js" ],
+            "preLaunchTask": "npm"
+        },
+        {
+            "name": "Launch Tests",
+            "type": "extensionHost",
+            "request": "launch",
+            "runtimeExecutable": "${execPath}",
+            "args": ["--extensionDevelopmentPath=${workspaceRoot}", "--extensionTestsPath=${workspaceRoot}/out/test" ],
+            "stopOnEntry": false,
+            "sourceMaps": true,
+            "outFiles": [ "${workspaceRoot}/out/test/**/*.js" ],
+            "preLaunchTask": "npm"
+        }
+    ]
+}

clangd/clients/clangd-vscode/.vscode/settings.json

+// Place your settings in this file to overwrite default and user settings.
+{
+    "files.exclude": {
+        "out": false // set this to true to hide the "out" folder with the compiled JS files
+    },
+    "search.exclude": {
+        "out": true // set this to false to include "out" folder in search results
+    }
+}
 No newline at end of file

clangd/clients/clangd-vscode/.vscode/tasks.json

+// Available variables which can be used inside of strings.
+// ${workspaceRoot}: the root folder of the team
+// ${file}: the current opened file
+// ${fileBasename}: the current opened file's basename
+// ${fileDirname}: the current opened file's dirname
+// ${fileExtname}: the current opened file's extension
+// ${cwd}: the current working directory of the spawned process
+
+// A task runner that calls a custom npm script that compiles the extension.
+{
+    "version": "0.1.0",
+
+    // we want to run npm
+    "command": "npm",
+
+    // the command is a shell script
+    "isShellCommand": true,
+
+    // show the output window only if unrecognized errors occur.
+    "showOutput": "silent",
+
+    // we run the custom script "compile" as defined in package.json
+    "args": ["run", "compile", "--loglevel", "silent"],
+
+    // The tsc compiler is started in watching mode
+    "isWatching": true,
+
+    // use the standard tsc in watch mode problem matcher to find compile problems in the output.
+    "problemMatcher": "$tsc-watch"
+}
 No newline at end of file

clangd/clients/clangd-vscode/.vscodeignore

+.vscode/**
+.vscode-test/**
+out/test/**
+test/**
+src/**
+**/*.map
+.gitignore
+tsconfig.json
+vsc-extension-quickstart.md

clangd/clients/clangd-vscode/README.txt

+A *toy* VS Code integration for development purposes.
+
+Steps:
+1. Make sure you have clangd in /usr/bin/clangd or edit src/extension.ts to
+point to the binary.
+2. Make sure you have nodejs and npm installed.
+3. Make sure you have VS Code installed.
+4. In order to start a development instance of VS code extended with this, run:
+   $ npm install
+   $ code .
+   When VS Code starts, press <F5>.

clangd/clients/clangd-vscode/package.json

+{
+    "name": "clangd-vscode",
+    "displayName": "clangd-vscode",
+    "description": "Clang Language Server",
+    "version": "0.0.1",
+    "publisher": "Unpublished",
+    "engines": {
+        "vscode": "^1.8.0"
+    },
+    "categories": [
+        "Languages",
+        "Linters",
+        "Snippets"
+    ],
+    "activationEvents": [
+        "onLanguage:cpp",
+        "onLanguage:c"
+    ],
+    "main": "./out/src/extension",
+    "scripts": {
+        "vscode:prepublish": "tsc -p ./",
+        "compile": "tsc -watch -p ./",
+        "postinstall": "node ./node_modules/vscode/bin/install",
+        "test": "node ./node_modules/vscode/bin/test"
+    },
+    "dependencies": {
+        "vscode-languageclient": "^2.6.3",
+        "vscode-languageserver": "^2.6.2"
+    },
+    "devDependencies": {
+        "typescript": "^2.0.3",
+        "vscode": "^1.0.3",
+        "mocha": "^2.3.3",
+        "@types/node": "^6.0.40",
+        "@types/mocha": "^2.2.32"
+    }
+}
 No newline at end of file

clangd/clients/clangd-vscode/src/extension.ts

+import * as vscode from 'vscode';
+import * as vscodelc from 'vscode-languageclient';
+
+/**
+ *  this method is called when your extension is activate
+ *  your extension is activated the very first time the command is executed
+ */
+export function activate(context: vscode.ExtensionContext) {
+    // TODO: make this configurable
+    const clangdPath = '/usr/bin/clangd';
+
+    const serverOptions: vscodelc.ServerOptions = { command: clangdPath };
+
+    const clientOptions: vscodelc.LanguageClientOptions = {
+        // Register the server for C/C++ files
+        documentSelector: ['c', 'cc', 'cpp', 'h', 'hh', 'hpp']
+    };
+
+    const clangdClient = new vscodelc.LanguageClient('Clang Language Server', serverOptions, clientOptions);
+
+    console.log('Clang Language Server is now active!');
+
+    const disposable = clangdClient.start();
+
+    context.subscriptions.push(disposable);
+}
 No newline at end of file

clangd/clients/clangd-vscode/test/extension.test.ts

+/** The module 'assert' provides assertion methods from node */
+import * as assert from 'assert';
+
+import * as vscode from 'vscode';
+import * as myExtension from '../src/extension';
+
+// TODO: add tests
+suite("Extension Tests", () => {
+
+    // Defines a Mocha unit test
+    test("Something 1", () => {
+        assert.equal(-1, [1, 2, 3].indexOf(5));
+        assert.equal(-1, [1, 2, 3].indexOf(0));
+    });
+});
 No newline at end of file

clangd/clients/clangd-vscode/test/index.ts

+//
+// PLEASE DO NOT MODIFY / DELETE UNLESS YOU KNOW WHAT YOU ARE DOING
+//
+// This file is providing the test runner to use when running extension tests.
+// By default the test runner in use is Mocha based.
+//
+// You can provide your own test runner if you want to override it by exporting
+// a function run(testRoot: string, clb: (error:Error) => void) that the extension
+// host can call to run the tests. The test runner is expected to use console.log
+// to report the results back to the caller. When the tests are finished, return
+// a possible error to the callback or null if none.
+
+var testRunner = require('vscode/lib/testrunner');
+
+// You can directly control Mocha options by uncommenting the following lines
+// See https://github.com/mochajs/mocha/wiki/Using-mocha-programmatically#set-options for more info
+testRunner.configure({
+    ui: 'tdd',    // the TDD UI is being used in extension.test.ts (suite, test, etc.)
+    useColors: true // colored output from test results
+});
+
+module.exports = testRunner;
 No newline at end of file

clangd/clients/clangd-vscode/tsconfig.json

+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "target": "es6",
+        "outDir": "out",
+        "lib": [
+            "es6",
+            "es2015.core",
+            "es2015.collection",
+            "es2015.generator",
+            "es2015.iterable",
+            "es2015.promise",
+            "es2015.symbol",
+            "es2016.array.include"
+        ],
+        "sourceMap": true,
+        "rootDir": ".",
+        "alwaysStrict": true,
+        "noEmitOnError": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitAny": true,
+        "noImplicitReturns": true,
+        "noImplicitThis": true
+    },
+    "exclude": [
+        "node_modules",
+        ".vscode-test"
+    ]
+}
 No newline at end of file

clangd/clients/clangd-vscode/vsc-extension-quickstart.md

+# Toy VS Code Extension for clangd
+
+## What's in the folder
+* This folder contains all of the files necessary for your extension
+* `package.json` - this is the manifest file in which you declare your extension and command.
+The sample plugin registers a command and defines its title and command name. With this information
+VS Code can show the command in the command palette. It doesn’t yet need to load the plugin.
+* `src/extension.ts` - this is the main file where you will provide the implementation of your command.
+The file exports one function, `activate`, which is called the very first time your extension is
+activated (in this case by executing the command). Inside the `activate` function we call `registerCommand`.
+We pass the function containing the implementation of the command as the second parameter to
+`registerCommand`.
+
+## Get up and running straight away
+* press `F5` to open a new window with your extension loaded
+* run your command from the command palette by pressing (`Ctrl+Shift+P` or `Cmd+Shift+P` on Mac) and typing `Hello World`
+* set breakpoints in your code inside `src/extension.ts` to debug your extension
+* find output from your extension in the debug console
+
+## Make changes
+* you can relaunch the extension from the debug toolbar after changing code in `src/extension.ts`
+* you can also reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes
+
+## Explore the API
+* you can open the full set of our API when you open the file `node_modules/vscode/vscode.d.ts`
+
+## Run tests
+* open the debug viewlet (`Ctrl+Shift+D` or `Cmd+Shift+D` on Mac) and from the launch configuration dropdown pick `Launch Tests`
+* press `F5` to run the tests in a new window with your extension loaded
+* see the output of the test result in the debug console
+* make changes to `test/extension.test.ts` or create new test files inside the `test` folder
+    * by convention, the test runner will only consider files matching the name pattern `**.test.ts`
+    * you can create folders inside the `test` folder to structure your tests any way you want
 No newline at end of file