Add Visual Studio Code documentation

docs/visual_studio_code_dev.md

+# Visual Studio Code Dev

[chaopeng, 2017/03/30 14:16:14]

Please merge this to docs/vscode.md

+
+Visual Studio Code is a free, lightweight and powerful code editor for Windows,
+Mac and Linux. It has built-in support for JavaScript, TypeScript and Node.js
+and a rich extension ecosystem that adds intellisense, debugging, syntax
+highlighting etc. for many languages (C++, Python, Go). Get started
+[here](https://code.visualstudio.com/docs).
+
+It is NOT a full-fledged IDE like Visual Studio. The two are completely
+separate products. The only commonality with Visual Studio is that both are
+from Microsoft.
+
+Here's what works well:
+
+*   Editing code works well especially when you get used to the [keyboard
+    shortcuts](https://code.visualstudio.com/docs/customization/keybindings).
+    VS Code is very responsive and can handle even big code bases like Chromium.
+*   Git integration is a blast. Built-in side-by-side view, local commit and
+    even extensions for
+    [history](https://marketplace.visualstudio.com/items?itemName=donjayamanne.githistory)
+    and
+    [blame view](https://marketplace.visualstudio.com/items?itemName=ryu1kn.annotator).
+*   [Debugging](https://code.visualstudio.com/Docs/editor/debugging) works
+    well, even though startup times can be fairly high (~40 seconds with
+    gdb on Linux, much lower on Windows). You can step through code, inspect
+    variables, view call stacks for multiple threads etc.
+*   Opening files and searching solution-wide works well now after having
+    problems in earlier versions.
+*   Building works well. Build tools are easy to integrate. Warnings and errors
+    are displayed on a separate page and you can click to jump to the
+    corresponding line of code.
+
+[TOC]
+
+## Updating This Page

[chaopeng, 2017/03/30 14:16:14]

nit: Maybe we should not add this section.

[ljusten (tachyonic), 2017/03/31 14:02:31]

I've added this because I imagine this doc will be read by many Nooglers who
might not be familiar with the check-in process. It might literally be the first
Chromium "code" they see, so I figured it would help to add this info here.

+
+Please keep this doc up-to-date. VS Code is still in active development and
+subject to changes. This doc is checked into the Chromium git repo, so if you
+make changes, you have to
+[submit a change list](https://www.chromium.org/developers/contributing-code).
+You may skip code review by adding
+```
+  TBR=<foo>@chromium.org
+```
+where <foo> should be a valid comitter (e.g. your supervisor).
+
+All file paths and commands have been tested on Linux. Windows and Mac might
+require a slightly different setup (e.g. `Ctrl` -> `Cmd`). Please update this
+page accordingly.
+
+## Setup
+
+### Installation
+
+Follow the steps on https://code.visualstudio.com/docs/setup/setup-overview.
+To run it on Linux, just navigate to the chromium/src folder and type 'code .'
+in a terminal. VS Code does not require project or solution files. However, it
+does store workspace settings in a .vscode folder in your base directory.
+
+### Useful Extensions
+
+Up to now, you have a basic version of VS Code without much language support.
+Next, we will install some useful extensions. Jump to the extensions window
+(`Ctrl+Shift+X`) and install these extensions, you will most likely use them
+every day:
+

[chaopeng, 2017/03/30 14:16:14]

Add a line for developer easier install everything by 1 copy/paste.
e.g. : `F1` - `ext install cpptools you-complete-me clang-format
chromium-codesearch`

[ljusten (tachyonic), 2017/03/31 14:02:31]

Apparently they changed the behavior and ext install is not a command anymore.
It opens the extension search window instead (also, it doesn't work with F1, but
CTRL+P). Having all search results there is kind of confusing, try CTRL+P and
ext install cpptools python chromium-codesearch toggle header/source proto
you-complete-me rewrap
It shows unrelated extensions mixed in, so I think it's better to have the user
install them one by one.

I've added chromium-codesearch, though, I didn't know that exists!

+*   ***C/C++*** -
+    Complete C/C++ language support.
+*   ***Python*** -
+    Python linting, debugging, intellisense, code formatting etc.
+*   ***Toggle Header/Source*** -
+    Toggles between .cc and .h with `F4`. The C/C++ extension supports this as
+    well `Alt+O`. Last time I checked this was very laggy, but they might have
+    improved it since, so this extension might not be necessary.
+*   ***Protobuf support*** -
+    Syntax highlighting for .proto files.
+*   ***Rewrap*** -
+    Wrap lines at 80 characters with `Alt+Q`.

[chaopeng, 2017/03/30 14:16:14]

1. Add chromium-codesearch
https://marketplace.visualstudio.com/items?itemName=chaopeng.chromium-codesearch

2. Add clang-format, this extension can format c++/js.

[ljusten (tachyonic), 2017/03/31 14:02:31]

Done.

Just noticed you wrote this extension. Nice work! Could you expose it to the
Google-internal code search as well? It would be very useful for Chromium OS and
other stuff that's only on internal code search.

+
+The following extensions might be useful for you as well:
+
+*   ***Annotator*** -
+    Git blame view.
+*   ***Git History (git log)*** -
+    Git history view.
+*   ***you-complete-me*** -
+    YouCompleteMe code completion for VS Code. I've had some luck with it in
+    Chromium. Be sure to turn off code completion and suggestions from the C/C++
+    extension.
+*   ***change-case*** -
+    Quickly change the case of the current selection or current word.
+*   ***Instant Markdown*** -
+    Markdown (.md) preview in your browser as you type. This document was
+    written with this extension!
+
+Also be sure to take a look at the
+[VS Code marketplace](https://marketplace.visualstudio.com/VSCode) to check out other
+useful extensions.
+
+### Color Scheme
+Press `Ctrl+Shift+P, color, Enter` to pick a color scheme for the editor. There
+are also tons of [color schemes available for download on the
+marketplace](https://marketplace.visualstudio.com/search?target=VSCode&category=Themes&sortBy=Downloads).
+
+### Usage Tips
+*   `Ctrl+P` opens a search box to find and open a file.
+*   `Ctrl+Shift+P` opens a search box to find a command (e.g. Tasks: Run Task).
+*   `Ctrl+K, Z` enters Zen Mode, a fullscreen editing mode with nothing but the
+    current editor visible.
+*   `Ctrl+Shift+M` and `Ctrl+~` toggles between problem view (compile
+    warnings and errors) and terminal view. This is useful during compilation.
+*   `Alt+O` switches between the source/header file.
+*   `F12` jumps to a symbol definition.
+*   `Ctrl+D` selects the word at the cursor. Pressing it multiple times
+    multi-selects the next occurrences, so typing in one types in all of them,
+    and `Ctrl+U` deselects the last occurrence.
+*   `Ctrl+X` without anything selected cuts the current line. `Ctrl+V` pastes
+    the line.
+

[chaopeng, 2017/03/30 14:16:14]

ctrl+` toggle terminal.
F1 - CodeSearchOpen open current line in code search on chrome.
F1 - CodeSearchReferences open XRef Infomation of current symbol.
Use right click menu call go to definition or peek definition.
Use right click menu call find all references.

[ljusten (tachyonic), 2017/03/31 14:02:31]

Done.

+## Setup For Chromium
+
+VS Code is configured via JSON files. This paragraph contains JSON configuration
+files that are useful for Chromium development, in particular. See [VS Code
+documentation](https://code.visualstudio.com/docs/customization/overview) for an
+introduction to VS Code customization.
+
+### Workspace Settings
+Open the file chromium/src/.vscode/settings.json and add the following settings:
+
+```
+{
+  // Default tab size of 2.
+  "editor.tabSize": 2,
+  // Do not figure out tab size from opening a file.
+  "editor.detectIndentation": false,
+  // Add a line at 80 characters.
+  "editor.rulers": [80],
+  // Optional: Highlight current line at the left of the editor.
+  "editor.renderLineHighlight": "gutter",
+  // Optional: Don't automatically add closing brackets. It gets in the way.
+  "editor.autoClosingBrackets": false,
+  // Optional: Enable a tiny 30k feet view of your doc.
+  "editor.minimap.enabled": true,
+  "editor.minimap.maxColumn": 80,

[chaopeng, 2017/03/30 14:16:14]

"editor.minimap.renderCharacters": false
This one feels better. 

[ljusten (tachyonic), 2017/03/31 14:02:31]

I agree.

+  // Trim tailing whitespace on save.
+  "files.trimTrailingWhitespace": true,
+  // Optional: Do not open files in 'preview' mode. Opening a new file in can
+  //           replace an existing one in preview mode, which can be confusing.
+  "workbench.editor.enablePreview": false,
+  // Optional: Same for files opened from quick open (Ctrl+P).
+  "workbench.editor.enablePreviewFromQuickOpen": false,
+
+  "files.associations": {
+    // Adds xml syntax highlighting for grd files.
+    "*.grd" : "xml",
+    // Optional: .gn and .gni are not JavaScript, but at least it gives some
+    // approximate syntax highlighting. Ignore the linter warnings!
+    "*.gni" : "javascript",
+    "*.gn" : "javascript"
+  },
+
+  "files.exclude": {
+    // Ignore build output folders.
+    "out*/**": true
+  },
+
+  // Wider author column for annotator extension.
+  "annotator.annotationColumnWidth": "24em",
+

[chaopeng, 2017/03/30 14:16:14]

Do you forget YCM settings here? Also please add how to install ycmd below.

[ljusten (tachyonic), 2017/03/31 14:02:31]

Added. How does use_imprecise_get_type work:true out for you? I'd rather wait
longer and get precise type information. Is there a situation where it has a
clear advantage?

Btw, don't you also have to go into vim and install ycm there?

[ljusten (tachyonic), 2017/03/31 14:02:31]

Done.

[chaopeng, 2017/03/31 14:42:19]

No, I dont install ycm in vim.

+  // C++ clang format settings.

[chaopeng, 2017/03/30 14:16:14]

Please look at Nico's comment for clang-format
https://codereview.chromium.org/2687733003/#msg11

[ljusten (tachyonic), 2017/03/31 14:02:31]

Done.

+  "C_Cpp.clang_format_path": "clang-format",
+  "C_Cpp.clang_format_style": "Chromium",
+  "C_Cpp.clang_format_fallbackStyle": "Visual Studio",
+  "C_Cpp.clang_format_sortIncludes": true,
+  "C_Cpp.clang_format_formatOnSave": true,
+}
+```
+
+### Tasks
+Next, we'll tell VS Code how to compile our code and how to read warnings and
+errors from the build output. Copy the code below to
+chromium/src/.vscode/tasks.json. This will provide 5 tasks to do basic things.
+You might have to adjust the commands to your situation and needs.
+
+```
+{
+  "version": "0.1.0",
+  "_runner": "terminal",
+  "showOutput": "always",
+  "echoCommand": true,
+  "tasks": [
+  {
+    "taskName": "1-build_chrome_debug",
+    "command": "ninja -C out/Debug -j 2000 chrome",
+    "isShellCommand": true,
+    "isTestCommand": true,
+    "problemMatcher": {
+      "owner": "cpp",
+      "fileLocation": ["relative", "${workspaceRoot}"],
+      "pattern": {
+        "regexp": "^../../(.*):(\\d+):(\\d+):\\s+(warning|\\w*\\s?error):\\s+(.*)$",
+        "file": 1, "line": 2, "column": 3, "severity": 4, "message": 5
+      }
+    }
+  },
+  {
+    "taskName": "2-build_chrome_release",
+    "command": "ninja -C out/Release -j 2000 chrome",
+    "isShellCommand": true,
+    "isBuildCommand": true,
+    "problemMatcher": {
+      "owner": "cpp",
+      "fileLocation": ["relative", "${workspaceRoot}"],
+      "pattern": {
+        "regexp": "^../../(.*):(\\d+):(\\d+):\\s+(warning|\\w*\\s?error):\\s+(.*)$",
+        "file": 1, "line": 2, "column": 3, "severity": 4, "message": 5
+      }
+    }
+  },
+  {
+    "taskName": "3-build_all_debug",
+    "command": "ninja -C out/Debug -j 2000",
+    "isShellCommand": true,
+    "problemMatcher": {
+      "owner": "cpp",
+      "fileLocation": ["relative", "${workspaceRoot}"],
+      "pattern": {
+        "regexp": "^../../(.*):(\\d+):(\\d+):\\s+(warning|\\w*\\s?error):\\s+(.*)$",
+        "file": 1, "line": 2, "column": 3, "severity": 4, "message": 5
+      }
+    }
+  },
+  {
+    "taskName": "4-build_all_release",
+    "command": "ninja -C out/Release -j 2000",
+    "isShellCommand": true,
+    "problemMatcher": {
+      "owner": "cpp",
+      "fileLocation": ["relative", "${workspaceRoot}"],
+      "pattern": {
+        "regexp": "^../../(.*):(\\d+):(\\d+):\\s+(warning|\\w*\\s?error):\\s+(.*)$",
+        "file": 1, "line": 2, "column": 3, "severity": 4, "message": 5
+      }
+    }
+  },
+  {
+    "taskName": "5-build_test_debug",
+    "command": "ninja -C out/Debug -j 2000 unit_tests components_unittests browser_tests",
+    "isShellCommand": true,
+    "problemMatcher": {
+      "owner": "cpp",
+      "fileLocation": ["relative", "${workspaceRoot}"],
+      "pattern": {
+        "regexp": "^../../(.*):(\\d+):(\\d+):\\s+(warning|\\w*\\s?error):\\s+(.*)$",
+        "file": 1, "line": 2, "column": 3, "severity": 4, "message": 5
+      }
+    }
+  }]
+}
+```
+
+### Launch Commands
+Launch commands are the equivalent of `F5` in Visual Studio: They launch some
+program or a debugger. Optionally, they can run some task defined in
+`tasks.json`. Launch commands can be run from the debug view (`Ctrl+Shift+D`).
+Copy the code below to chromium/src/.vscode/launch.json and adjust them to
+your situation and needs.
+```
+{
+  "version": "0.2.0",
+  "configurations": [
+  {
+    "name": "Chrome Debug",
+    "type": "cppdbg",
+    "request": "launch",
+    "targetArchitecture": "x64",
+    "program": "${workspaceRoot}/out/Debug/chrome",
+    "args": [],  // Optional command line args
+    "preLaunchTask": "1-build_chrome_debug",
+    "stopAtEntry": false,
+    "cwd": "${workspaceRoot}",
+    "environment": [],
+    "externalConsole": true
+  },
+  {
+    "name": "Chrome Release",
+    "type": "cppdbg",
+    "request": "launch",
+    "targetArchitecture": "x64",
+    "program": "${workspaceRoot}/out/Release/chrome",
+    "args": [],  // Optional command line args
+    "preLaunchTask": "2-build_chrome_release",
+    "stopAtEntry": false,
+    "cwd": "${workspaceRoot}",
+    "environment": [],
+    "externalConsole": true
+  },
+  {
+    "name": "Custom Test Debug",
+    "type": "cppdbg",
+    "request": "launch",
+    "targetArchitecture": "x64",
+    "program": "${workspaceRoot}/out/Debug/unit_tests",
+    "args": ["--gtest_filter=*",
+              "--single_process",
+              "--ui-test-action-max-timeout=1000000",
+              "--test-launcher-timeout=1000000"],
+    "preLaunchTask": "5-build_test_debug",
+    "stopAtEntry": false,
+    "cwd": "${workspaceRoot}",
+    "environment": [],
+    "externalConsole": true
+  },
+  {
+    "name": "Attach Debug",
+    "type": "cppdbg",
+    "request": "launch",
+    "targetArchitecture": "x64",
+    "program": "${workspaceRoot}/out/Debug/chrome",
+    "args": ["--remote-debugging-port=2224"],
+    "stopAtEntry": false,
+    "cwd": "${workspaceRoot}",
+    "environment": [],
+    "externalConsole": false
+  }]
+}
+```
+
+### Key Bindings
+To edit key bindings, press `Ctrl+K, Ctrl+S`. You'll see the defaults on the
+left and your overrides on the right. To change a key binding, copy the
+corresponding command to the right. It's fairly self-explanatory. As everything,
+key bindings are stored in a `keybindings.json` file. Here are some key bindings
+that are likely to be useful for you:
+
+```
+// Place your key bindings in this file to overwrite the defaults
+[
+// Run the task marked as "isTestCommand": true, see tasks.json.
+{ "key": "ctrl+shift+t",       "command": "workbench.action.tasks.test" },
+// Jump to the previous change in the built-in diff tool.
+{ "key": "ctrl+up",            "command": "workbench.action.compareEditor.previousChange" },
+// Jump to the next change in the built-in diff tool.
+{ "key": "ctrl+down",          "command": "workbench.action.compareEditor.nextChange" },
+// Jump to previous location in the editor (useful to get back from viewing a symbol definition).
+{ "key": "alt+left",           "command": "workbench.action.navigateBack" },
+// Jump to next location in the editor.
+{ "key": "alt+right",          "command": "workbench.action.navigateForward" },
+// Get a blame view of the current file. Requires the annotator extension.
+{ "key": "ctrl+alt+a",         "command": "annotator.annotate" },
+// Toggle header/source with the Toggle Header/Source extension (overrides the
+// key binding from the C/C++ extension as I found it to be slow).
+{ "key": "alt+o",              "command": "togglehs.toggleHS" },
+// Quickly run a task, see tasks.json. Since we named them 1-, 2- etc., it is
+// suffucient to press the corresponding number.
+{ "key": "ctrl+r",             "command": "workbench.action.tasks.runTask",
+                                  "when": "!inDebugMode" },
+// The following keybindings are useful on laptops with small keyboards such as
+// Chromebooks that don't provide all keys.
+{ "key": "shift+alt+down",     "command": "cursorColumnSelectDown",
+                                  "when": "editorTextFocus" },
+{ "key": "shift+alt+left",     "command": "cursorColumnSelectLeft",
+                                  "when": "editorTextFocus" },
+{ "key": "shift+alt+pagedown", "command": "cursorColumnSelectPageDown",
+                                  "when": "editorTextFocus" },
+{ "key": "shift+alt+pageup",   "command": "cursorColumnSelectPageUp",
+                                  "when": "editorTextFocus" },
+{ "key": "shift+alt+right",    "command": "cursorColumnSelectRight",
+                                  "when": "editorTextFocus" },
+{ "key": "shift+alt+up",       "command": "cursorColumnSelectUp",
+                                  "when": "editorTextFocus" },
+{ "key": "alt+down",           "command": "scrollPageDown",
+                                  "when": "editorTextFocus" },
+{ "key": "alt+up",             "command": "scrollPageUp",
+                                  "when": "editorTextFocus" },
+{ "key": "alt+backspace",      "command": "deleteRight",
+                                  "when": "editorTextFocus && !editorReadonly" },
+{ "key": "ctrl+right",         "command": "cursorEnd",
+                                  "when": "editorTextFocus" },
+{ "key": "ctrl+shift+right",   "command": "cursorEndSelect",
+                                  "when": "editorTextFocus" },
+{ "key": "ctrl+left",          "command": "cursorHome",
+                                  "when": "editorTextFocus" },
+{ "key": "ctrl+shift+left",    "command": "cursorHomeSelect",
+                                  "when": "editorTextFocus" },
+]
+```
+
+### Tips
+

[chaopeng, 2017/03/30 14:16:14]

Please add my battery saving settings here:
https://chromium.googlesource.com/chromium/src/+/master/docs/vscode.md#On-laptop

[ljusten (tachyonic), 2017/03/31 14:02:31]

Done.

+#### The `out` folder
+Automatically generated code is put into a subfolder of out/, which means that
+these files are ignored by VS Code (see files.exclude above) and cannot be
+opened e.g. from quick-open (`Ctrl+P`). On Linux, you can create a symlink as a
+work-around:
+```
+  cd ~/chromium/src
+  mkdir _out
+  ln -s ../out/Debug/gen _out/gen
+```
+We picked _out since it is already in .gitignore, so it won't show up in git
+status.
+
+Note: As of version 1.9, VS Code does not support negated glob commands, but
+once it does, you can use
+```
+"!out/Debug/gen/**": true
+```
+in files.exclude instead of the symlink.
+
+#### Using VS Code as git editor
+Add `[core] editor = "code --wait"` to your `~/.gitignore` file in order to use
+VS Code as editor for git commit messages etc. Note that the editor starts up
+significantly slower than nano or vim.
+

[chaopeng, 2017/03/30 14:16:14]

vscode can also be the difftool/mergetool. If you want to try, see
https://github.com/Microsoft/vscode-tips-and-tricks/blob/master/README.md

[ljusten (tachyonic), 2017/03/31 14:02:31]

Done.

+#### Task Names
+Note that we named the tasks `1-build_chrome_debug`, `2-build_chrome_release`
+etc. This allows you to quickly execute tasks by pressing their number:
+Press `Ctrl+P` and enter `task <n>`, where `<n>` is the number of the task. You
+can also create a keyboard shortcut for running a task. `File > Preferences >
+Keyboard Shortcuts` and add `{ "key": "ctrl+r", "command":
+"workbench.action.tasks.runTask", "when": "!inDebugMode" }`. Then it's
+sufficient to press `Ctrl+R` and enter `<n>`.