Build Systems

Sublime Text is able to run build programs such as 'make', either when a key in pressed (F7 by default), or when a file is saved.

The build system to use can be select from the Tools/Build System menu. If a project is open, the selected build system will be remembered for the project.

Adding a new Build System

The contents of the Tools/Build System menu is found by enumerating all of the .sublime-build files under the packages directory, which can be accessed via Preferences/Browse Packages. .sublime-build files are a simple key-value, text based format. A simple example is:

build make
lineNumberRegex ^(...*?):([0-9]*):?([0-9]*)
showWhenFinished true
workingDir $ProjectDir

There are four keys of interested here: 'build', 'lineNumberRegex', 'showWhenFinished', 'workingDir'. The meaning of these is:

• build: This is the system command to run. In the above example, it's simply 'make'. This is the same as opening up a command prompt and typing 'make'. This is the only required key.
• lineNumberRegex: This is used to map the output from the build command into build errors, enabling you to press F4 to go to the next build error. The regex should have from one to three captures: the first gives the filename, the second the line number, and the third the column. lineNumberRegex is optional.
• showWhenFinished: If true, then a line similar to [Finished in 1.029 seconds] will be appended to the build output. If not specified, it defaults to true.
• workingDir: If given, the current directory will be changed to this before running the command. File names identified by lineNumberRegex will be assumed to be relative to this directory.

Another, even simpler example:

build "C:\Program Files\SomeApp\SomeApp.exe" "$File"

This will launch SomeApp.exe with the current file as a command line argument.

Variable Substitution

In the above examples, you may have noticed a few variables being used: $ProjectDir in the first example, and $File in the second. The full list of these is:

• $File: The full path to the current file, e.g., C:\Files\Chapter1.txt
• $FileDir: The directory of the current file, e.g., C:\Files
• $FileName: The name portion of the current file, e.g., Chapter1.txt
• $FileExt: The extension portion of the current file, e.g., txt
• $BaseName: The name only portion of the current file, e.g., Document
• $ProjectDir: The directory of the current project , e.g., C:\Files
• $ProjectName: The name portion of the current project, e.g., Book for C:\Files\Book.sublime-project

Snippet style formatting can be used with these variables, for example:

${ProjectName:Default}

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

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

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

Troubleshooting

After pressing F7, you can see the command that was actually run by taking a look in the Console (via View/Console).

If you're getting an error like 'make' is not recognized as an internal or external command, operable program or batch file, try running same command in a command prompt and ensuring it works there.