Warning

Want even better documentation for Sublime Text?

We are starting a new round of writing and editing to improve this guide in many ways. If you find it useful, please support us.

Build Systems

Build systems let you run your files through external programs without leaving Sublime Text, and see the output they generate.

Build systems consist of one –or optionally three– parts:

  • configuration data in JSON format (the .sublime-build file contents)
  • optionally, a Sublime Text command driving the build process
  • optionally, an external executable file (script, binary file)

Essentially, .sublime-build files are configuration data for an external program, as well as for a Sublime Text command (just mentioned). In them, you specify the switches, options and environment information you want forwarded.

The Sublime Text command then receives the data stored in the .sublime-build file. At this point, it can do whatever it needs to do to build the files. By default, build systems will use the exec command implemented by Packages/Default/exec.py. As explained below, you can override this command.

Finally, the external program may be a shell script you’ve created to process your files, or a well-known utility like make or tidy. Usually, these executable files will receive paths to files or directories, along with switches and options to run with.

Note that build systems can but don’t need to call external programs; a valid build system could be implemented entirely in Python in a Sublime Text command.

File Format

.build-system files use JSON. Here’s an example:

{
    "cmd": ["python", "-u", "$file"],
    "file_regex": "^[ ]*File \"(...*?)\", line ([0-9]*)",
    "selector": "source.python"
}

Options

Build system-specific options

These options are standard for all build systems.

target

Optional. Sublime Text command to run. Defaults to exec. (Packages/Default/exec.py). This command receives the full configuration data specified in the .build-system 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 arbitrary variables in 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. Allow specification of OS-specific options which will override the default settings. These accept a dict of Arbitrary options each.

See Platform-specific Options.

variants

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

See Variants.

name
Only valid inside a variant (see variants). Identifies variant build systems. If name is Run, the variant will show up under the Tools | Build System menu and be bound to Ctrl+Shift+B.

Arbitrary options

Due to the target setting a build system can contain literally any option (key) that is not one of the options already listed above.

Please note that all the options below are from the default implementation of exec (see exec command). If you change the target option, these can no longer be relied on.

cmd

Array containing the command to run and its desired arguments. If you don’t specify an absolute path, the external program will be searched in your PATH, one of your system’s environmental variables.

On Windows, GUIs are supressed.

file_regex
Optional. Regular expression (Perl-style) to capture error output of cmd. See the next section for details.
line_regex
Optional. If file_regex doesn’t match on the current line, but line_regex exists, and it does match on the current line, then walk backwards through the buffer until a line matching file regex is found, and use these two matches to determine the file and line to go to.
working_dir
Optional. Directory to change the current directory to before running cmd. The original current directory is restored afterwards.
encoding
Optional. Output encoding of cmd. Must be a valid python encoding. Defaults to utf-8.
env

Optional. Dictionary of environment variables to be merged with the current process’ before passing them to cmd.

Use this element, for example, to add or modify environment variables without modifying your system’s settings.

shell
Optional. If true, cmd will be run through the shell (cmd.exe, bash...).
path

Optional. This string will replace the current process’s PATH before calling cmd. The old PATH value will be restored after that.

Use this option to add directories to PATH without having to modify your system’s settings.

Capturing Error Output with file_regex

The file_regex option uses a Perl-style regular expression to capture up to four fields of error information from the build program’s output, 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.

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

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.

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.

Place Holders 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 snippets and their variable features.

Running Build Systems

Select the desired build system from Tools | Build System, and then select Tools | Build or press F7.

Troubleshooting Build Systems

Build systems will look for executables in your PATH, unless you specify an absolute path to the executable. Therefore, your PATH variable must be correctly set.

On some operating systems, the value for PATH will vary from a terminal window to a graphical application. Thus, even if the command you are using in your build system works in the command line, it may not work from Sublime Text. This is due to user profiles in shells.

To solve this issue, make sure you set the desired PATH so that graphical applications such as Sublime Text can find it. See the links below for more information.

Alternatively, you can use the path key in .sublime-build files to override the PATH used to locate the executable specified in cmd. This new value for PATH will only be in effect for as long as your build system is running. After that, the old PATH will be restored.

See also

Managing Environment Variables in Windows
Search Microsoft knowledge base for this topic.
Setting environment variables in OSX
StackOverflow topic.

Warning

Want even better documentation for Sublime Text?

We are starting a new round of writing and editing to improve this guide in many ways. If you find it useful, please support us.