Build tasks

Each build task starts with a file pattern. When that pattern matches one or more files, Build knows which command to run.

Examples:

• images/*.jpg matches JPEG files directly inside images/
• script/**/*.es6 matches ES6 files anywhere under script/
• asset/**/* matches every file under asset/

For one-off builds, Build checks each pattern in turn and runs the matching tasks once. For watch mode, Build keeps checking the same patterns and reruns tasks when the modification time of a matched file changes.

INI task format

In build.ini, each task is a section:

[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17, node >=18
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --sourcemap --outfile=./www/script.js

The section name is the glob pattern.

The supported keys are:

• name: optional label used in success output
• require: optional comma-separated list of command/version pairs
• execute: required command line to run

If name is omitted, Build logs the command instead.

If require is omitted, the task still runs, but Build will not check the environment first.

The require line

The require line is a comma-separated list. Each item contains a command name followed by an optional version constraint.

require=node >=18, sass >=1.6, vendor/bin/sync ^1.3

These version constraints use Composer semver rules.

If the version is omitted, it defaults to *, which means “the command only needs to exist”.

require=esbuild, vendor/bin/sitemap ^1.0

The execute line

The execute line is split into the command and its arguments.

execute=sass ./style/style.scss ./www/style.css

Quoted arguments are supported:

execute=./node_modules/.bin/esbuild "script/my cool script.es6" --bundle --outfile=./www/script.js

There are a few parser rules to be aware of:

• execute is required
• the command part may not be empty
• quoted arguments must be terminated correctly
• the line may not contain ;, #, or line breaks

Those restrictions keep the configuration focused on one command invocation per task.

Full INI example

[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17, node >=18
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --sourcemap --outfile=./www/script.js

[style/**/*.scss]
name=Compile Sass
require=sass >=1.6
execute=sass ./style/style.scss ./www/style.css

[page/**/*.php]
name=Generate sitemap
require=vendor/bin/sitemap ^1.0
execute=php vendor/bin/sitemap src/page www/sitemap.xml

JSON is still supported

If a project already uses JSON, the same concepts are available through build.json, with require and execute written as nested objects.

See JSON configuration example for a complete example.

---

Next, move on to different environments to see how task definitions are overridden per mode.