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.

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

{
                                            "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"]
                                            }
                                            ]
}

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.

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:

${project_name:Default}

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

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:

See Variants.