Targets

A target stands for a particular hardware and software context, inside of a project. Its purpose is to build a bunch of software component packages for a defined platform with defined options. It also allows testing the produced deliveries.

BuildBox ensures that environment variables are always related to the active target. Paths are pointing to current target paths and to its needed tools.

Environment variables precedence respects the following rule: tools (from the last to the first, from target tools list) > target > BuildBox > system.

Target profile

Targets profiles are defined in project profile directory .bbx/, in files prefixed by target.. Target profile file is available at .bbx/target.<TARGET>.

Target file accepted fields are:

• PACKAGES defines a file listing target packages (must be stored in project profile directory).
• TOOLS (optional) defines a file listing target required tools, and toolchains (must be stored in project profile directory).
• TESTS (optional) defines a target test script.
• DIST (optional) defines a target delivery script.
• DESCRIPTION (optional) short target description.
• VAR_xxx (optional) target variables (replace xxx with whatever you want)
• build settings (optional): CPU, CPU_FAMILY, CPU_DESCRIPTION, CPUDEF, CHOST, CFLAGS and LDFLAGS.

Every field is optional: a target file may define nothing at all, in which case the target is built for the machine running BuildBox, with no specific flag.

You can define specific target variables, with VAR_xxx entries (replace xxx with whatever you want). Target variables result in environment variables declaration when the target is active, named BB_TARGET_VAR_xxx.

The target file is read as a shell script, so a value is written like a shell assignment: quote it when it holds spaces, and the quotes are not part of the value. A value may also use variables, which are expanded when the target becomes active:

• a BuildBox or target environment variable, such as ${BB_PROJECT_PROFILE_DIR},
• another field of the same target file, declared before it,
• a variable the target file defines for its own needs. Such a helper variable is not exported: only the VAR_xxx fields become environment variables.

# A helper variable, private to this target file
_CONFIG_DIR=${BB_PROJECT_PROFILE_DIR}/config

# Becomes BB_TARGET_VAR_CONFIG, expanded when the target is active
VAR_CONFIG="${_CONFIG_DIR}/prod.json"
VAR_DESCRIPTION="Production build of ${BB_PROJECT}"

TOOLS and PACKAGES files defines listing with an entry by line. Listed entries references files in project profile packages sub-directory. See package list file to know how to write a PACKAGES file. More details about tools and packages are in packages and tools documentation.

Example of a target file:

CPU=x86
TOOLS=tools.prod
PACKAGES=packages.prod
TESTS=${BB_PROJECT_PROFILE_DIR}/tests.sh
DIST=${BB_PROJECT_PROFILE_DIR}/dist.sh
DESCRIPTION="My target description"

The target directory (if the target has been fetched) is <TARGET>/ at the project root. Built packages are installed in the target build directory, <TARGET>/build.

Target build settings

BuildBox does not know any CPU nor any toolchain: the target file is the only place where the target hardware specifics are described. BuildBox only takes care of the mechanics, and exports what the target file defines to the build environment, so that packages build scripts, test and delivery scripts can use it.

The following fields are accepted, all of them being optional:

Field	Meaning	Default value
CPU	Target CPU name, freely chosen (it is also the name displayed by bbx target list)	x86
CPU_FAMILY	CPU family, to share code between several CPU of the same family	CPU value, uppercased
CPUDEF	CPU identifier, meant to be used as a C pre-processor definition	CPU value, uppercased
CPU_DESCRIPTION	Human readable CPU description	CPU value
CHOST	Toolchain host triplet, passed to configure scripts as --host for autotools packages	x86_64-pc-linux-gnu
CFLAGS	Compilation flags for the target	none
LDFLAGS	Link flags for the target	none

When a field is left undefined (or defined empty), its default value applies. Defaults describe a native build for the machine running BuildBox, which is why a target file defining nothing at all builds for the host.

For CPU_FAMILY and CPUDEF defaults, uppercasing the CPU value also replaces every character which is neither a letter nor a digit by an underscore, so that the result can be used as a C pre-processor definition: for example CPU=cortex-m33 gives CORTEX_M33.

TIP

Fields are plain shell assignments, evaluated in the order they appear in the file, so a field can reference a previously defined one, for example CFLAGS="-mcpu=${CPU} -mthumb".

CFLAGS and LDFLAGS given here are the target specific flags only: BuildBox completes them with the target build directory and the target tools include and library paths. Do not reference these paths in the target file.

Example of a target file for an ARM Cortex-M33 firmware, built with a bare metal toolchain provided as a tool:

CPU=cortex-m33
CPU_FAMILY=ARM
CPU_DESCRIPTION="Cortex-M33 with security extensions"
CPUDEF=CORTEX_M33
CHOST=arm-none-eabi
CFLAGS="-mcpu=cortex-m33 -mthumb -mfloat-abi=soft -mcmse -mgeneral-regs-only"
LDFLAGS="-specs=nosys.specs -specs=nano.specs"
TOOLS=tools.prod
PACKAGES=packages.prod
DESCRIPTION="Secure firmware"

WARNING

BuildBox 2.0.2 and older had built-in flags for a fixed list of CPU. Projects relying on them must declare these flags in their target files: see version migrations.

Dealing with targets is done through the target command, detailed below.

List targets

To list current project available targets, use:

bbx target list

Set target

To switch current project target, use:

bbx target set TARGET

Set current project TARGET. Following commands are going to concern this set target.

Target information

To display target information:

bbx target info [TARGET]

This command displays target information (defaults current target if TARGET is not specified). Displayed information:

Name	Description
Target	Target name
Path	Location of the target directory in the project
Profile path	Target profile file path
Testable	Indicates if the target has a self-test script available
Distributable	Indicates if the target has a distribution script available
Is cloned	Tells whether the target is cloned, yes if all packages are cloned, partially if some of them are cloned, else no

Fetch target

The following command is used to fetch all target required tools and packages sources:

bbx target clone [-p] [-u|--update]

With -u, a package or a tool which is already there is updated instead of being left as it is, and one which is not there yet is simply cloned. Updating only concerns sources which can move, and never discards anything:

Sources	Result
On a branch which got new commits	Fast forwarded to the last commit of the branch
On a branch with no new commit	Left as they are
On a tag or a changeset	Left as they are, such a revision designates a fixed commit
Holding local changes, or local commits which are not upstream	Left as they are
Fetched with a protocol other than Git	Left as they are
Whose remote repository holds a tag which does not designate the same commit any more	The update stops with an error, the history of the remote repository changed
On a branch which was rewritten upstream, the commit they sit on being gone from it	The update stops with an error, the history of the remote repository changed

With -u, the sources of the current target are also brought back in line with the sources sharing the packages support, when the two do not agree any more: sharing is decided when the sources are cloned, and a package whose package file or build mode changed afterwards keeps the layout it got on the day it was cloned. Sources which are shared now replace the target copy by a symlink to the project sources, the copy being sent to the BuildBox trash, and sources which are not shared any more replace the symlink by a copy of the project sources. Here too nothing is ever discarded: a target copy holding local work the project sources do not have is kept as it is, and so is a copy fetched with a protocol other than Git, which can not be asked for local work.

A remote repository whose history changed stops the update with an error rather than going past it, since the sources here may sit on a commit which does not exist upstream any more. The log says what moved, a tag or a branch, and what it means for the sources takes a look by hand.

The command reports what happened for each package and each tool: updated, up to date, or kept when local work stopped the update, preceded by sharing fixed or sharing kept when the sources layout was concerned. Details are in <TARGET>/target_clone.log.

Sources shared between targets are the same repository for every target using them, so updating them from one target updates them for all. Sources a target holds its own copy of are updated for that target only. Tools are installed once per project and shared by all its targets, so updating a tool updates it for every target requiring it.

A single package can be updated with bbx fetch -u.

-p gets the prebuilt files of the target.

In case of error, logs can be accessed from <TARGET>/target_clone.log.

Build target

To build target packages:

bbx target build [-v] [-c|--continue]

Install target required tools, and build (and install) target packages. Packages are automatically fetched if not done yet.

The -v option enables verbose mode to show all build logs.

The -c or --continue option allows to retry a build from where it failed.

In case of error, logs can be accessed from <TARGET>/target_build.log.

Build target (fast)

As target build, it is possible to use:

bbx target fastbuild [-v] [-c|--continue]

This command does not do package configuration step, it is assumed packages sources are already configured. This is why it is named "fast".

See Build target for more details about options.

In case of error, logs can be accessed from <TARGET>/target_fastbuild.log.

Test target

To run target tests, use:

bbx target test [-q | OPTIONS]

A log file is used for test output, stored in tests.log in target directory.

The -q option enables quiet mode: tests logs are only written to log file.

A target self-test script must be defined in the target profile file. OPTIONS are passed to the target test script.

Make target delivery

To make a deliverable for the current target, use:

bbx target dist [OPTIONS]

This command generates target deliverables. A target distribution script must be defined in the target profile file. OPTIONS are passed to the target dist script.

A log file is used for distribution output, stored in dist.log in target directory.

Clean target built files

To clean built files, run:

bbx target clean

Cleans target by removing built files in each packages. The target build directory is also removed.

Clean all target files

To clean all target files:

bbx target mrproper

This command wipes target by removing sources and built files in each packages. The target build directory is also removed. Sources are sent to BuildBox trash, and kept for a while.

WARNING

For packages using shared sources, sources are also removed from project (this affects other targets).

List target packages

To list target packages, use:

bbx target pkg [-m] [-v]

It displays target packages information.

The -m option displays only packages having locally modified sources. It helps to identify uncommitted changes.

The -v option enables verbose mode, which displays package details.

List target tools

To list target tools, use:

bbx target tools

Current target required tools are listed with their details.

Pre-built targets

Pre-built targets are built files of specific project revision targets, whose purpose is to avoid spending time building targets locally.

Settings before using pre-built targets can be defined in a config file: .bbx/config for a single project, ~/.config/buildbox/config for all your projects, or /etc/buildbox/config for all the users of the machine:

• BB_PREBUILT_SERVER: pre-built targets SSH server
• BB_PREBUILT_USERNAME: username to connect to pre-built targets server
• BB_PREBUILT_PATH: pre-built targets directory on server

BB_PREBUILT_PATH belongs to the project file, and is best dedicated to the project (/prebuilt/my_project for instance): on the server, a pre-built target is stored as <BB_PREBUILT_PATH>/<TAG>/<TARGET>.tar.xz, so two projects sharing a path and a tag would overwrite each other. The server and the username go in whichever file fits the context.

Pre-built targets can only be created for tagged projects revisions.

To get a prebuilt target from server, you have to fetch the target using bbx target clone -p.

Target test and delivery scripts

In the target file, you can define a test script with the TESTS field. The same way, you can define a delivery script with the DIST field. These scripts must be executable bash scripts which can be either located in the project profile, provided by a package or by a tool.

These scripts should not use BuildBox user commands, and should rely on BuildBox API instead.

These scripts must catch and return any error as a non-zero shell error code. You can use set -e for that.

Also, these scripts should carefully clean up any temporary resources created on exit. Produced test report or delivery archive may be stored in target directory.

Read how to develop scripts using BuildBox for more details.