Warning

Want even better documentation for Sublime Text? You can help.

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 two—or optionally three—parts:

  • Configuration data in JSON format (the .sublime-build file contents)
  • A Sublime Text command driving the build process
  • An optional, external executable file (script or 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

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.
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.
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.
target

Optional. Sublime Text command to run. Defaults to exec (Packages/Default/exec.py). This command receives the configuration data specified in the .build-system file.

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.

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’ 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.

variants
Optional. A list of dictionaries of options to override the main build system’s options. Variant ``name``s will appear in the Command Palette for easy access if the build system’s selector matches for the active file.
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.
syntax
Optional. When provided, the build system output will be formatted with the provided syntax definition.

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": [

        { "cmd": ["ls -l *.py"],
          "name": "List Python Files",
          "shell": true
        },

        { "cmd": ["wc", "$file"],
          "name": "Word Count (current file)"
        },

        { "cmd": ["python", "-u", "$file"],
          "name": "Run"
        }
    ]
}

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 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.

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.

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 set correctly.

On some operating systems, the value of PATH may vary between terminal windows and graphical applications. Thus, in your build system, even if the command you are using 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 element in .sublime-build files to override the PATH used to locate the executable specified in cmd. This new value for PATH will be in effect only 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? You can help.