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

For each task, Build:

1. loads the configuration
2. checks the declared requirements
3. skips tasks whose file pattern matches nothing
4. runs the command for tasks with matching files

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.

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.