ctrl+shift+p filters: :st2 :st3 :win :osx :linux
Browse

Complex​Build

by lucteo ST2/ST3

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

Details

Installs

  • Total 23
  • Win 15
  • OS X 4
  • Linux 4
Oct 18 Oct 17 Oct 16 Oct 15 Oct 14 Oct 13 Oct 12 Oct 11 Oct 10 Oct 9 Oct 8 Oct 7 Oct 6 Oct 5 Oct 4 Oct 3 Oct 2 Oct 1 Sep 30 Sep 29 Sep 28 Sep 27 Sep 26 Sep 25 Sep 24 Sep 23 Sep 22 Sep 21 Sep 20 Sep 19 Sep 18 Sep 17 Sep 16 Sep 15 Sep 14 Sep 13 Sep 12 Sep 11 Sep 10 Sep 9 Sep 8 Sep 7 Sep 6 Sep 5 Sep 4
Windows 0 0 0 0 1 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0
OS X 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0
Linux 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0

Readme

Source
raw.​githubusercontent.​com

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:

Build menu

Selecting “Change Options” should show something like:

Options menu

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)

Project settings

All the values that the user will set through the Change Options menu will be stored as project settings. 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": ""
    }
}

The values present here will override any value set in the ComplexBuild_values section.

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.


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.

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: “json { "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