Build Systems - Configuration

Overview

The build system framework in Sublime Text tries to be flexible enough to accommodate a large number of build scenarios.

Should the default configuration options fall short for your needs, you can implement your own build system mechanism in two main ways:

  • as a custom target command (still using the default build system framework)
  • as an entirely new plugin (skipping the build system framework)

Meta Options in Build Systems

This is a list of standard options that all build systems understand. These options are used internally by Sublime Text. The target command does not receive any of these options.

target (optional)

A Sublime Text WindowCommand. Defaults to exec (Packages/Default/exec.py). This command receives all the target command arguments specified in the .sublime-build file (as **kwargs).

Used to override the default build system command. Note that if you choose to override the default command for build systems, you can add any number of extra options to the .sublime-build file.

selector (optional)
Used when Tools | Build System | Automatic is set to true. Sublime Text uses this scope selector to find the appropriate build system for the active view.
windows, osx and linux (optional)

Used to selectively apply options by OS. OS-specific values override defaults. Each of the listed items accepts a dictionary of options.

See Platform-specific Options.

variants (optional)

A list of dictionaries of options. Variant names will appear in the Command Palette for easy access if the build system’s selector matches for the active file.

Using variants it’s possible to specify multiple build system tasks in the same .sublime-build file.

See Variants.

name (optional)

Only valid inside a variant.

Identifies a build system task. If the name is ‘Run’, the variant will show up under Tools | Build System. Sublime Text will automatically bind the ‘Run’ task to Ctrl+Shift+B.

See Variants.

Target Command Arguments

Thanks to the target setting, which overrides the default exec command with any other command of your choice, a build system may contain any number of custom arguments that the new target command accepts.

See the target option.

Platform-specific Options

The windows, osx and linux elements let you provide platform-specific data in the build system. Here’s an example:

{
                                            "cmd": ["ant"],
                                            "file_regex": "^ *\\[javac\\] (.+):([0-9]+):() (.*)$",
                                            "working_dir": "${project_path:${folder}}",
                                            "selector": "source.java",
                                            "windows": {
                                            "cmd": ["ant.bat"]
                                            }
}

In this case, ant will be executed for every platform except Windows, where ant.bat will be used instead.

Variants

Here’s a contrived example of a build system with variants:

{
                                            "selector": "source.python",
                                            "cmd": ["date"],
                                            "variants": [
                                            { "name": "List Python Files",
                                            "cmd": ["ls -l *.py"],
                                            "shell": true
                                            },
                                            { "name": "Word Count (current file)",
                                            "cmd": ["wc", "$file"]
                                            },
                                            { "name": "Run",
                                            "cmd": ["python", "-u", "$file"]
                                            }
                                            ]
}

Given these settings, Ctrl+B would run the date command, Crtl+Shift+B would run the Python interpreter and the remaining variants would appear in the Command Palette as Build: name whenever the build system was active.

Capturing Build System Results

When build systems output text to a results view, it’s possible to capture results data in order to enable result navigation.

Note

Results can also mean errors. Often, build systems produce error data.

Set the following view settings in a results view if you want to enable results navigation:

result_file_regex
A Perl-style regular expression to capture up to four fields of error information from a results view, namely: filename, line number, column number and error message. Use groups in the pattern to capture this information. The filename field and the line number field are required.
result_line_regex
If result_file_regex doesn’t match but result_line_regex exists and does match on the current line, walk backwards through the buffer until a line matching result_file_regex is found, and use the two matches to determine the file and line to go to.
result_base_dir
Used to find files where results occur.

When result data is captured, you can navigate to results in your project’s files with F4 and Shift+F4. If available, the captured error message will be displayed in the status bar.

Build System Variables

Build systems expand the following variables in .sublime-build files:

$file_path The directory of the current file, e.g., C:\Files.
$file The full path to the current file, e.g., C:\Files\Chapter1.txt.
$file_name The name portion of the current file, e.g., Chapter1.txt.
$file_extension The extension portion of the current file, e.g., txt.
$file_base_name The name-only portion of the current file, e.g., Document.
$packages The full path to the Packages folder.
$project The full path to the current project file.
$project_path The directory of the current project file.
$project_name The name portion of the current project file.
$project_extension The extension portion of the current project file.
$project_base_name The name-only portion of the current project file.

Placeholders for Variables

Features found in snippets can be used with these variables. For example:

${project_name:Default}

This will emit the name of the current project if there is one, otherwise Default.

${file/\.php/\.txt/}

This will emit the full path of the current file, replacing .php with .txt.

See also

Snippets
Documentation on snippet variables.

Running Build Systems

Select the desired build system from Tools | Build System, and then select Tools | Build. Alternatively, you can use the command palette or the following key bindings:

Ctrl+B Run default build task
F7 Run default build task
Ctrl+Shift+B Run ‘Run’ build task
Ctrl+Break Cancel running build task

See Variants.