Index: docs/visual_studio_code_dev.md |
diff --git a/docs/visual_studio_code_dev.md b/docs/visual_studio_code_dev.md |
new file mode 100644 |
index 0000000000000000000000000000000000000000..2c19930d9943a25ed7084ca632e4d07f425232d9 |
--- /dev/null |
+++ b/docs/visual_studio_code_dev.md |
@@ -0,0 +1,423 @@ |
+# 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
|
+ |
+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
ljusten (tachyonic)
2017/03/31 14:02:31
Apparently they changed the behavior and ext insta
|
+* ***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.vis
ljusten (tachyonic)
2017/03/31 14:02:31
Done.
Just noticed you wrote this extension. Nice
|
+ |
+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 c
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
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 h
ljusten (tachyonic)
2017/03/31 14:02:31
Added. How does use_imprecise_get_type work:true o
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
htt
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:
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
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>`. |