Sublime Text Complex Build plugin

Sublime Text plugin that allows creating more complex build environments, with multiple commands and variables.

This plugin is helpful if you want to:

• have multiple build commands that you frequently invoke
  • i.e., Build, Clean, Configure, Run
• have different parameters to the build commands that you want to change frequently
  • i.e., mode (debug/release/reldev), targets, run parameters, build arguments, etc.
• tailor the build system to fit your needs

Installation

Install using Package Control:

• Open the Sublime Text Command Palette
• Select Package Control: Install Package
• Select ComplexBuild

Example usage

User's perspective

Let's assume we have a CMake project. As a consequence, the following operations will be frequently performed:

• Configure the build system
• Build all
• Clean
• Run the build executable

For this project, we frequently modify the following parameters:

• the mode (debug/release/reldev)
• the target to be built
• additional configuration arguments to be passed to CMake
• additional build arguments to be passed when building
• run arguments (to be passed when executing the resulting executable)

At the end of this exercise, we expect the build menu (Cmd+Shift+B or Ctrl+Shift+B) to show something like:

Selecting "Change Options" should show something like:

The user can change these options; for some of them (i.e., mode, target) the user needs to chose from a set of fix values, and for others, the user can enter the corresponding textual values.

After setting up the right parameters, the users can Configure the project, Build or Clean the selected target, or Run the executable generated by building the solution. If the user encounters some problems with the build commands, it can always use the Print build variables command to print all the variables defined, together with all their values.

Implementing the above scheme

For the purpose of this example, we will use a per-project build scheme; the same can be accomplished with a stand-alone Sublime Text build scheme (.sublime-build file).

There are several things that need to be configured, each in its own section:

• the build_systems section, containing the entries in the build menu
• the ComplexBuild_options section, describing the options for the build
• the ComplexBuild_values describing the pre-defined values we will use for the build
• the ComplexBuild, as part of the project settings, where user-chosen values will be stored

The first 3 sections can be placed in a dedicated Sublime Text build scheme, but the last one will always be saved in the project settings.

build_system section

For our example, the build_systems section should be configured like the following:

"build_systems":
[
    {
        "name": "Testability build",
        "target": "complex_build_exec",
        "target_cmd": "${cmdbuild}",
        "target_dir": "${builddir}",
        "variants":
        [
            {
                "name": "Change Options",
                "target": "complex_build_options"
            },
            {
                "name": "Configure",
                "target": "complex_build_exec",
                "target_cmd": "${cmdconfigure}"
            },
            {
                "name": "Clean",
                "target": "complex_build_exec",
                "target_cmd": "${cmdclean}"
            },
            {
                "name": "Run",
                "target": "complex_build_exec",
                "target_cmd": "${cmdrun}",
                "target_dir": "${rundir}"
            },
            {
                "name": "Print build variables",
                "target": "complex_build_print_vars"
            }
        ]
    }
],

ComplexBuild defines 3 commands that can be used in build systems:

• complex_build_exec -- executes the command given as target_cmd in the directory target_dir
• complex_build_options -- shows a menu with the options to be configured by the user
• complex_build_print_vars -- prints the variables currently available

We notice that the actual parameters to the complex_build_exec are in the form ${var_name}. ComplexBuild replaces them with the values configured for these variables. The values of these variables can be defined in two paces: as build values, or as user-specified values

ComplexBuild_values section

Here the user defines variables/values that are used directly by the build system, and typically cannot be specified by the user. For our example, we have

"ComplexBuild_values":
{
    "builddir": "${project_path}",
    "rundir": "${project_path}",
    "cmdconfigure": "/usr/local/bin/cmake ${configure_args} -DCMAKE_BUILD_TYPE=${mode}",
    "cmdbuild": "make ${build_args} ${target}",
    "cmdclean": "make clean",
    "cmdrun": "${executable} ${run_args}"
},

We define the actual commands to be executed for each build action, along with the directories to be used for building and for running the application (in our case it's just the project path)

The ComplexBuild_options section

In this section we define the menu presented to the user to easily select between different build configurations. For our example, we can have:

"ComplexBuild_options":
[
    {
        "name": "Set mode",
        "show": "${mode}",
        "choices":
        [
            {
                "name": "Debug",
                "set":
                {
                    "mode": "Debug"
                }
            },
            {
                "name": "RelDev",
                "set":
                {
                    "mode": "RelDev"
                }
            },
            {
                "name": "Release",
                "set":
                {
                    "mode": "Release"
                }
            }
        ]
    },
    {
        "name": "Set target",
        "show": "${executable}",
        "choices":
        [
            {
                "name": "testability",
                "set":
                {
                    "target": "mytest",
                    "executable": "./mytest"
                }
            },
            {
                "name": "perf_test",
                "set":
                {
                    "target": "perfTest",
                    "executable": "./perfTest"
                }
            }
        ]
    },
    {
        "name": "Set configure args",
        "show": "${configure_args}",
        "edit_value": "configure_args"
    },
    {
        "name": "Set build args",
        "show": "${build_args}",
        "edit_value": "build_args"
    },
    {
        "name": "Set run args",
        "show": "${run_args}",
        "edit_value": "run_args"
    }
],

There are two types of options we can configure: choices, for which the user will be presented with drop-down lists, or edit values for which the user will be presented with an edit field in which the options will be introduced. All these options have a name, and optionally a text to be displayed when showing the option; this text is usually the value of the variable that can be changed.

For the edit_value types of options, we need to provide a variable name in which the text introduced by the user will be placed. Chocices can allow a more advanced changing of the values; for each choice that the user can have, we can set one or more variables in a set list. For example, we may enable/disable different build options, stored in different variables, when we switch between debug and release builds.

Saved options

All the values that the user will set through the Change Options menu will be stored as project settings (part of the .sublime-project file). For our project, one possible configuration would be:

"settings":
{
    "ComplexBuild":
    {
        "build_args": "-j4",
        "configure_args": "-G \"Unix Makefiles\"",
        "target": "mytest",
        "executable": "./mytest",
        "mode": "Release",
        "run_args": ""
    }
}

These will be overwritten whenever the user changes the settings from the Change Options menu. The values present here will override any value set in the ComplexBuild_values section.

---

With these simple configurations, one can build more and more complex build system. We can have a lot of variables that can be easily configured from an options menu, and applied as arguments to the actual build commands.

Complete .sublime-project file (click to expand)

{
    "ComplexBuild_options":
    [
        {
            "name": "Set mode",
            "show": "${mode}",
            "choices":
            [
                {
                    "name": "Debug",
                    "set":
                    {
                        "mode": "Debug"
                    }
                },
                {
                    "name": "RelDev",
                    "set":
                    {
                        "mode": "RelDev"
                    }
                },
                {
                    "name": "Release",
                    "set":
                    {
                        "mode": "Release"
                    }
                }
            ]
        },
        {
            "name": "Set target",
            "show": "${executable}",
            "choices":
            [
                {
                    "name": "testability",
                    "set":
                    {
                        "target": "mytest",
                        "executable": "./mytest"
                    }
                },
                {
                    "name": "perf_test",
                    "set":
                    {
                        "target": "perfTest",
                        "executable": "./perfTest"
                    }
                }
            ]
        },
        {
            "name": "Set configure args",
            "show": "${configure_args}",
            "edit_value": "configure_args"
        },
        {
            "name": "Set build args",
            "show": "${build_args}",
            "edit_value": "build_args"
        },
        {
            "name": "Set run args",
            "show": "${run_args}",
            "edit_value": "run_args"
        }
    ],
    "ComplexBuild_values":
    {
        "builddir": "${project_path}",
        "rundir": "${project_path}",
        "cmdconfigure": "/usr/local/bin/cmake ${configure_args} -DCMAKE_BUILD_TYPE=${mode}",
        "cmdbuild": "make ${build_args} ${target}",
        "cmdclean": "make clean",
        "cmdrun": "${executable} ${run_args}"
    },
    "build_systems":
    [
        {
            "name": "Testability build",
            "target": "complex_build_exec",
            "target_cmd": "${cmdbuild}",
            "target_dir": "${builddir}",
            "variants":
            [
                {
                    "name": "Change Options",
                    "target": "complex_build_options"
                },
                {
                    "name": "Configure",
                    "target": "complex_build_exec",
                    "target_cmd": "${cmdconfigure}"
                },
                {
                    "name": "Clean",
                    "target": "complex_build_exec",
                    "target_cmd": "${cmdclean}"
                },
                {
                    "name": "Run",
                    "target": "complex_build_exec",
                    "target_cmd": "${cmdrun}",
                    "target_dir": "${rundir}"
                },
                {
                    "name": "Print build variables",
                    "target": "complex_build_print_vars"
                }
            ]
        }
    ],
    "folders":
    [
        {
            "path": "."
        },
    ],
    "settings":
    {
        "ComplexBuild":
        {
            "build_args": "-j4",
            "configure_args": "-G \"Unix Makefiles\"",
            "target": "mytest",
            "executable": "./mytest",
            "mode": "Release",
            "run_args": ""
        }
    }
}

Useful shortcuts

These build customization can be even more useful with the right keyboard shortcuts, to ease accessing the build features.

We recommend the following additional key configurations to be added to the key bindings:

{ "keys": ["f5"], "command": "build", "args": { "variant": "Run"} },
{ "keys": ["alt+f7"], "command": "complex_build_options"},
{ "keys": ["alt+b"], "command": "show_panel" , "args" : {"panel": "output.exec"} },

With these additions, then the following shortcuts can be used to interact with the build system:

Key shortcut	Meaning
Cmd+Shift+B (or Ctrl+Shift+B)	shows the build menu; typically used to select Configure, Clean or the main build command
F7 or Cmd+B (or Ctrl+B)	runs the last build command selected
Alt+F7	allows easy change of the build options
F5	run the selected program
Alt+B	shows the last console output