By josh / January 13, 2013

Compile with a keystroke using Sublime’s build systems

This week I received an email from a reader, Derek, who’s working on a project that uses LESS to generate CSS. Derek is using the Windows version of Sublime Text and wants to use a PowerShell script to compile his LESS code. (PowerShell is Microsoft’s answer to bash—a huge improvement over cmd.exe). This is simple to accomplish with Sublime’s build system feature. The following examples focus on PowerShell, but the same principles apply on Mac OS X and Linux.

Sublime’s build systems are available under Tools | Build Systems. By default, you’ll see entries for languages like C++, Ant and Make. Some plugins will add new build systems, and you can also create your own.

Build files are JSON-formatted configuration files saved with a .sublime-build extension. You can save them anywhere under /Data/Packages. I have a /Data/Packages/User/builds folder to keep custom build systems together.

For our example, we’ll create a build system that uses PowerShell to execute a script called build.ps1. (Email is unkind to formatted code, so I’ve posted example .sublime-build and build.ps1 files at

This build system will run PowerShell and execute any commands you specify in a file named build.ps1 that’s saved in the same directory as your .sublime-project file.

To dissect the example .sublime-build file a bit, the cmd property is an array that tells Sublime what program to execute (the first element) and what parameters to use (subsequent elements). In this case, we’re specifying PowerShell as the command and passing the path to our build script as a parameter. The working_dir property tells Sublime to look for the build.ps1 file in the same directory as the .sublime-project file.

To use the new build script, click Tools | Build Systems | PowerShell, which activates the new PowerShell build system. Then press Ctrl+B to execute the build.ps1 script.

The first time I ran the example, I was expecting to see a PowerShell window pop open to run the script, then sit there after it finished, forcing me to dismissed it. I was pleasantly surprised that Sublime suppresses the PowerShell GUI and displays the script output in the Sublime console. It’s a slick user experience.

Sublime’s build systems are quite configurable. My favorite feature: You can specify different defaults for different operating systems, which would allow you to easily use a PowerShell build script on Windows and a bash script on Mac OS X and Linux for a painless cross-platform workflow.

The only annoying limitation I’ve encountered so far: it’s difficult to run scripts that prompt for user input. I like to use rsync to deploy small websites, but I don’t want to hardcode my login info directly into the script. I saw a forum post that mentioned using using Sublime’s API to pop up an input window, so I might experiment with that at some point.

In addition to creating custom .sublime-build files, you can also choose to specify build systems in your project file. That way they’re automatically available to anyone who works on the project, but they don’t clutter up the build menu when you’re working on an unrelated project.

For a bunch of useful custom build tool examples, check out this master list.

And you can find more of the nitty-gritty details of Sublime’s build system in the unofficial Sublime docs.

P.S. For more ways to streamline your Sublime Text workflow, check out:

About the author


Click here to add a comment

Leave a comment: