Build Systems – Basics¶
Overview¶
You can use build systems to run files through external programs and see any generated output, all without leaving Sublime Text.
Note
We use the term build in a broad sense. A build system doesn’t need to generate a compiled executable—it could simply format code, run an interpreter, etc.
Parts of a Build System¶
Simple build systems
only require a .sublime-build
file.
More advanced build systems
may optionally consist of up to three parts:
- a
.sublime-build
file (configuration data in JSON format); - optionally, a custom Sublime Text command (Python code) driving the build process;
- optionally, an external executable file (script or binary file).
File Format of .sublime-build
Files¶
Format | JSON (with comments) |
Extension | .sublime-build |
Name | Any |
Location | Any under Packages |
Content | Predefined items and, optionally, arbitrary user-defined items |
A .sublime-build
file
contains configuration data
as a JSON object
and specifies
switches, options and environmental data.
Each .sublime-build
file
is normally associated
with a specific scope
corresponding to a file type
(for example, source.python
).
The file name represents the name of the build system and will be displayed whenever you can select a build system.
Example¶
{
"cmd": ["python", "-u", "$file"],
"file_regex": "^[ ]*File \"(...*?)\", line ([0-9]*)",
"selector": "source.python"
}
The Sublime Text Command Used in A Build System¶
When you run
the default build task in Sublime Text
(Ctrl+B
),
a Sublime Text command receives
the configuration data
specified in the .sublime-build
file.
This command then builds the files.
Often, it calls
an external program.
By default, the command
used in build systems is exec
,
but it can be overridden.
Overriding the Default Command for Build Systems¶
By default, build systems use
the exec
command implemented by Packages/Default/exec.py
.
This command simply forwards configuration data
to an external program
and runs it asynchronously.
Using the target
option
in a .build-system
file,
it’s possible to override
the exec
command.
See Target Command Arguments for details.
Calling External Programs¶
A build system may call
an external program
to process files.
The external program may be
a custom shell script,
a standard utility like make
or tidy
, etc.
Usually, the external program
receives paths to files or directories,
along with switches and options
that configure its behavior.
Note
Build systems can but don’t need to call external programs—a build system could be implemented entirely as a Sublime Text command.