Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(2054)

Unified Diff: docs/visual_studio_code_dev.md

Issue 2710503003: Add Visual Studio Code documentation (Closed)
Patch Set: Added more documentation and polish Created 3 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
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>`.
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698