13. Build Systems

Sublime Text comes with a beautiful and flexible subsystem to launch external programs. Because it is surrounded by information about the file you are currently editing, this framework is very convenient to use it to “do something” with the file you are editing – typically:

running it,
testing it, or
translating it into something else.

The whole concept of “building” is indeed the concept of translating something (considered source) into something else, whether it is a program or set of documents, or whatever it is.

Because this subsystem is normally used to compile (or otherwise translate) the file being edited, or the files of the current source-code project, this subsystem is referred to as the “Build System”.

For many languages, Sublime Text will also:

automatically select a Build System based on file type;
remember the last-used Build System;
search the output of the launched program and then enable the “Next Result” and “Previous Result” commands (bound to [F4] and [Shift+F4] by default) in order to place the cursor on the problematic part of the source code found by the Build System, if any;
cancel a build in progress, if requested ([Ctrl+Break] or [Ctrl+C] on Mac).

The Tools menu has a whole section dedicated to doing different things with Build Systems.

13.1. Selecting a Build System

At any time, you can tell Sublime Text what Build System you wish to use via the Tools > Build System > ... fly-out menu.

13.2. Launching a Build

You launch a build operation using Tools > Build (mapped to [Ctrl+B] by default).

When there is more than one possible Build System that applies to the file in the current View, you will be prompted to select from the options available. After selecting the Build System you want to use, hitting [Ctrl+B] will repeat the launch of last Build System chosen. To select a different one from that same list, use Tools > Build With... or [Ctrl+Shift+B].

Once launched, the output from the external program is captured and can be seen in the Build Output Overlay Panel. This text can be edited and copied from, but not saved.

13.3. Navigating Among Results

If the Build System is so configured, if there are any problems (e.g. syntax errors) found and reported during the execution of the external program, once it has completed, Sublime Text will select the first such error or warning and place your cursor on the line where the problem was found. This is where the “Next Result” and “Previous Result” Commands apply (outside of the Find in Files, a.k.a. Recursive File Searching context).

Using these Commands will open the applicable file (if it isn’t already open) and place your cursor on the applicable line, for each error or warning found in the output text.

13.4. Creating Your Own Build System

Like most things in Sublime Text, you can customize existing Build Systems as well as create your own. Tools > Build System > New Build System... creates a “skeleton” Build System (a JSON file), which you can save anywhere under a Package directory (e.g. in your User Package).

Its structure is a JSON “object” (dictionary in Python), which represents a single Build System. The minimum structure is the command line using the “cmd” or “shell_cmd” key (the latter has more features, namely piping and redirection).

{
    "cmd": ["cmd", "arg1", "arg2", "arg3"]
}

or

{
    "shell_cmd": "my_command \"$file\" | other_command"
}

With only the minimum structure, Sublime Text uses the file stem as a name in the Build System list if there are more than one applicable to the current file being edited. Example: the file Python.sublime-build will appear as “Python” in the Build System list.

Other top-level keys available are documented on this web page:

https://www.sublimetext.com/docs/build_systems.html#options

https://www.sublimetext.com/docs/build_systems.html#exec-target-options

https://www.sublimetext.com/docs/build_systems.html#custom-options

13.4.1. Variables

The following variables will be expanded within any string specified in the "cmd", "shell_cmd" or "working_dir" options.

If a literal $ needs to be specified in one of these options, it must be escaped with a . Since JSON uses backslashes for escaping also, $ will need to be written as \\$.

Please note that this substitution will occur for any <span class="key">"target"</span>. If a custom target is used, it may implement variable expansion for additional options by using sublime.expand_variables() with the result from self.window.extract_variables().

Variable	Description
$packages	The path to the Packages/ folder.
$platform	The platform Sublime Text is running on: “windows”, “osx” or “linux”.
$file	The full path, including folder, to the file in the active view.
$file_path	The path to the folder that contains the file in the active view.
$file_name	The file name (sans folder path) of the file in the active view.
$file_base_name	The file name, excluding the extension, of the file in the active view.
$file_extension	The extension of the file name of the file in the active view.
$folder	The full path to the first folder listed in the side bar.
$project	The full path to the current project file.
$project_path	The path to the folder containing the current project file.
$project_name	The file name (sans folder path) of the current project file.
$project_base_name	The file name, excluding the extension, of the current project file.
$project_extension	The extension of the current project file.