PHP.GT

Different environments

One project often needs slightly different build steps in different places. A local development build may generate source maps, while a production build may omit them. Build handles this through modes.

How modes are named

The mode name is inserted before the file extension:

  • build.ini + mode production becomes build.production.ini
  • build.json + mode production becomes build.production.json

To use a mode:

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

Build loads the base configuration first, then loads the mode file, then recursively merges the two.

INI example

Base configuration:

build.ini

[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17
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

Production override:

build.production.ini

[script/**/*.es6]
name=Bundle JavaScript for production
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --minify --outfile=./www/script.js

The production file only contains the task that changes.

Running vendor/bin/build --mode production keeps the Sass task from build.ini, but replaces the name and execute values of the JavaScript task with those from build.production.ini.

Partial overrides are allowed

Mode files do not need to repeat the whole task definition.

For example, if we only want to change the arguments in an execute command, we can override just that property and leave the requirements and block name alone.

Adding tasks in a mode

A mode file can also introduce brand new tasks.

For example, a build.dev.ini file might add a sitemap generator or some diagnostic step that only runs during development.

Missing mode files

If we ask for a mode and the corresponding file does not exist, Build stops with an error rather than silently continuing with the wrong configuration.

That makes deployment mistakes more obvious when they happen.

Next, read default config to see how shared defaults and project-specific overrides fit together.