buildium

Build your current project, directly from Pulsar

This package is a fork of build, with a few key-differences:

• it does not track your usage behaviour
• it defers activation
• it supports many types of build files
• it uses xterm as terminal
• it integrates naturally into visual language
• it's written in TypeScript
• it uses Svelte for UI
• it updates regularly

Installation

ppm

Install buildium from Pulsar's Package Manager or the command-line equivalent:

$ ppm install buildium

Using Git

Change to your Pulsar packages directory:

Windows

# Powershell
$ cd $Env:USERPROFILE\.pulsar\packages

:: Command Prompt
$ cd %USERPROFILE%\.pulsar\packages

Linux & macOS

$ cd ~/.pulsar/packages/

Clone repository as buildium:

$ git clone https://github.com/idleberg/atom-buildium buildium

Inside the cloned directory, install dependencies:

$ ppm install

Usage

Build Providers

This package provides services that ”build providers” can consume, it provides no functionality to build the code. In order to build, you will need to install additional packages. See the list of build providers for registered packages or search the packages website.

Build Files

If no provider suits your specific needs, you can create a build file in your project folder. A variety of file formats is supported, they need to match any of the following names:

Important

The legacy atom-build.config.* and .atom-build.* names are no longer read. Rename any such file to its buildium equivalent — keep the extension, so .atom-build.json becomes .buildium.json — or its targets will silently stop appearing.

Supported config files

• package.json with buildium object
• buildium.config.cts
• buildium.config.mts
• buildium.config.ts
• buildium.config.cjs
• buildium.config.mjs
• buildium.config.js
• buildium.config.json
• buildium.config.json5
• buildium.config.jsonc
• buildium.config.toml
• buildium.config.pkl
• buildium.config.yaml
• buildium.config.yml

Each of these is also supported as a dotfile, dropping the config infix:

• .buildium.cts
• .buildium.mts
• .buildium.ts
• .buildium.cjs
• .buildium.mjs
• .buildium.js
• .buildium.json
• .buildium.json5
• .buildium.jsonc
• .buildium.toml
• .buildium.pkl
• .buildium.yaml
• .buildium.yml

Example config

️

Let's take a look at a build file written in YAML

cmd: '<command to execute>'
name: '<name of target>'
args:
  - '<argument1>'
  - '<argument2>'
sh: true
cwd: '<current working directory for `cmd`>'
env:
  VARIABLE1: 'VALUE1'
  VARIABLE2: 'VALUE2'
errorMatch:
  - ^regexp1$
  - ^regexp2$
warningMatch:
  - ^regexp1$
  - ^regexp2$
keymap: '<keymap string>'
atomCommandName: 'namespace:command'
targets:
  extraTargetName:
    cmd: '<command to execute>'
    args:
    # (any previous options are viable here except `targets` itself)

Global Build Files

A build file in your home directory acts as a fallback for every project. All of the names above are recognised there too, so a ~/.buildium.yaml supplies its targets to any project that has no build file of its own — and to those that do, since the targets of both are shown together.

The one exception is ~/package.json, which is ignored deliberately: it is usually the result of running npm init in the wrong directory, and letting one quietly add targets to every project would be surprising.

Configuration Options

Option	Type	Description
cmd	string	The executable command
name	string?	The name of the target, shown in the targets list (toggled by buildium:select-active-target)
args	string[]?	An array of arguments for the command
sh	boolean?	If true, the combined command and arguments are passed to /bin/sh. Defaults to true.
cwd	string?	The working directory for the command, i.e. what . resolves to
env	Record<string, string>?	An object of environment variables and their values to set
errorMatch	(string | string[])?	A regular expression, or list thereof, matching output to a file, row and col. See error matching for details.
warningMatch	(string | string[])?	Like errorMatch, but reported as just a warning
functionMatch	(Function | Function[])?	Interpreted formats only. A function, or list thereof, that returns a list of match objects
keymap	string?	A keymap string, e.g. ctrl-alt-k or cmd-U. Pressing this key combination triggers the target.
killSignals	string[]?	An array of signals, sent one after each time Esc is pressed until the process has terminated. Defaults to SIGINT → SIGTERM → SIGKILL; only SIGKILL is guaranteed to terminate the process, so it's recommended to include it.
atomCommandName	string?	A command name of the form namespace:command, registered on the command registry. It becomes available in the command palette and can be triggered from there.
targets	Record<string, Target>?	Additional targets to build variations of your project. Any of the options above are viable here, except targets itself.
preBuild	Function?	Interpreted formats only. Called before executing cmd, with no arguments. this is the build configuration.
postBuild	Function?	Interpreted formats only. Called after executing cmd, with three arguments: boolean buildOutcome, string stdout and string stderr. this is the build configuration.

Note

A ? suffix marks an optional value. errorMatch, warningMatch and functionMatch are individually optional, but at least one of them is needed to report build failures.

Replacements

The following parameters will be replaced in cmd, any entry in args, cwd and values of env. They should all be enclosed in curly brackets.

Placeholder	Description
{FILE_ACTIVE}	Full path to the active file, e.g. ~/github/atom-build/lib/build.js
{FILE_ACTIVE_PATH}	Full path to the parent folder of the active file is, e.g. ~/github/atom-build/lib
{FILE_ACTIVE_NAME}	Full name and extension of the active file, e.g. buildium.js
{FILE_ACTIVE_NAME_BASE}	Base name of the active file, e.g. buildium
{FILE_ACTIVE_CURSOR_ROW}	Line number of the last cursor sits in the active document
{FILE_ACTIVE_CURSOR_COLUMN}	Column number of the last cursor sits in the active document
{PROJECT_PATH}	Full path to project folder, e.g. ~/github/atom-build
{REPO_BRANCH_SHORT}	Name of the active Git branch, e.g. main
{SELECTION}	Selected text in the active document

Keybindings

The following keybindings are for Windows and Linux, Mac should use Cmd instead of Ctrl

Keybinding	Description
Ctrl+Alt+B or F9	Builds your project
Ctrl+Alt+G or F4	Steps through build errors
Ctrl+Alt+H or Shift+F4	Steps to the first build error
Ctrl+Alt+V or F8	Toggles the build panel
Ctrl+Alt+T or F7	Show available build targets
Esc	Terminates build and closes the build panel

License

This work is licensed under The MIT License.