Build process

| Home | Libraries | People | FAQ | More

## Build process

When you've described your targets, you want Boost.Build to run the right tools and create the needed targets. This section will describe two things: how you specify what to build, and how the main targets are actually constructed.

The most important thing to note is that in Boost.Build, unlike other build tools, the targets you declare do not correspond to specific files. What you declare in Jamfiles is more like "metatarget". Depending on the properties that you specify on the command line, each "metatarget" will produce a set of real targets corresponding to the requested properties. It is quite possible that the same metatarget is build several times with different properties, and will, of course, produce different files.

### Tip

This means that for Boost.Build, you cannot directly obtain build variant from Jamfile. There could be several variants requested by the user, and each target can be build with different properties.

### Build request

The command line specifies which targets to build and with what properties. For example:

    bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full

would build two targets, "app1" and "lib1//lib1" with the specified properties. You can refer to any targets, using target id and specify arbitrary properties. Some of the properties are very common, and for them the name of the property can be omitted. For example, the above can be written as:

    bjam app1 lib1//lib1 gcc debug optimization=full

The complete syntax which has some additional shortcuts if described here.

### Building a main target

When you request, directly or indirectly, a build of a main target with specific requirements, the following steps are made. Some brief explanation is provided, and more detailes are given in the reference.

1. Applying default build. If the default-build property of a target specifies a value of a feature which is not present in the build request, that value is added.

2. Selecting the main target alternative to use. For each alternative we look how many properties are present both in alternative's requirements, and in build request. The alternative with large number of matching properties is selected.

3. Determining "common" properties. The build request is refined with target's requirements. The conditional properties in requirements are handled as well. Finally, default values of features are added.

4. Building targets referred by the sources list and dependency properties. The list of sources and the properties can refer to other target using target references. For each reference, we take all propagated properties, refine them by explicit properties specified in the target reference, and pass the resulting properties as build request to the other target.

5. Adding the usage requirements produces when building dependencies to the "common" properties. When dependencies are built in the previous step, they return both the set of created "real" targets, and usage requirements. The usage requirements are added to the common properties and the resulting property set will be used for building the current target.

6. Building the target using generators. To convert the sources to the desired type, Boost.Build uses "generators" --- objects which correspond to tools like compilers and linkers. Each generator declares what type of targets in can produce and what type of sources it requires. Using this information, Boost.Build determines which generators must be run to produce a specific target from specific sources. When generators are run, they return the "real" targets.

7. Computing the usage requirements to be returned. The conditional properties in usage requirements are expanded and the result is returned.

### Building a project

Often, user request a build of a complete project, not just one main target. In fact, invoking bjam without parameters builds the project defined in the current directory.

When a project is build, the build request is passed without modification to all main targets in that project. It's is possible to prevent implicit building of a target in a project with the `explicit` rule:

    explicit hello_test ;

would cause the `hello_test` target to be built only if explicitly requested by the user or by some other target.

The Jamfile for a project can include a number of `build-project` rule calls, that specify additional projects to be built.