Overview of Sublime Text Sublime Text is a next-level editor that was developed specifically for coders. It includes features such as syntax highlighting, directory explorer, command palette, and extensive keystrokes shortcuts for much more efficient programming. Sublime Text IntelliJ IDEA. Use Google+ Hangouts to video chat and screen-share while editing. We also have a browser-based editor.
Sublime Text is a fast, powerful and easily extensible code editor. Check out some visual demos for a quick demonstration.
You can download and install Sublime Text 3 from the Sublime Text Website. 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.
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 and Mac).
- Building works fairly well and it does a decent job of parsing errors so that you can click and jump to the problem spot.
Setup
Configuring Sublime
All global configuration for Sublime (including installed packages) is stored in ~/.config/sublime-text-3
(or %APPDATASublime 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.
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:
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 sidebarCtrl+`
will show the console; it shows errors and debugging output, and you can run PythonView > Enter Distraction Free Mode
goes into fullscreen and removes Sublime's header and footerView > Layout > ..
changes the configuration of files you can open side- by-sideCtrl + P
(Cmd + P
on Mac) quickly opens a search box to find a file or definitionAlt + O
(Alt + Cmd + Up
on Mac) switches between the source/header fileAlt + PageUp
/Alt + PageDown
(Alt + Cmd + Left
/Alt + Cmd + Right
on Mac) moves between tabsF12
(Alt + Cmd + Down
on Mac) goes to the symbol's definition- With text selected,
Ctrl + D
will multi-select the next occurrence (so typing in one types in all of them), andCtrl+U
deselects - Similarly, after finding something with
Ctrl + F
,Alt + Enter
will select all occurrences of the search query, which can be multi-edited Ctrl + X
without anything selected cuts the current line, then move to a different line andCtrl + 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:
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 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 lenient; 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):
If you are working on Blink, or any other third-party subproject, you can add it as a separate entry in the folders
array:
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: Anti malware osx. CPPLint enforces the Google/Chromium style guide, and hence is not useful on third_party projects that use another style.
Install the SublimeLinter package (
Ctrl + Shift + P > Install Package > SublimeLinter
).cpplint
should be somewhere on your path so that SublimeLinter finds it. depot_tools includescpplint.py
, but it needs to be namedcpplint
, so on Linux and Mac you have to make a symlink to it: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.
Inside
src/
, run:This installs a plugin that defines the command 'clang_format'. You can add the 'clang_format' command to
Preferences > Key Bindings - User
, e.g.:Select some text and press
Ctrl + Shift + C
to format, or select no text to format the entire file
CodeSearch Integration with Chromium X-Refs
With Chromium X-Refs you can perform https://cs.chromium.org cross-reference searches in your editor. This gives you the call graph, overrides, references, declaration, and definition of most of the code. The results are as fresh as the search engine‘s index so uncomitted changes won't be reflected.
More information on Chromium X-Ref's functionality (including keyboard and mouse shortcuts) can be found on the Chromium X-Refs page.
Code Completion, Error Highlighting, Go-to-Definition, and Find References with LSP (clangd)
Gives Sublime Text 3 rich editing features for languages with Language Server Protocol support. It searches the current compilation unit for definitions and references and provides super fast code completion.
In this case, we're going to add C/C++ support.
Refer to clangd.md to install clangd and build a compilation database.
Install the LSP Package and enable clangd support by following the link and following the instructions for Sublime Text.
To remove sublime text's auto completion and only show LSPs (recommended), set the following LSP preference:
Code Completion with SublimeClang (Linux Only) [Deprecated, see LSP above]
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.
Linux
Note that there are recent (as of August 2017) changes to support C++14. Namely, you must use a more recent clang (3.9 is known to work), and use its resource directory instead of that supplied by SublimeClang.
Install a recent libclang-dev to get a copy of libclang.so. 3. Www audacityteam org. 4 isn't recent enough, but 3.9 works. If you use something different, change the names and paths accordingly:
Build libclang.so and SublimeClang in your packages directory:
Edit your project file
Project > Edit Project
to call the script above (replace/path/to/depot_tools
with your depot_tools directory):Edit your SublimeClang settings and set
dont_prepend_clang_includes
to true. This way you use the resource directory we set instead of the ancient ones included in the repository. Without this you won't have C++14 support.(Optional) To remove errors that sometimes show up from importing out of third_party, edit your SublimeClang settings and set:
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.
Debugging: If things don't seem to be working, the console Ctrl + `
is your friend. Here are some basic errors which have workarounds:
- Bad Libclang args
- problem:
tu is None..
is showing up repeatedly in the console: - solution: ninja_options_script.py is generating arguments that libclang can't parse properly. To fix this, make sure to
export CHROMIUM_OUT_DIR='{Default Out Directory}'
This is because the ninja_options_script.py file will use the most recently modified build directory unless specified to do otherwise. If the chosen build directory has unusual args (say for thread sanitization), libclang may fail.
- problem:
Mac (not working)
Install cmake if you don't already have it
Install XCode
Copy libclang.dylib from XCode to the SublimeClang/internals folder:
The rest of the instructions are the same, but when adding your project settings, add these extra arguments to
sublimeclang_options
:
Windows (not working)
You'll need cl.exe which can be installed with 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 ToolsVisual 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. The instructions should be the same as Linux from there.
Alternative: Code Completion with Ctags
For a fast way to look up symbols, we recommend installing the CTags plugin.
- 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
) - 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:
Create a batch file (e.g. ctags_builder.bat) that you can run either manually or automatically after you do a gclient sync:
This takes a couple of minutes to run, but you can work while it is indexing.
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.
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
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
):
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):
Regex explanation: Aims to capture these error formats while respecting Sublime's perl-like group matching:
d:srcchromesrcbasethreadingsequenced_worker_pool.cc(670): error C2653: 'Foo': is not a class or namespace name
././base/threading/sequenced_worker_pool.cc(670,26) error: use of undeclared identifier 'Foo'
././base/threading/sequenced_worker_pool.cc:670:26: error: use of undeclared identifier 'Foo'
Building other targets
You can add build variants to the variants
array to have quick access to other build targets with Ctrl + Shift + B
: 1999 unreal tournament.
You can also add a variant for running chrome, meaning you can assign a keyboard shortcut to run it after building:
More detailed stack traces
Chrome‘s default stack traces don't have full file paths so Sublime can't parse them. You can enable more detailed stack traces and use F4 to step right to the crashing line of code.
First, add print_unsymbolized_stack_traces = true
to your gn args, and make sure you have debug symbols enabled too (symbol_level = 2
). Then, pipe Chrome‘s stderr through the asan_symbolize.py script. Here's a suitable build variant for Linux (with tweaked file_regex):
You can test it by visiting chrome://crash. You should be able to step through each line in the resulting stacktrace with F4. You can also get a stack trace without crashing like so:
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:
Sublime Text 3 Download
For more info on custom key bindings, see the Sublime Text Key Bindings Documentation.
Other useful packages
Some other useful packages that improve sublime can be installed from Ctrl+Shift+P > Install Package
:
- Git enhancements
- GitCommitMsg - Performs a ‘git blame' for one or more lines of code with
Alt + Shift + M
(Command + Shift + M
on Mac) - GitDiffHelper -
Ctrl + Alt + G
to open all files modified since the last commit - GitOpenChangedFiles -
Ctrl + Shift + O
(Command + Shift + O
on Mac) to open all files modified on the current branch - Git Conflict Resolver
- A GUI for resolving git conflicts
- GitGutter - Shows an icon next to lines that have been inserted, modified or deleted since the last commit.
- GitCommitMsg - Performs a ‘git blame' for one or more lines of code with
- Visual enhancements
- SyncedSideBar - Syncs the currently open file with the expanded tree in the sidebar
- SideBarEnhancements - Adds more file management options to the sidebar context menu.
- SyncedSidebarBg - A purely aesthetic improvement that syncs the sidebar background with the background color for the current theme.
- Theme - Soda - 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 - Auto- completes filenames in #includes
- Open-Include
- Opens the file path under the cursor with
Alt + D
- Opens the file path under the cursor with
- Text tools
- Case Conversion - automatically changes the case of selected text, e.g.
kConstantName
toCONSTANT_NAME
- Text Pastry - Inserts incremental number sequences with multi-select
- Wrap Plus - Auto-wraps a comment block to 80 columns with
Alt + Q
(was used to write this document! ;-) - Diffy - With two files opened side-by-side,
Ctrl + k Ctrl + d
will show the differences
- Case Conversion - automatically changes the case of selected text, e.g.
New instructions: https://chromium.googlesource.com/chromium/src/+/master/docs/sublime_ide.mdContents
- 9 Example plugin
Contents
- 9 Example plugin
What is Sublime Text?
- Project support.
- Theme support.
- Works on Mac, Windows and Linux.
- No need to close and re-open during a
gclient sync
. - Supports many of the great editing features found in popular IDE's like Visual Studio, Eclipse and SlickEdit.
- Doesn't go to lunch while you're typing.
- The UI and keyboard shortcuts are pretty standard (e.g. saving a file is still Ctrl+S on Windows).
- It's inexpensive and you can evaluate it (fully functional) for free.
Installing Sublime Text 2
Preferences
'tab_size': 2,
Project files
'folders':
{
}
}
'folders':
{
'name': 'src',
'*.vcproj',
'*.sln',
'*.gitmodules',
],
'build',
'third_party',
'Debug',
]
]
Navigating the project
- 'Goto Anything' or Ctrl+P is how you can quickly open a file or go to a definition of a type such as a class. Just press Ctrl+P and start typing.
- Open source/header file: If you're in a header file, press Alt+O to open up the corresponding source file and vice versa. For more similar features check out the Goto->Switch File submenu.
- 'Go to definition': Right click a symbol and select 'Navigate to Definition'. A more powerful way to navigate symbols is by using the Ctags extension and use the Ctrl+T,Ctrl+T shortcut. See the section about source code indexing below.
Enable source code indexing
- Install the Sublime Package Control package: https://packagecontrol.io/installation
- 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
- Install the Ctags plugin: Ctrl+Shift+P and type 'Package Control: Install Package'
- Create a batch file (e.g. ctags_builder.bat) that you can run either manually or automatically after you do a gclient sync:This takes a couple of minutes to run, but you can work while it is indexing.
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_partyplatformsdk_win8 & ctags --languages=C++ -a -R -f .tmp_tags third_partyWebKit & move /Y .tmp_tags .tags
- 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 :-)
Windows: git config --global core.excludesfile %USERPROFILE%.gitignore
Mac, Linux: git config --global core.excludesfile ~/.gitignoreBuilding with ninja
'cmd': ['ninja', '-C', 'outDebug', 'chrome.exe'],
'file_regex': '^[./]*([a-z]?:?[w./]+)[(:]([0-9]+)[):,]([0-9]+)?[:)]?(.*)$'
Sublime Text Indent Xml
You can also add build variants so that you can also have quick access to building other targets like unit_tests or browser_tests. You build description file could look like this:
And keep using 'ctrl+b' for a regular, 'chrome.exe' build. Enjoy!
Example plugin
import subprocess
class RunLintCommand(sublime_plugin.TextCommand):
command = ['cpplint.bat', self.view.file_name()]
stdout=subprocess.PIPE,
print process.communicate()[1]
{
}
D:srccgitsrccontentbrowserbrowsing_instance.cc:69: Add #include for string [build/include_what_you_use] [4]
Done processing D:srccgitsrccontentbrowserbrowsing_instance.cc
['__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattribute__', '__hash__', '__init__', '__len__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'add_regions', 'begin_edit', 'buffer_id', 'classify', 'command_history', 'em_width', 'encoding', 'end_edit', 'erase', 'erase_regions', 'erase_status', 'extract_completions', 'extract_scope', ..
Compile current file using Ninja
As a more complex plug in example, look at the attached python file: compile_current_file.py. This plugin will compile the current file with Ninja, so will start by making sure that all this file's project depends on has been built before, and then build only that file.
First, it confirms that the file is indeed part of the current project (by making sure it's under the folder, which is taken from the self.view.window().folders() array, the first one seems to always be the project folder when one is loaded). Then it looks for the file in all the .ninja build files under the out, where must be specified as an argument to the compile_current_file command. Using the proper target for this file compilation, it starts Ninja from a background thread and send the results to the output.exec panel (the same one used by the build system of Sublime Text 2). So you can use key bindings like these two, to build the current file in either Debug or Release mode:
{ 'keys': ['ctrl+f7'], 'command': 'compile_current_file', 'args': {'target_build': 'Debug'} },
{ 'keys': ['ctrl+shift+f7'], 'command': 'compile_current_file', 'args': {'target_build': 'Release'} },
If you are having trouble with this plugin, you can set the python logging level to DEBUG in the console and see some debug output.
Format selection (or area around cursor) using clang-format
Miscellaneous tips
- To synchronize the project sidebar with the currently open file, right click in the text editor and select 'Reveal in Side Bar'. Alternatively you can install the SyncedSideBar sublime package (via the Package Manager) to have this happen automatically like in Eclipse.
- If you're used to hitting a key combination to trigger a build (e.g. Ctrl+Shift+B in Visual Studio) and would like to continue to do so, add this to your Preferences->Key Bindings - User file:
- { 'keys': ['ctrl+shift+b'], 'command': 'show_panel', 'args': {'panel': 'output.exec'} }
- Install the Open-Include plugin (Ctrl+Shift+P, type:'Install Package', type:'Open Include'). Then just put your cursor inside an #include path, hit Alt+D and voila, you're there.
- If you want to take that a step further, add an entry to the right-click context menu by creating a text file named 'context.sublime-menu' under '%APPDATA%Sublime Text 2PackagesUser' with the following content:
[ { 'command': 'open_include', 'caption': 'Open Include' } ]
- Open Command Palette (Ctrl-Shift-P)
- Type 'Package Control: Install Package' (note: given ST's string match is amazing you can just type something like 'instp' and it will find it :-)).
- Case Conversion (automatically swap casing of selected text -- works marvel with multi-select -- go from a kConstantNames to ENUM_NAMES in seconds)
- CTags (see detailed setup info above).
- Git
- Open-Include
- Text Pastry (insert incremental number sequences with multi-select, etc.)
- Wrap Plus (auto-wrap a comment block to 80 columns with Alt-Q)