Command line usage

Build is intended to be run from the command line.

When the package is installed in a project, the executable is available at:

vendor/bin/build

Note

In WebEngine applications, the same functionality is also exposed through:

gt build

By default, Build looks in the current working directory and prefers these filenames in this order:

1. build.ini
2. build.json

That means if both files exist, build.ini is the one that will be used.

If we want to point somewhere else, we can use --config or -c.

Examples:

vendor/bin/build --config ./config/build.ini
vendor/bin/build --config ./tools/build.json
vendor/bin/build --config ./some/project/directory

If the path passed to --config is a directory, Build looks inside that directory for build.ini first, then build.json.

Running once

Running the command without --watch performs one pass:

vendor/bin/build

Before running tasks, Build checks client-side packages if the working directory contains a package.json. Missing packages or versions that do not match trigger an automatic npm install --include=dev. Once the packages are ready, Build checks the declared requirements and runs each task whose file pattern matches at least one file.

See installing client-side packages for the first-build experience and help with missing commands.

Build prints a timestamped line for each successful task and then reports the total elapsed time.

Watching for changes

To keep Build running and rebuild when source files change, use --watch or -w:

vendor/bin/build --watch

In watch mode, Build remembers the modification time of each matched file and reruns only the tasks whose matching files changed.

This is usually the command we keep running during local development.

The package check runs once when watch mode starts. If we change package.json while Build is watching, we can restart Build to check and install the updated packages.

Build modes

Mode files let us override part of the base configuration for a specific environment.

vendor/bin/build --mode production
vendor/bin/build -m dev

When the base file is build.ini, Build looks for files such as build.production.ini. When the base file is build.json, Build looks for files such as build.production.json.

Only the properties that change need to be present in the mode file. The base and mode configuration are merged before the build runs.

The full behaviour is covered on different environments.

Default configuration

Frameworks and shared project setups can provide a fallback configuration by using --default or -d.

vendor/bin/build --default ./config/build.default.ini
vendor/bin/build --default ./framework/build

The default path may point to either a file or a directory. If it points to a directory, the same build.ini then build.json lookup order is used.

Build first looks for the project configuration. If none is found, it falls back to the default path.

The override model is explained on default config.

---

Next, read build tasks for the structure of individual task definitions.