Build Systems
Build systems run external programs to process your project’s files and print captured output to the output panel. Ultimately, they call subprocess.Popen.
File Format
Build systems use JSON. Here’s an example build system:
Options
cmd
-
Array containing the command to run and its desired arguments.
Note
Under Windows, GUIs are supressed.
file_regex
-
Optional. Regular expression to capture error output of
cmd.
line_regex
-
Optional. If the
file_regex doesn’t match on the current line, but there’s a
line_regex specified, and it does match the current line, then walk backwards through the buffer until a line matching the file regex is found: 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.
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).
env
-
Optional. Dictionary of environment variables to be merged with the current process’ that will be passed to
cmd.
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.
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: file name, line number, column number and error message. Use groups in the pattern to capture this information. The file name 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
windows, osx and linux are additional options which override any build system options for the corresponding platform only. Here’s an example:
In this case, ant.bat will be executed under Windows, while for the other platforms ant will be used instead.
Variables
$file The full path to the current file, e. g., C:\Files\Chapter1.txt. $file_path The directory of the current file, e. g., C:\Files. $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
Snippet style formatting can be used with these variables, for example:
This will emit the name of the current project if there is one, otherwise Default.
This will emit the full path of the current file, replacing .php with .txt.
Running Build Systems
Select Tools | Build in the Sublime Text menu or press F7.
Troubleshooting Build Systems
External programs used in build systems need to be in your PATH. As a quick test, you can try to run them from the command line first and see whether they work. However, note that your shell’s PATH variable might differ to that seen by Sublime Text due to your shell’s profile. Also, note that you can use the path option in a .build-system to specify additional directories toPATH.
See also
Managing Environment Variables in Windows
-
Search Microsoft for this topic.
Build Systems
Build systems run external programs to process your project’s files and print captured output to the output panel. Ultimately, they call subprocess.Popen.
File Format
Build systems use JSON. Here’s an example build system:
Options
-
cmd
-
Array containing the command to run and its desired arguments.
Note
Under Windows, GUIs are supressed.
file_regex
- Optional. Regular expression to capture error output of cmd. line_regex
- Optional. If the file_regex doesn’t match on the current line, but there’s a line_regex specified, and it does match the current line, then walk backwards through the buffer until a line matching the file regex is found: 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. 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). env
- Optional. Dictionary of environment variables to be merged with the current process’ that will be passed to cmd. 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.
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: file name, line number, column number and error message. Use groups in the pattern to capture this information. The file name 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
windows, osx and linux are additional options which override any build system options for the corresponding platform only. Here’s an example:
In this case, ant.bat will be executed under Windows, while for the other platforms ant will be used instead.
Variables
$file | The full path to the current file, e. g., C:\Files\Chapter1.txt. |
$file_path | The directory of the current file, e. g., C:\Files. |
$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
Snippet style formatting can be used with these variables, for example:
This will emit the name of the current project if there is one, otherwise Default.
This will emit the full path of the current file, replacing .php with .txt.
Running Build Systems
Select Tools | Build in the Sublime Text menu or press F7.
Troubleshooting Build Systems
External programs used in build systems need to be in your PATH. As a quick test, you can try to run them from the command line first and see whether they work. However, note that your shell’s PATH variable might differ to that seen by Sublime Text due to your shell’s profile. Also, note that you can use the path option in a .build-system to specify additional directories toPATH.
See also
-
Managing Environment Variables in Windows
-
Search Microsoft for this topic.