Chapter 3. Build script fundamentals

A build script is made up of several elements. The main script consists of a single "project" element, which is broken down into "targets". Each target is then made up of "tasks", which perform an action such as compiling source code.

Build Script Elements

project

The main node that is required by every build script. Use it to define the project's name and its default build target. It can also be used to set global properties that can be accessed by all targets.

target

A target is a collection of build tasks, similar to a function. It will run all of the tasks it contains, and it is commonly used to break a build file into more manageable chunks. For example, resource building can be done in a separate target that is included into the main build file. This keeps everything much cleaner, and also means that only certain targets can be run if so desired.

task

Tasks are where the action in a build script occurs. Each task does a single job, such as compiling an executable or creating a directory.

More information: Task reference

type

Types allow for complex information to be passed to a task.

For example, the fileset type is used to pass a list of filenames to a task. The list is generated when the task is run, and can include and exclude filenames using patterns (such as "*.bmx"). This makes it much simpler to create a task that works with files without having having to list each file name.

More information: Type reference

expression

Expressions are small bits of code that blam will evaluate when processing a property or task argument. They are enclosed in the following syntax: ${ expression }.

For example, the following expression expands into the directory name of the current build file: ${ project::get-buildfile-path() }.

Expressions support basic arithmetic operations, such as + and -.

function

A function can be used inside an expression. They're usually used to do things like fetching path names or manipulating strings.

More information: Function reference

property

Properties are the blam equivalent of variables. They can either be set in the main project node, where they will be globally accessible, or they can be set in tasks where they will only be accessed by the local task.

One important point is that property values are only processed when they are accessed by a task or function. For example, a property that gets its value from a folder's existence will have a different value if the folder is deleted during the script's execution.

filter

Filters are used to filter the content of a file during a task. They do not modify the source file, but will change the output.

More information: Filter reference