.. include:: /include/substitutions.txt
.. include:: /include/external_links.txt
.. include:: /include/custom_roles.txt
.. _build systems:

*************
Build Systems
*************

Sublime |nbsp| Text comes with a beautiful and flexible subsystem to launch external
programs.  Because it is surrounded by information about the file you are
currently editing, this framework is very convenient to use it to "do
something" with the file you are editing -- typically:

- running it,
- testing it, or
- translating it into something else.

The whole concept of "building" is indeed the concept of translating something
(considered source) into something else, whether it is a program or set of
documents, or whatever it is.

Because this subsystem is normally used to compile (or otherwise translate) the file
being edited, or the files of the current source-code project, this subsystem is
referred to as the "Build System".

For many languages, Sublime |nbsp| Text will also:

- automatically select a Build System based on file type;

- remember the last-used Build System;

- search the output of the launched program and then enable the "Next Result" and
  "Previous Result" commands (bound to [F4] and [Shift+F4] by default) in order to
  place the cursor on the problematic part of the source code found by the
  Build System, if any;

- cancel a build in progress, if requested ([Ctrl+Break] or [Ctrl+C] on Mac).

The ``Tools`` menu has a whole section dedicated to doing different things with
Build Systems.



Selecting a Build System
************************

At any time, you can tell Sublime |nbsp| Text what Build System you wish to use via the
``Tools > Build System > ...`` fly-out menu.



Launching a Build
*****************

You launch a build operation using ``Tools > Build`` (mapped to [Ctrl+B] by default).

When there is more than one possible Build System that applies to the file in the
current :term:`View`, you will be prompted to select from the options available.
After selecting the Build System you want to use, hitting [Ctrl+B] will repeat the
launch of last Build System chosen.  To select a different one from that same list,
use ``Tools > Build With...`` or [Ctrl+Shift+B].

Once launched, the output from the external program is captured and can be seen in the
Build Output Overlay Panel.  This text can be edited and copied from, but not saved.



Navigating Among Results
************************

If the Build System is so configured, if there are any problems (e.g. syntax errors)
found and reported during the execution of the external program, once it has
completed, Sublime |nbsp| Text will select the first such error or warning and place your
cursor on the line where the problem was found.  This is where the "Next Result"
and "Previous Result" Commands apply (outside of the :ref:`find in files` context).

Using these Commands will open the applicable file (if it isn't already open) and
place your cursor on the applicable line, for each error or warning found in the
output text.



Creating Your Own Build System
******************************

Like most things in Sublime |nbsp| Text, you can customize existing Build Systems as well as
create your own.  ``Tools > Build System > New Build System...`` creates a "skeleton"
Build System (a JSON file), which you can save anywhere under a Package directory
(e.g. in your :term:`User Package`).

Its structure is a JSON "object" (dictionary in Python), which represents a single
Build System.  The minimum structure is the command line using the "cmd"
or "shell_cmd" key (the latter has more features, namely piping and redirection).

.. code-block:: json

    {
        "cmd": ["cmd", "arg1", "arg2", "arg3"]
    }

or

.. code-block:: json

    {
        "shell_cmd": "my_command \"$file\" | other_command"
    }

With only the minimum structure, Sublime |nbsp| Text uses the :term:`file stem` as a
name in the Build System list if there are more than one applicable to the current
file being edited.  Example:  the file ``Python.sublime-build`` will appear
as "Python" in the Build System list.

Other top-level keys available are documented on this web page:

    https://www.sublimetext.com/docs/build_systems.html#options

    https://www.sublimetext.com/docs/build_systems.html#exec-target-options

    https://www.sublimetext.com/docs/build_systems.html#custom-options


Variables
=========

The following variables will be expanded within any string specified in
the ``"cmd"``, ``"shell_cmd"`` or ``"working_dir"`` options.

If a literal ``$`` needs to be specified in one of these options, it must be escaped
with a \.  Since JSON uses backslashes for escaping also, ``$`` will need to be
written as ``\\$``.

Please note that this substitution will occur for any ``<span
class="key">"target"</span``>.  If a custom target is used, it may implement variable
expansion for additional options by using ``sublime.expand_variables()`` with the
result from ``self.window.extract_variables()``.

.. container:: tighter-table-2

    +--------------------+-------------------------------------------------------------------------+
    | Variable           | Description                                                             |
    +====================+=========================================================================+
    | $packages          | The path to the Packages/ folder.                                       |
    +--------------------+-------------------------------------------------------------------------+
    | $platform          | The platform Sublime Text is running on: "windows", "osx" or "linux".   |
    +--------------------+-------------------------------------------------------------------------+
    | $file              | The full path, including folder, to the file in the active view.        |
    +--------------------+-------------------------------------------------------------------------+
    | $file_path         | The path to the folder that contains the file in the active view.       |
    +--------------------+-------------------------------------------------------------------------+
    | $file_name         | The file name (sans folder path) of the file in the active view.        |
    +--------------------+-------------------------------------------------------------------------+
    | $file_base_name    | The file name, excluding the extension, of the file in the active view. |
    +--------------------+-------------------------------------------------------------------------+
    | $file_extension    | The extension of the file name of the file in the active view.          |
    +--------------------+-------------------------------------------------------------------------+
    | $folder            | The full path to the first folder listed in the side bar.               |
    +--------------------+-------------------------------------------------------------------------+
    | $project           | The full path to the current project file.                              |
    +--------------------+-------------------------------------------------------------------------+
    | $project_path      | The path to the folder containing the current project file.             |
    +--------------------+-------------------------------------------------------------------------+
    | $project_name      | The file name (sans folder path) of the current project file.           |
    +--------------------+-------------------------------------------------------------------------+
    | $project_base_name | The file name, excluding the extension, of the current project file.    |
    +--------------------+-------------------------------------------------------------------------+
    | $project_extension | The extension of the current project file.                              |
    +--------------------+-------------------------------------------------------------------------+



Further Reading
***************

- https://www.sublimetext.com/docs/build_systems.html
- https://docs.sublimetext.io/guide/usage/build-systems.html