docs/sublime_ide.md

   1 # Using Sublime Text as your IDE
   2
   3 Sublime Text is a fast, powerful and easily extensible code editor. Check out
   4 some [visual demos](http://www.sublimetext.com) for a quick demonstration.
   5
   6 You can download and install Sublime Text 3 from the [Sublime Text
   7 Website](http://www.sublimetext.com/3). Assuming you have access to the right
   8 repositories, you can also install Sublime via apt-get on Linux. Help and
   9 general documentation is available in the [Sublime Text 3
  10 Docs](http://www.sublimetext.com/docs/3/).
  11
  12 Sublime can be used on Linux, Windows and Mac as an IDE for developing Chromium.
  13 Here's what works:
  14
  15 *   Editing code works well (especially if you're used to it and get used to the
  16     shortcuts).
  17 *   Navigating around the code works well. There are multiple ways to do this (a
  18     full list of keyboard shortcuts is available for [Windows/Linux](http://docs.sublimetext.info/en/latest/reference/keyboard_shortcuts_win.html)
  19     and [Mac](http://docs.sublimetext.info/en/latest/reference/keyboard_shortcuts_osx.html)).
  20 *   Building works fairly well and it does a decent job of parsing errors so
  21     that you can click and jump to the problem spot.
  22
  23 [TOC]
  24
  25 ## Setup
  26
  27 ### Configuring Sublime
  28
  29 All global configuration for Sublime (including installed packages) is stored in
  30 `~/.config/sublime-text-3` (or `%APPDATA\Sublime Text 3` on Windows, or
  31 `~/Library/Application Support/Sublime Text 3` on Mac). We will reference the
  32 Linux folder for the rest of this tutorial, but replace with your own path if
  33 using a different OS. If you ever want a clean install, just remove this folder.
  34
  35 **Warning**: If you have installed a license key for a paid version Sublime
  36 Text, removing this folder will delete the license key, too.
  37
  38 Most of the packages you will install will be placed in `~/.config/sublime-
  39 text-3/Packages/User`, where Sublime Text can detect them. You can also get to
  40 this folder by selecting `Preferences > Browse Packages...` (or `Sublime Text >
  41 Preferences > Browse Packages...` on Mac).
  42
  43 ### A short word about paths
  44
  45 Certain packages require executables to be on your `PATH`, but Sublime gets the
  46 `$PATH` variable from a login shell, not an interactive session (i.e. your path
  47 needs to be set in `~/.bash_profile`, `~/.zprofile`, etc, not `~/.bashrc`,
  48 `~/.zshrc`, etc). For more info, see
  49 [Debugging Path Problems](http://sublimelinter.readthedocs.io/en/latest/troubleshooting.html#debugging-path-problems).
  50
  51 ### Editing Preferences
  52
  53 Sublime configuration (including project files, key bindings, etc) is done via
  54 JSON files. All configurations have a Default config (usually provided with the
  55 program or package to document the available commands) and a User config
  56 (overrides the default; this is where your overrides go). For example, select
  57 `Preferences > Settings - Default` to see all the available settings for
  58 Sublime. You can override any of these in `Preferences > Settings - User`.
  59
  60 Here are some settings that help match the Chromium style guide:
  61 ```
  62 {
  63   // Basic Chromium style preferences
  64   "rulers": [80],
  65   "tab_size": 2,
  66   "trim_trailing_white_space_on_save": true,
  67   "ensure_newline_at_eof_on_save": true,
  68   "translate_tabs_to_spaces" : true,
  69
  70   // Optional, but also useful, preferences
  71   "always_show_minimap_viewport": true,
  72   "bold_folder_labels": true,
  73   "draw_white_space": "all",
  74   "enable_tab_scrolling": false,
  75   "highlight_line": true,
  76
  77   // Mainly for Windows, but harmless on Mac/Linux
  78   "default_line_ending": "unix",
  79 }
  80 ```
  81
  82 The settings will take effect as soon as you save the file.
  83
  84 #### Tips
  85 *   `View > Side Bar > Show Open Files` will add a list of open files to the top
  86     of the sidebar
  87 *   ``Ctrl+` `` will show the console; it shows errors and debugging output, and
  88     you can run Python
  89 *   `View > Enter Distraction Free Mode` goes into fullscreen and removes
  90     Sublime's header and footer
  91 *   `View > Layout > ...` changes the configuration of files you can open side-
  92     by-side
  93 *   `Ctrl + P` (`Cmd + P` on Mac) quickly opens a search box to find a file or
  94     definition
  95 *   `Alt + O` (`Alt + Cmd + Up` on Mac) switches between the source/header file
  96 *   `Alt + PageUp`/`Alt + PageDown` (`Alt + Cmd + Left`/`Alt + Cmd + Right` on
  97     Mac) moves between tabs
  98 *   `F12` (`Alt + Cmd + Down` on Mac) goes to the symbol's definition
  99 *   With text selected, `Ctrl + D` will multi-select the next occurrence (so
 100     typing in one types in all of them), and `Ctrl+U` deselects
 101 *   Similarly, after finding something with `Ctrl + F`, `Alt + Enter` will
 102     select all occurrences of the search query, which can be multi-edited
 103 *   `Ctrl + X` without anything selected cuts the current line, then move to a
 104     different line and `Ctrl + V` pastes it below the current line
 105
 106 ### Setting Sublime as the default Terminal editor
 107
 108 Add `export EDITOR="subl -w"` to your `~/.bashrc` file (or similar) to open git
 109 commit messages, gn args, etc with Sublime Text. Since you may want to only open
 110 sublime when using a non-SSH session, you can wrap it in the following:
 111
 112 ```
 113 if [ "$SSH_CONNECTION" ]; then
 114   export EDITOR='vim'
 115 else
 116   export EDITOR='subl -w'
 117 fi
 118 ```
 119
 120 ### Installing the Package Manager
 121
 122 The Sublime Package Manager is the way most Sublime packages are installed and
 123 configured. You can install the package manager by following in the
 124 [installation instructions](https://packagecontrol.io/installation) on their
 125 website. Once the package manager is installed, restart Sublime.
 126
 127 To install a package, press `Ctrl + Shift + P` and select `Package Manager:
 128 Install Package` (the string match is fairly lenient; you can just type
 129 `"instp"` and it should find it). Then type or select the package you want to
 130 install.
 131
 132 #### Mac Paths Fix
 133
 134 There is a known bug on Mac where Sublime doesn't detect the current path
 135 correctly. If you're using Mac, install the package `SublimeFixMacPath` to find
 136 the path from your `~/.bashrc` file or similar.
 137
 138 ## Making a New Project
 139
 140 Once you have a copy of the Chromium checkout, we'll make a new Sublime project
 141 with the src directory as the root.
 142
 143 To do this, create a new file `chromium.sublime-project` (or whatever name you'd
 144 like) in the folder above your `src/` directory, with the following contents
 145 (the exclude patterns are needed - Sublime can't handle indexing all of Chrome's
 146 files):
 147
 148 ```json
 149 {
 150   "folders": [
 151     {
 152       "name": "chromium",
 153       "path": "src",
 154       "file_exclude_patterns":
 155       [
 156         "*.vcproj",
 157         "*.vcxproj",
 158         "*.sln",
 159         "*.gitignore",
 160         "*.gitmodules",
 161         "*.vcxproj.*",
 162       ],
 163       "folder_exclude_patterns":
 164       [
 165         "build",
 166         "out",
 167         "third_party",
 168         ".git",
 169       ],
 170     },
 171     {
 172       "name": "Generated Files",
 173       "path": "src/out/Debug/gen",
 174     },
 175   ],
 176 }
 177 ```
 178
 179 If you are working on Blink, or any other third-party subproject, you can add it
 180 as a separate entry in the `folders` array:
 181
 182 ```json
 183 {
 184   "name": "blink",
 185   "path": "src/third_party/blink",
 186 }
 187 ```
 188
 189 Once you've saved the file, select `Project > Switch Project` and navigate to
 190 the `chromium.sublime-project` file.
 191
 192 ### Code Linting with CPPLint (Chromium only)
 193
 194 **Note:** CPPLint enforces the Google/Chromium style guide, and hence is not
 195 useful on third_party projects that use another style.
 196
 197 1.  Install the SublimeLinter package (`Ctrl + Shift + P > Install Package >
 198     SublimeLinter`).
 199 1.  `cpplint` should be somewhere on your path so that SublimeLinter finds it.
 200     depot_tools includes `cpplint.py`, but it needs to be named `cpplint`, so on
 201     Linux and Mac you have to make a symlink to it:
 202
 203     ```shell
 204     cd /path/to/depot_tools
 205     ln -s cpplint.py cpplint
 206     chmod a+x cpplint
 207     ```
 208
 209 1.  Install the SublimeLinter-cpplint package (`Ctrl + Shift + P > Install
 210     Package > SublimeLinter-cpplint`).
 211
 212 Now when you save a C++ file, red dots should appear next to lines that
 213 invalidate the style. You can change this behavior with Choose Lint Mode
 214 (`Ctrl + Shift + P > "lint mode"`).
 215
 216 You can also see and navigate all the linter errors with Show All Errors
 217 (`Ctrl + Shift + P > "show all"`). You can also use Next Error/Previous Error
 218 (and their associated shortcuts) to navigate the errors. The gutter at the
 219 bottom of the screen shows the message for the error on the current line.
 220
 221 You can also change the style of dot next to the line with Choose Gutter Theme
 222 (`Ctrl + Shift + P > "gutter"`)
 223
 224 For a list of all preferences, see `Preferences > Package Settings >
 225 SublimeLinter > Settings - Default` (or `Settings - User` to edit your
 226 preferences).
 227
 228 ### Format Selection with Clang-Format (Chromium only)
 229
 230 **Note:** Like CPPLint, Clang-format enforces the Google/Chromium style guide,
 231 and hence is not useful on third_party projects that use another style.
 232
 233 1.  Inside `src/`, run:
 234
 235     ```shell
 236     cd /path/to/chromium/src
 237     cp buildtools/clang_format/script/clang-format-sublime.py ~/.config/sublime-text-3/Packages/User/
 238     ```
 239
 240 1. This installs a plugin that defines the command "clang\_format". You can add
 241    the "clang\_format" command to `Preferences > Key Bindings - User`, e.g.:
 242
 243     ```json
 244     [
 245         { "keys": ["ctrl+shift+c"], "command": "clang_format" },
 246     ]
 247     ```
 248
 249 2. Select some text and press `Ctrl + Shift + C` to format, or select no text to
 250    format the entire file
 251
 252 ## CodeSearch Integration with Chromium X-Refs
 253
 254 With [Chromium X-Refs](https://github.com/karlinjf/ChromiumXRefs/) you can
 255 perform [https://cs.chromium.org](https://cs.chromium.org) cross-reference
 256 searches in your editor. This gives you the call graph, overrides, references,
 257 declaration, and definition of most of the code. The results are as fresh as
 258 the search engine's index so uncomitted changes won't be reflected.
 259
 260 More information on Chromium X-Ref's functionality (including keyboard and
 261 mouse shortcuts) can be found on the [Chromium X-Refs
 262 page](https://github.com/karlinjf/ChromiumXRefs/).
 263
 264
 265 ## Code Completion, Error Highlighting, Go-to-Definition, and Find References with LSP (clangd)
 266
 267 Gives Sublime Text 3 rich editing features for languages with Language Server
 268 Protocol support. It searches the current compilation unit for definitions and
 269 references and provides super fast code completion.
 270
 271 In this case, we're going to add C/C++ support.
 272
 273 1. Refer to [clangd.md](clangd.md) to install clangd and build a compilation
 274    database.
 275
 276 1. Install the [LSP Package](https://github.com/tomv564/LSP) and enable clangd
 277    support by following the [link](https://clang.llvm.org/extra/clangd/Installation.html#editor-plugins)
 278    and following the instructions for Sublime Text.
 279
 280 To remove sublime text's auto completion and only show LSPs (recommended), set
 281 the following LSP preference:
 282
 283 ```json
 284 "only_show_lsp_completions": true
 285 ```
 286
 287 ## Code Completion with SublimeClang (Linux Only) [Deprecated, see LSP above]
 288
 289 SublimeClang is a powerful autocompletion plugin for Sublime that uses the Clang
 290 static analyzer to provide real-time type and function completion and
 291 compilation errors on save. It works with Chromium with a script that finds and
 292 parses the appropriate \*.ninja files to find the necessary include paths for a
 293 given file.
 294
 295 **Note**: Currently, only the Linux setup of SublimeClang is working. However,
 296 there are instructions below for Windows/Mac which you are welcome to try -- if
 297 you can get them to work, please update these instructions ^\_^
 298
 299 More information on SublimeClang's functionality (including keyboard shortcuts)
 300 can be found on the [SublimeClang GitHub
 301 page](https://github.com/quarnster/SublimeClang).
 302
 303
 304 ### Linux
 305
 306 **Note** that there are recent (as of August 2017) changes to support C++14.
 307 Namely, you must use a more recent clang (3.9 is known to work), and use its
 308 resource directory instead of that supplied by SublimeClang.
 309
 310 1. Install a recent libclang-dev to get a copy of libclang.so. 3.4 isn't
 311    recent enough, but 3.9 works. If you use something different, change the
 312    names and paths accordingly:
 313
 314     ```shell
 315     sudo apt-get install libclang-3.9-dev
 316     ```
 317
 318 1.  Build libclang.so and SublimeClang in your packages directory:
 319
 320     ```shell
 321     cd ~/.config/sublime-text-3/Packages
 322     git clone --recursive https://github.com/quarnster/SublimeClang SublimeClang
 323     cd SublimeClang
 324     # Copy libclang.so to the internals dir
 325     cp /usr/lib/llvm-3.9/lib/libclang.so.1 internals/libclang.so
 326     # Fix src/main.cpp (shared_ptr -> std::shared_ptr)
 327     sed -i -- 's/shared_ptr/std::shared_ptr/g' src/main.cpp
 328     # Make the project - should be really quick, since libclang.so is already built
 329     cd src && mkdir build && cd build
 330     cmake ..
 331     make
 332     ```
 333
 334 1.  Edit your project file `Project > Edit Project` to call the script above
 335     (replace `/path/to/depot_tools` with your depot_tools directory):
 336
 337     ```json
 338     {
 339       "folders":
 340       [
 341         ...
 342       ],
 343       "settings":
 344       {
 345         "sublimeclang_options":
 346         [
 347           "-Wno-attributes",
 348           "-resource-dir=/usr/lib/llvm-3.9/lib/clang/3.9.1",
 349         ],
 350         "sublimeclang_options_script": "python ${project_path}/src/tools/sublime/ninja_options_script.py -d '/path/to/depot_tools'",
 351       }
 352     }
 353     ```
 354 1. Edit your SublimeClang settings and set `dont_prepend_clang_includes` to
 355    true. This way you use the resource directory we set instead of the ancient
 356    ones included in the repository. Without this you won't have C++14 support.
 357
 358 1. (Optional) To remove errors that sometimes show up from importing out of
 359    third_party, edit your SublimeClang settings and set:
 360
 361    ```json
 362    "diagnostic_ignore_dirs":
 363    [
 364      "${project_path}/src/third_party/"
 365    ],
 366    ```
 367
 368 1.  Restart Sublime. Now when you save a file, you should see a "Reparsing…"
 369     message in the footer and errors will show up in the output panel. Also,
 370     variables and function definitions should auto-complete as you type.
 371
 372 **Note:** If you're having issues, adding `"sublimeclang_debug_options": true` to
 373 your settings file will print more to the console (accessed with ``Ctrl + ` ``)
 374 which can be helpful when debugging.
 375
 376 **Debugging:** If things don't seem to be working, the console ``Ctrl + ` `` is
 377 your friend. Here are some basic errors which have workarounds:
 378
 379 1. Bad Libclang args
 380     - *problem:* ```tu is None...``` is showing up repeatedly in the console:
 381     - *solution:* ninja_options_script.py is generating arguments that libclang
 382     can't parse properly. To fix this, make sure to
 383     ```export CHROMIUM_OUT_DIR="{Default Out Directory}"```
 384     This is because the ninja_options_script.py file will use the most recently
 385     modified build directory unless specified to do otherwise. If the chosen
 386     build directory has unusual args (say for thread sanitization), libclang may
 387     fail.
 388
 389
 390 ### Mac (not working)
 391
 392 1.  Install cmake if you don't already have it
 393 1.  Install XCode
 394 1.  Copy libclang.dylib from XCode to the SublimeClang/internals folder:
 395
 396     ```shell
 397     cd ~/Library/Application\ Support/Sublime\ Text\ 3/Packages
 398     git clone --recursive https://github.com/quarnster/SublimeClang SublimeClang
 399     cd SublimeClang
 400     cp /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib internals/libclang.dylib
 401     # Remove i386 from the build file since XCode's libclang.dylib is only a 64-bit version
 402     sed -ie 's/CMAKE_OSX_ARCHITECTURES i386 x86_64/CMAKE_OSX_ARCHITECTURES x86_64/' src/CMakeLists.txt
 403     # Copy libclang.dylib to the internals dir
 404     # Make the project - should be really quick, since libclang.dylib is already built
 405     cd src && mkdir build && cd build
 406     cmake ..
 407     make
 408     ```
 409
 410 1.  The rest of the instructions are the same, but when adding your project
 411     settings, add these extra arguments to `sublimeclang_options`:
 412
 413     ```json
 414     "sublimeclang_options":
 415     [
 416       ...
 417       // MAC-ONLY: Include these options, replacing the paths with the correct installed SDK
 418       "-isystem", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk/usr/include/",
 419       "-isystem", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk/usr/include/c++/4.2.1",
 420       "-F/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk/System/Library/Frameworks/",
 421       "isysroot", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk",
 422       "-mmacosx-version-min=10.7",
 423       "-stdlib=libc++",
 424       "-isystem", "/usr/include",
 425       "-isystem", "/usr/include/c++/*",
 426     ]
 427     ```
 428
 429 ### Windows (not working)
 430
 431 You'll need cl.exe which can be installed with [the Visual C++ Build Tools
 432 2015](https://blogs.msdn.microsoft.com/vcblog/2016/03/31/announcing-the-official-release-of-the-visual-c-build-tools-2015/).
 433 You should have cl.exe on your `$PATH`, which you can get by running `C:\Program
 434 Files (x86)\Microsoft Visual C++ Build Tools\Visual C++ 2015 x64 Native Build
 435 Tools Command Prompt`.
 436
 437 Then you'll need a copy of libclang.so, which can be found on the [LLVM
 438 website](http://llvm.org/releases/download.html). The instructions should be the
 439 same as Linux from there.
 440
 441 ## Alternative: Code Completion with Ctags
 442
 443 For a fast way to look up symbols, we recommend installing the CTags plugin.
 444
 445 1.  Install Exuberant Ctags and make sure that ctags is in your path:
 446     http://ctags.sourceforge.net/ (on linux you should be able to just do `sudo
 447     apt-get install ctags`)
 448 1.  Install the Ctags plugin: `Ctrl + Shift + P > Install Package > Ctags`
 449
 450 Once installed, you'll get an entry in the context menu when you right click the
 451 top level folder(s) in your project that allow you to build the Ctags database.
 452 If you're working in a Chrome project however, do not do that at this point,
 453 since it will index much more than you actually want. Instead, do one of:
 454
 455 1.  Create a batch file (e.g. ctags_builder.bat) that you can run either
 456     manually or automatically after you do a gclient sync:
 457
 458     ```
 459     ctags --languages=C++ --exclude=third_party --exclude=.git --exclude=build --exclude=out -R -f .tmp_tags & ctags --languages=C++ -a -R -f .tmp_tags third_party\platformsdk_win7 & move /Y .tmp_tags .tags
 460     ```
 461
 462     This takes a couple of minutes to run, but you can work while it is indexing.
 463 1.  Edit the `CTags.sublime-settings` file for the ctags plugin so that it runs
 464     ctags with the above parameters.  Note: the above is a batch file - don't
 465     simply copy all of it verbatim and paste it into the CTags settings file)
 466
 467 Once installed, you can quickly look up symbols with `Ctrl+t, Ctrl+t` etc.  More
 468 information on keyboard shortcuts can be found on the [CTags GitHub
 469 page](https://github.com/SublimeText/CTags).
 470
 471 One more hint - Edit your `.gitignore` file (under `%USERPROFILE%` or `~/`) so
 472 that git ignores the `.tags` file.  You don't want to commit it. :)
 473
 474 If you don't have a `.gitignore` in your profile directory, you can tell git
 475 about it with this command: Windows: `git config --global core.excludesfile
 476 %USERPROFILE%\.gitignore` Mac, Linux: `git config --global core.excludesfile
 477 ~/.gitignore`
 478
 479 ## Building inside Sublime
 480
 481 To build inside Sublime Text, we first have to create a new build system.
 482
 483 You can add the build system to your project file (`Project > Edit Project`),
 484 replacing `out/Debug` with your output directory (on Windows, replace /'s with
 485 \s in `cmd` and `working_dir`):
 486
 487 ```json
 488 {
 489   "folders": [
 490   ...
 491   ],
 492   "build_systems":
 493   [
 494     {
 495       "name": "Build Chrome",
 496       "cmd": ["ninja", "-C", "out/Debug", "chrome"],
 497       "working_dir": "${project_path}/src",
 498       "file_regex": "^[.\\\\/]*([a-z]?:?[\\w.\\\\/]+)[(:]([0-9]+)[,:]?([0-9]+)?[)]?:(.*)$",
 499       "variants": [],
 500     },
 501   ],
 502 }
 503 ```
 504
 505 The file regex will allow you to click on errors to go to the error line.
 506
 507 If you're using goma, add the -j parameter (replace out/Debug with your out directory):
 508 ```
 509     "cmd": ["ninja", "-j", "1000", "-C", "out/Debug", "chrome"],
 510 ```
 511
 512 **Regex explanation:** Aims to capture these error formats while respecting
 513 [Sublime's perl-like group matching](http://docs.sublimetext.info/en/latest/reference/build_systems/configuration.html#build-capture-error-output):
 514
 515 1.  `d:\src\chrome\src\base\threading\sequenced_worker_pool.cc(670): error
 516     C2653: 'Foo': is not a class or namespace name`
 517 1.  `../../base/threading/sequenced_worker_pool.cc(670,26) error: use of
 518     undeclared identifier 'Foo'`
 519 1.  `../../base/threading/sequenced_worker_pool.cc:670:26: error: use of
 520     undeclared identifier 'Foo'`
 521
 522 ```
 523 "file_regex": "^[.\\\\/]*([a-z]?:?[\\w.\\\\/]+)[(:]([0-9]+)[,:]?([0-9]+)?[)]?:(.*)$"
 524                 (   0   ) (   1  )(    2     ) (3 )(  4   )( 5 )(   6   )(7 ) (8 )
 525
 526 (0) Cut relative paths (which typically are relative to the out dir and targeting src/ which is already the "working_dir")
 527 (1) Match a drive letter if any
 528 (2) Match the rest of the file
 529 (1)+(2) Capture the "filename group"
 530 (3) File name is followed by open bracket or colon before line number
 531 (4) Capture "line number group"
 532 (5) If (6) is non-empty there will be a comma or colon preceding it (but can't put it inside brackets as the "column number group" only wants digits).
 533 (6) Capture "column number group" if any
 534 (7) Closing bracket of either "(line)" or "(line,column)" if bracket syntax is in effect
 535 (8) Everything else until EOL is the error message.
 536 ```
 537
 538 ### Building other targets
 539
 540 You can add build variants to the `variants` array to have quick access to other
 541 build targets with `Ctrl + Shift + B`:
 542
 543 ```json
 544 "variants":
 545   [
 546     {
 547       "name": "Unit Tests",
 548       "cmd": ["ninja", "-j", "1000", "-C", "out/Debug", "unit_tests"],
 549     },
 550     {
 551       "name": "Browser Tests",
 552       "cmd": ["ninja", "-j", "1000", "-C", "out/Debug", "browser_tests"],
 553     },
 554     {
 555       "name": "Current file",
 556       "cmd": ["compile_single_file", "--build-dir", "out/Debug", "--file-path", "$file"],
 557     },
 558   ]
 559 ```
 560
 561 You can also add a variant for running chrome, meaning you can assign a keyboard
 562 shortcut to run it after building:
 563
 564 ```json
 565 "variants":
 566   [
 567     ...
 568     {
 569       "cmd": ["out/Debug/chrome"],
 570       "name": "run_chrome",
 571       "shell": true,
 572       "env": {
 573         "CHROME_DEVEL_SANDBOX": "/usr/local/sbin/chrome-devel-sandbox",
 574       },
 575     },
 576   ]
 577 ```
 578
 579 ### More detailed stack traces
 580
 581 Chrome's default stack traces don't have full file paths so Sublime can't
 582 parse them. You can enable more detailed stack traces and use F4 to step right
 583 to the crashing line of code.
 584
 585 First, add `print_unsymbolized_stack_traces = true` to your gn args, and make
 586 sure you have debug symbols enabled too (`symbol_level = 2`). Then, pipe
 587 Chrome's stderr through the asan_symbolize.py script. Here's a suitable build
 588 variant for Linux (with tweaked file_regex):
 589
 590 ```json
 591 {
 592   "name": "Build and run with asan_symbolize",
 593   "cmd": "ninja -j 1000 -C out/Debug chrome && out/Debug/chrome 2>&1 | ./tools/valgrind/asan/asan_symbolize.py",
 594   "shell": true,
 595   "file_regex": "(?:^|[)] )[.\\\\/]*([a-z]?:?[\\w.\\\\/]+)[(:]([0-9]+)[,:]?([0-9]+)?[)]?:?(.*)$"
 596 }
 597 ```
 598
 599 You can test it by visiting chrome://crash. You should be able to step through
 600 each line in the resulting stacktrace with F4. You can also get a stack trace
 601 without crashing like so:
 602
 603 ```c++
 604 #include "base/debug/stack_trace.h"
 605 [...]
 606 base::debug::StackTrace().Print();
 607 ```
 608
 609 ### Assigning builds to keyboard shortcuts
 610
 611 To assign a build to a keyboard shortcut, select `Preferences > Key Bindings -
 612 User` (or `Key Bindings - Default` to see the current key bindings). You can add
 613 the build variants above with the `"build"` command, like so:
 614
 615 ```json
 616 [
 617   ...
 618   { "keys": ["ctrl+shift+u"], "command": "build", "args": {"variant": "unit_tests"} },
 619   { "keys": ["ctrl+shift+b"], "command": "build", "args": {"variant": "browser_tests"} },
 620   { "keys": ["ctrl+shift+x"], "command": "build", "args": {"variant": "run_chrome"} },
 621 ]
 622 ```
 623
 624 For more info on custom key bindings, see the
 625 [Sublime Text Key Bindings Documentation](http://docs.sublimetext.info/en/latest/customization/key_bindings.html).
 626
 627 ## Other useful packages
 628
 629 Some other useful packages that improve sublime can be installed from `Ctrl+Shift+P > Install Package`:
 630
 631 *   Git enhancements
 632     *   [Git](https://packagecontrol.io/packages/Git)
 633     *   [GitCommitMsg](https://packagecontrol.io/packages/GitCommitMsg) -
 634         Performs a 'git blame' for one or more lines of code with `Alt + Shift +
 635         M` (`Command + Shift + M` on Mac)
 636     *   [GitDiffHelper](https://packagecontrol.io/packages/GitDiffHelper) -
 637         `Ctrl + Alt + G` to open all files modified since the last commit
 638     *   [GitOpenChangedFiles](https://packagecontrol.io/packages/GitOpenChangedFiles) -
 639         `Ctrl + Shift + O` (`Command + Shift + O` on Mac) to open all files
 640         modified on the current branch
 641     *   [Git Conflict
 642         Resolver](https://packagecontrol.io/packages/Git%20Conflict%20Resolver)
 643         - A GUI for resolving git conflicts
 644     *   [GitGutter](https://packagecontrol.io/packages/GitGutter) - Shows an
 645         icon next to lines that have been inserted, modified or deleted since
 646         the last commit.
 647 *   Visual enhancements
 648     *   [SyncedSideBar](https://packagecontrol.io/packages/SyncedSideBar) -
 649         Syncs the currently open file with the expanded tree in the sidebar
 650     *   [SideBarEnhancements](https://packagecontrol.io/packages/SideBarEnhancements) -
 651         Adds more file management options to the sidebar context menu.
 652     *   [SyncedSidebarBg](https://packagecontrol.io/packages/SyncedSidebarBg) -
 653         A purely aesthetic improvement that syncs the sidebar background with
 654         the background color for the current theme.
 655     *   [Theme - Soda](http://buymeasoda.github.io/soda-theme/) - A global theme
 656         for Sublime that matches the default color scheme. Needs `"theme": "Soda
 657         Light 3.sublime-theme"` in your Preferences > Settings - User` file.
 658 *   Code navigation tools
 659     *   [AutoFileName](https://packagecontrol.io/packages/AutoFileName) - Auto-
 660         completes filenames in #includes
 661     *   [Open-Include](https://packagecontrol.io/packagenavigations/Open-Include)
 662         - Opens the file path under the cursor with `Alt + D`
 663 *   Text tools
 664     *   [Case Conversion](https://packagecontrol.io/packages/Case%20Conversion) -
 665         automatically changes the case of selected text, e.g. `kConstantName` to
 666         `CONSTANT_NAME`
 667     *   [Text Pastry](https://packagecontrol.io/packages/Text%20Pastry) -
 668         Inserts incremental number sequences with multi-select
 669     *   [Wrap Plus](https://packagecontrol.io/packages/Wrap%20Plus) - Auto-wraps
 670         a comment block to 80 columns with `Alt + Q` (was used to write this
 671         document! ;-)
 672     *   [Diffy](https://packagecontrol.io/packages/Diffy) - With two files
 673         opened side-by-side, `Ctrl + k Ctrl + d` will show the differences