Moved Sublime documentation to markdown and added SublimeClang setup

docs/linux_sublime_dev.md

+# Linux Sublime Dev
+
+Sublime Text is a fast, powerful and easily extensible code editor. Check out
+some [visual demos](http://www.sublimetext.com) for a quick demonstration.
+
+You can download and install Sublime Text 3 from the [Sublime Text
+Website](http://www.sublimetext.com/3). Assuming you have access to the right
+repositories, you can also install Sublime via apt-get on Linux. Help and
+general documentation is available in the [Sublime Text 3
+Docs](http://www.sublimetext.com/docs/3/).
+
+Sublime can be used on Linux, Windows and Mac as an IDE for developing Chromium.
+Here's what works:
+
+*   Editing code works well (especially if you're used to it and get used to the
+    shortcuts).
+*   Navigating around the code works well. There are multiple ways to do this (a
+    full list of keyboard shortcuts is available for [Windows/Linux](http://docs
+    .sublimetext.info/en/latest/reference/keyboard_shortcuts_win.html) and
+    [Mac](http://docs.sublimetext.info/en/latest/reference/keyboard_shortcuts_osx.html)).
+*   Building works fairly well and it does a decent job of parsing errors so
+    that you can click and jump to the problem spot.
+
+[TOC]
+
+## Setup
+
+### Configuring Sublime
+
+All global configuration for Sublime (including installed packages) is stored in
+`~/.config/sublime-text-3` (or `%APPDATA\Sublime Text 3` on Windows, or
+`~/Library/Application Support/Sublime Text 3` on Mac). We will reference the
+Linux folder for the rest of this tutorial, but replace with your own path if
+using a different OS. If you ever want a clean install, just remove this folder.
+
+**Warning**: If you have installed a license key for a paid version Sublime
+Text, removing this folder will delete the license key, too.
+
+Most of the packages you will install will be placed in `~/.config/sublime-
+text-3/Packages/User`, where Sublime Text can detect them. You can also get to
+this folder by selecting `Preferences > Browse Packages...` (or `Sublime Text >
+Preferences > Browse Packages...` on Mac).
+
+### A short word about paths
+
+Certain packages require executables to be on your `PATH`, but Sublime gets the
+`$PATH` variable from a login shell, not an interactive session (i.e. your path
+needs to be set in `~/.bash_profile`, `~/.zprofile`, etc, not `~/.bashrc`,
+`~/.zshrc`, etc). For more info, see
+[Debugging Path Problems](http://sublimelinter.readthedocs.io/en/latest/troubleshooting.html#debugging-path-problems).
+
+### Editing Preferences
+
+Sublime configuration (including project files, key bindings, etc) is done via
+JSON files. All configurations have a Default config (usually provided with the
+program or package to document the available commands) and a User config
+(overrides the default; this is where your overrides go). For example, select
+`Preferences > Settings - Default` to see all the available settings for
+Sublime. You can override any of these in `Preferences > Settings - User`.
+
+Here are some settings that help match the Chromium style guide:
+```
+{
+  // Basic Chromium style preferences
+  "rulers": [80],
+  "tab_size": 2,
+  "trim_trailing_white_space_on_save": true,
+  "ensure_newline_at_eof_on_save": true,
+  "translate_tabs_to_spaces" : true,
+
+  // Optional, but also useful, preferences
+  "always_show_minimap_viewport": true,
+  "bold_folder_labels": true,
+  "draw_white_space": "all",
+  "enable_tab_scrolling": false,
+  "highlight_line": true,
+}
+```
+
+The settings will take effect as soon as you save the file.
+
+#### Tips
+*   `View > Side Bar > Show Open Files` will add a list of open files to the top
+    of the sidebar
+*   ``Ctrl+` `` will show the console; it shows errors and debugging output, and
+    you can run Python
+*   `View > Distractio-Free Mode` goes into fullscreen and removes Sublime's
+    header and footer
+*   `View > Layout > ...` changes the configuration of files you can open side-
+    by-side
+*   `Ctrl + P` (`Cmd + P` on Mac) quickly opens a search box to find a file or
+    definition
+*   `Alt + O` (`Alt + Cmd + Up` on Mac) switches between the source/header file
+*   `Alt + PageUp`/`Alt + PageDown` (`Alt + Cmd + Left`/`Alt + Cmd + Right` on
+    Mac) moves between tabs
+*   `F12` (`Alt + Cmd + Down` on Mac) goes to the symbol's definition
+*   With text selected, `Ctrl + D` will multi-select the next occurrance (so
+    typing in one types in all of them), and `Ctrl+U` deselects
+*   Similarly, after finding something with `Ctrl + F`, `Alt + Enter` will
+    select all occurrances of the search query, which can be multi-edited
+*   `Ctrl + X` without anything selected cuts the current line, then move to a
+    different line and `Ctrl + V` pastes it below the current line
+
+### Setting Sublime as the default Terminal editor
+
+Add `export EDITOR="subl -w"` to your `~/.bashrc` file (or similar) to open git
+commit messages, gn args, etc with Sublime Text. Since you may want to only open
+sublime when using a non-SSH session, you can wrap it in the following:
+
+```
+if [ "$SSH_CONNECTION" ]; then
+  export EDITOR='vim'
+else
+  export EDITOR='subl -w'
+fi
+```
+
+### Installing the Package Manager
+
+The Sublime Package Manager is the way most Sublime packages are installed and
+configured. You can install the package manager by following in the
+[installation instructions](https://packagecontrol.io/installation) on their
+website. Once the package manager is installed, restart Sublime.
+
+To install a package, press `Ctrl + Shift + P` and select `Package Manager:
+Install Package` (the string match is fairly leniant; you can just type
+`"instp"` and it should find it). Then type or select the package you want to
+install.
+
+#### Mac Paths Fix
+
+There is a known bug on Mac where Sublime doesn't detect the current path
+correctly. If you're using Mac, install the package `SublimeFixMacPath` to find
+the path from your `~/.bashrc` file or similar.
+
+## Making a New Project
+
+Once you have a copy of the Chromium checkout, we'll make a new Sublime project
+with the src directory as the root.
+
+To do this, create a new file `chromium.sublime-project` (or whatever name you'd
+like) in the folder above your `src/` directory, with the following contents
+(the exclude patterns are needed - Sublime can't handle indexing all of Chrome's
+files):
+
+```json
+{
+  "folders": [
+    {
+      "name": "chromium",
+      "path": "src",
+      "file_exclude_patterns":
+      [
+        "*.vcproj",
+        "*.vcxproj",
+        "*.sln",
+        "*.gitignore",
+        "*.gitmodules",
+        "*.vcxproj.*",
+      ],
+      "folder_exclude_patterns":
+      [
+        "build",
+        "out",
+        "third_party",
+        ".git",
+      ],
+    },
+    {
+      "name": "Generated Files",
+      "path": "src/out/Debug/gen",
+    },
+  ],
+}
+```
+
+If you are working on Blink, or any other third-party subproject, you can add it
+as a separate entry in the `folders` array:
+
+```json
+{
+  "name": "blink",
+  "path": "src/third_party/WebKit",
+}
+```
+
+Once you've saved the file, select `Project > Switch Project` and navigate to
+the `chromium.sublime-project` file.
+
+### Code Linting with CPPLint (Chromium only)
+
+**Note:** CPPLint enforces the Google/Chromium style guide, and hence is not
+useful on third_party projects that use another style.
+
+1.  Install the SublimeLinter package (`Ctrl + Shift + P > Install Package >
+    SublimeLinter`).
+1.  `cpplint` should be somewhere on your path so that SublimeLinter finds it.
+    depot_tools includes `cpplint.py`, but it needs to be named `cpplint`, so on
+    Linux and Mac you have to make a symlink to it:
+
+    ```shell
+    cd /path/to/depot_tools
+    ln -s cpplint.py cpplint
+    chmod a+x cpplint
+    ```
+
+1.  Install the SublimeLinter-cpplint package (`Ctrl + Shift + P > Install
+    Package > SublimeLinter-cpplint`).
+
+Now when you save a C++ file, red dots should appear next to lines that
+invalidate the style. You can change this behavior with Choose Lint Mode (`Ctrl
++ Shift + P > "lint mode"`).
+
+You can also see and navigate all the linter errors with Show All Errors (`Ctrl
++ Shift + P > "show all"`). You can also use Next Error/Previous Error (and
+their associated shortcuts) to navigate the errors. The gutter at the bottom of
+the screen shows the message for the error on the current line.
+
+You can also change the style of dot next to the line with Choose Gutter Theme
+(`Ctrl + Shift + P > "gutter"`)
+
+For a list of all preferences, see `Preferences > Package Settings >
+SublimeLinter > Settings - Default` (or `Settings - User` to edit your
+preferences).
+
+### Format Selection with Clang-Format (Chromium only)
+
+**Note:** Like CPPLint, Clang-format enforces the Google/Chromium style guide,
+and hence is not useful on third_party projects that use another style.
+
+1.  Inside `src/`, run:
+
+    ```shell
+    cd /path/to/chromium/src
+    cp buildtools/clang_format/script/clang-format-sublime.py ~/.config/sublime-text-3/Packages/User/
+    ```
+
+1. This installs a plugin that defines the command "clang\_format". You can add
+   the "clang\_format" command to `Preferences > Key Bindings - User`, e.g.:
+
+    ```json
+    [
+        { "keys": ["ctrl+shift+c"], "command": "clang_format" },
+    ]
+    ```
+
+2. Select some text and press `Ctrl + Shift + C` to format, or select no text to
+   format the entire file
+
+## Code Completion with SublimeClang (Linux Only)
+
+SublimeClang is a powerful autocompletion plugin for Sublime that uses the Clang
+static analyzer to provide real-time type and function completion and
+compilation errors on save. It works with Chromium with a script that finds and
+parses the appropriate *.ninja files to find the necessary include paths for a
+given file.
+
+**Note**: Currently, only the Linux setup of SublimeClang is working. However,
+there are instructions below for Windows/Mac which you are welcome to try -- if
+you can get them to work, please update these instructions ^_^
+
+More information on SublimeClang's functionality (including keyboard shortcuts)
+can be found on the [SublimeClang GitHub
+page](https://github.com/quarnster/SublimeClang).
+
+### Mac (not working)
+
+1.  Install cmake if you don't already have it
+1.  Install XCode
+1.  Copy libclang.dylib from XCode to the SublimeClang/internals folder:
+
+    ```shell
+    cd ~/Library/Application\ Support/Sublime\ Text\ 3/Packages
+    git clone --recursive https://github.com/quarnster/SublimeClang SublimeClang
+    cd SublimeClang
+    cp /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib internals/libclang.dylib
+    # Remove i386 from the build file since XCode's libclang.dylib is only a 64-bit version
+    sed -ie 's/CMAKE_OSX_ARCHITECTURES i386 x86_64/CMAKE_OSX_ARCHITECTURES x86_64/' src/CMakeLists.txt
+    # Copy libclang.dylib to the internals dir
+    # Make the project - should be really quick, since libclang.dylib is already built
+    cd src && mkdir build && cd build
+    cmake ..
+    make
+    ```
+
+1.  The rest of the instructions are the same, but when adding your project
+    settings, add these extra arguments to `sublimeclang_options`:
+
+    ```json
+    "sublimeclang_options":
+    [
+      ...
+      // MAC-ONLY: Include these options, replacing the paths with the correct installed SDK
+      "-isystem", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk/usr/include/",
+      "-isystem", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk/usr/include/c++/4.2.1",
+      "-F/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk/System/Library/Frameworks/",
+      "isysroot", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk",
+      "-mmacosx-version-min=10.7",
+      "-stdlib=libc++",
+      "-isystem", "/usr/include",
+      "-isystem", "/usr/include/c++/*",
+    ]
+    ```
+
+### Windows (not working)
+
+You'll need cl.exe which can be installed with [the Visual C++ Build Tools
+2015](https://blogs.msdn.microsoft.com/vcblog/2016/03/31/announcing-the-official-release-of-the-visual-c-build-tools-2015/).
+You should have cl.exe on your `$PATH`, which you can get by running `C:\Program
+Files (x86)\Microsoft Visual C++ Build Tools\Visual C++ 2015 x64 Native Build
+Tools Command Prompt`.
+
+Then you'll need a copy of libclang.so, which can be found on the [LLVM
+website](http://llvm.org/releases/download.html). The instructions should be the
+same as Linux from there.
+
+### Linux
+
+1. Install libclang-dev to get a copy of libclang.so:
+
+    ```shell
+    sudo apt-get install libclang-dev
+    ```
+
+1.  Build libclang.so and SublimeClang in your packages directory:
+
+    ```shell
+    cd ~/.config/sublime-text-3/Packages
+    git clone --recursive https://github.com/quarnster/SublimeClang SublimeClang
+    cd SublimeClang
+    # Copy libclang.so to the internals dir
+    cp $(ldconfig -p | grep libclang.so | cut -d" " -f4) internals/libclang.so
+    # Make the project - should be really quick, since libclang.so is already built
+    cd src && mkdir build && cd build
+    cmake ..
+    make
+    ```
+
+1.  Edit your project file `Project > Edit Project` to call the script above
+    (replace `out/Debug` with your out directory):
+
+    ```
+    {
+      "folders":
+      [
+        ...
+      ],
+      "settings":
+      {
+        "sublimeclang_options":
+        [
+          "-Wno-attributes",
+        ],
+        "sublimeclang_options_script": "python ${project_path}/src/tools/sublime/ninja_options_script.py ${project_path}/src ${project_path}/src/out/Debug",
+      }
+    }
+    ```
+
+1.  Restart Sublime. Now when you save a file, you should see a "Reparsing…"
+    message in the footer and errors will show up in the output panel. Also,
+    variables and function definitions should auto-complete as you type.
+
+**Note:** If you're having issues, adding `"sublimeclang_debug_options": true` to
+your settings file will print more to the console (accessed with ``Ctrl + ` ``)
+which can be helpful when debugging.
+
+## Alternative: Code Completion with Ctags
+
+For a fast way to look up symbols, we recommend installing the CTags plugin.
+
+1.  Install Exuberant Ctags and make sure that ctags is in your path:
+    http://ctags.sourceforge.net/ (on linux you should be able to just do `sudo
+    apt-get install ctags`)
+1.  Install the Ctags plugin: `Ctrl + Shift + P > Install Package > Ctags`
+
+Once installed, you'll get an entry in the context menu when you right click the
+top level folder(s) in your project that allow you to build the Ctags database.
+If you're working in a Chrome project however, do not do that at this point,
+since it will index much more than you actually want. Instead, do one of:
+
+1.  Create a batch file (e.g. ctags_builder.bat) that you can run either
+    manually or automatically after you do a gclient sync:
+
+    ```
+    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
+    ```
+
+    This takes a couple of minutes to run, but you can work while it is indexing.
+1.  Edit the `CTags.sublime-settings` file for the ctags plugin so that it runs
+    ctags with the above parameters.  Note: the above is a batch file - don't
+    simply copy all of it verbatim and paste it into the CTags settings file)
+
+Once installed, you can quickly look up symbols with `Ctrl+t, Ctrl+t` etc.  More
+information on keyboard shortcuts can be found on the [CTags GitHub
+page](https://github.com/SublimeText/CTags).
+
+One more hint - Edit your `.gitignore` file (under `%USERPROFILE%` or `~/`) so
+that git ignores the `.tags` file.  You don't want to commit it. :)
+
+If you don't have a `.gitignore` in your profile directory, you can tell git
+about it with this command: Windows: `git config --global core.excludesfile
+%USERPROFILE%\.gitignore` Mac, Linux: `git config --global core.excludesfile
+~/.gitignore`
+
+### Build a single file
+Copy the file `compile_current_file.py` to your Packages directory:
+
+```shell
+cd /path/to/chromium/src
+cp tools/sublime/compile_current_file.py ~/.config/sublime-text-3/Packages/User
+```
+
+This will give you access to a command `"compile_current_file"`, which you can
+then add to your `Preferences > Keybindings - User` file:
+
+```json
+[
+  { "keys": ["ctrl+f7"], "command": "compile_current_file", "args": {"target_build": "Debug"} },
+  { "keys": ["ctrl+shift+f7"], "command": "compile_current_file", "args": {"target_build": "Release"} },
+]
+```
+
+You can then press those key combinations to compile the current file in the
+given target build.
+
+## Building inside Sublime
+
+To build inside Sublime Text, we first have to create a new build system.
+
+You can add the build system to your project file (`Project > Edit Project`),
+replacing `out/Debug` with your output directory (on Windows, replace /'s with
+\s in `cmd` and `working_dir`):
+
+```json
+{
+  "folders": [
+  ...
+  ],
+  "build_systems":
+  [
+    {
+      "name": "Build Chrome",
+      "cmd": ["ninja", "-C", "out/Debug", "chrome"],
+      "working_dir": "${project_path}/src",
+      "file_regex": "^[.\\\\/]*([a-z]?:?[\\w.\\\\/]+)[(:]([0-9]+)[):]([0-9]+)?:?(.*)$",
+      "variants": [],
+    },
+  ],
+}
+```
+
+The file regex will allow you to click on errors to go to the error line.
+
+If you're using goma, add the -j parameter (replace out/Debug with your out directory):
+```
+    "cmd": ["ninja", "-j", "1000", "-C", "out/Debug", "chrome"],
+```
+
+**Regex explanation:** Aims to capture these two error formats while respecting
+[Sublime's perl-like group matching](http://docs.sublimetext.info/en/latest/reference/build_systems/configuration.html#build-capture-error-output):
+
+1.  `d:\src\chrome\src\base\threading\sequenced_worker_pool.cc(670): error
+    C2653: 'Foo': is not a class or namespace name`
+1.  `../../base/threading/sequenced_worker_pool.cc:670:26: error: use of
+    undeclared identifier 'Foo'`
+
+```
+"file_regex": "^[.\\\\/]*([a-z]?:?[\\w.\\\\/]+)[(:]([0-9]+)[):]([0-9]+)?:?(.*)$"
+                (   0   ) (   1  )(    2     ) (3 ) (  4 ) ( 5 ) (  6 )(7)(8 )
+
+(0) Cut relative paths (which typically are relative to the out dir and targeting src/ which is already the "working_dir")
+(1) Match a drive letter if any
+(2) Match the rest of the file
+(1)+(2) Capture the "filename group"
+(3) File name is followed by open bracket or colon before line number
+(4) Capture "line number group"
+(5) Line # is either followed by close bracket or another colon
+(6) Capture "column filename group" if any.
+(7) If (6) is non-empty there will be another colon (but can't put it inside brackets as the "column filename group" only wants digits).
+(8) Everything else until EOL is the error message.
+```
+
+### Building other targets
+
+You can add build variants to the `variants` array to have quick access to other
+build targets with `Ctrl + Shift + B`:
+
+```json
+"variants":
+  [
+    {
+      "name": "Unit Tests",
+      "cmd": ["ninja", "-j", "1000", "-C", "out/Debug", "unit_tests"],
+    },
+    {
+      "name": "Browser Tests",
+      "cmd": ["ninja", "-j", "1000", "-C", "out/Debug", "browser_tests"],
+    },
+  ]
+```
+
+You can also add a variant for running chrome, meaning you can assign a keyboard
+shortcut to run it after building:
+
+```json
+"variants":
+  [
+    ...
+    {
+      "cmd": ["out/Debug/chrome"],
+      "name": "run_chrome",
+      "shell": true,
+      "env": {
+        "CHROME_DEVEL_SANDBOX": "/usr/local/sbin/chrome-devel-sandbox",
+      },
+    },
+  ]
+```
+
+### Assigning builds to keyboard shortcuts
+
+To assign a build to a keyboard shortcut, select `Preferences > Key Bindings -
+User` (or `Key Bindings - Default` to see the current key bindings). You can add
+the build variants above with the `"build"` command, like so:
+
+```json
+[
+  ...
+  { "keys": ["ctrl+shift+u"], "command": "build", "args": {"variant": "unit_tests"} },
+  { "keys": ["ctrl+shift+b"], "command": "build", "args": {"variant": "browser_tests"} },
+  { "keys": ["ctrl+shift+x"], "command": "build", "args": {"variant": "run_chrome"} },
+]
+```
+
+For more info on custom key bindings, see the
+[Sublime Text Key Bindings Documentation](http://docs.sublimetext.info/en/latest/customization/key_bindings.html).
+
+## Other useful packages
+
+Some other useful packages that improve sublime can be installed from `Ctrl+Shift+P > Install Package`:
+
+*   Git enhancements
+    *   [Git](https://packagecontrol.io/packages/Git)
+    *   [GitCommitMsg](https://packagecontrol.io/packages/GitCommitMsg) -
+        Performs a 'git blame' for one or more lines of code with `Alt + Shift +
+        M` (`Command + Shift + M` on Mac)
+    *   [GitDiffHelper](https://packagecontrol.io/packages/GitDiffHelper) -
+        `Ctrl + Alt + G` to open all files modified since the last commit
+    *   [GitOpenChangedFiles](https://packagecontrol.io/packages/GitOpenChangedFiles) -
+        `Ctrl + Shift + O` (`Command + Shift + O` on Mac) to open all files
+        modified on the current branch
+    *   [Git Conflict
+        Resolver](https://packagecontrol.io/packages/Git%20Conflict%20Resolver)
+        - A GUI for resolving git conflicts
+    *   [GitGutter](https://packagecontrol.io/packages/GitGutter) - Shows an
+        icon next to lines that have been inserted, modified or deleted since
+        the last commit.
+*   Visual enhancements
+    *   [SyncedSideBar](https://packagecontrol.io/packages/SyncedSideBar) -
+        Syncs the currently open file with the expanded tree in the sidebar
+    *   [SideBarEnhancements](https://packagecontrol.io/packages/SideBarEnhancements) -
+        Adds more file management options to the sidebar context menu.
+    *   [SyncedSidebarBg](https://packagecontrol.io/packages/SyncedSidebarBg) -
+        A purely aesthetic improvement that syncs the sidebar background with
+        the background color for the current theme.
+    *   [Theme - Soda](http://buymeasoda.github.io/soda-theme/) - A global theme
+        for Sublime that matches the default color scheme. Needs `"theme": "Soda
+        Light 3.sublime-theme"` in your Preferences > Settings - User` file.
+*   Code navigation tools
+    *   [AutoFileName](https://packagecontrol.io/packages/AutoFileName) - Auto-
+        completes filenames in #includes
+    *   [Open-Include](https://packagecontrol.io/packagenavigations/Open-
+        Include) - Opens the file path under the cursor with `Alt + D`
+*   Text tools
+    *   [Case Conversion](https://packagecontrol.io/packages/Case%20Conversion) -
+        automatically changes the case of selected text, e.g. `kConstantName` to
+        `CONSTANT_NAME`
+    *   [Text Pastry](https://packagecontrol.io/packages/Text%20Pastry) -
+        Inserts incremental number sequences with multi-select
+    *   [Wrap Plus](https://packagecontrol.io/packages/Wrap%20Plus) - Auto-wraps
+        a comment block to 80 columns with `Alt + Q` (was used to write this
+        document! ;-)
+    *   [Diffy](https://packagecontrol.io/packages/Diffy) - With two files
+        opened side-by-side, `Ctrl + k Ctrl + d` will show the differences