Projects

As mentioned before, targets are grouped into projects, and each Jamfile is a separate project. Projects are useful because they allow us to group related targets together, define properties common to all those targets, and assign a symbolic name to the project that can be used in referring to its targets.

Projects are named using the project rule, which has the following syntax:

project id : attributes ;

Here, attributes is a sequence of rule arguments, each of which begins with an attribute-name and is followed by any number of build properties. The list of attribute names along with its handling is also shown in the table below. For example, it is possible to write:

project tennis
    : requirements <threading>multi
    : default-build release
    ;

The possible attributes are listed below.

Project id is a short way to denote a project, as opposed to the Jamfile's pathname. It is a hierarchical path, unrelated to filesystem, such as "boost/thread". Target references make use of project ids to specify a target.

Source location specifies the directory where sources for the project are located.

Project requirements are requirements that apply to all the targets in the projects as well as all subprojects.

Default build is the build request that should be used when no build request is specified explicitly.

The default values for those attributes are given in the table below.

Table 3.3.

Attribute	Name	Default value	Handling by the `project` rule
Project id	none	none	Assigned from the first parameter of the 'project' rule. It is assumed to denote absolute project id.
Source location	`source-location`	The location of jamfile for the project	Sets to the passed value
Requirements	`requirements`	The parent's requirements	The parent's requirements are refined with the passed requirement and the result is used as the project requirements.
Default build	`default-build`	none	Sets to the passed value
Build directory	`build-dir`	Empty if the parent has no build directory set. Otherwise, the parent's build directory with the relative path from parent to the current project appended to it.	Sets to the passed value, interpreted as relative to the project's location.

Besides defining projects and main targets, Jamfiles often invoke various utility rules. For the full list of rules that can be directly used in Jamfile see the section called “Builtin rules”.

Each subproject inherits attributes, constants and rules from its parent project, which is defined by the nearest Jamfile in an ancestor directory above the subproject. The top-level project is declared in a file called Jamroot rather than Jamfile. When loading a project, Boost.Build looks for either Jamroot or Jamfile. They are handled identically, except that if the file is called Jamroot, the search for a parent project is not performed.

Even when building in a subproject directory, parent project files are always loaded before those of their subprojects, so that every definition made in a parent project is always available to its children. The loading order of any other projects is unspecified. Even if one project refers to another via the use-project or a target reference, no specific order should be assumed.

Note

Giving the root project the special name “Jamroot” ensures that Boost.Build won't misinterpret a directory above it as the project root just because the directory contains a Jamfile.