|
Home | Libraries | People | FAQ | More |
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 a Jamfile is more like a “metatarget.” Depending on the properties 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 built several times with different properties, producing different files.
This means that for Boost.Build, you cannot directly obtain a build variant from a Jamfile. There could be several variants requested by the user, and each target can be built with different properties.
The command line specifies which targets to build and with which 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, is described in the section called “Command line”.
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 details are given in the section called “Build process”.
Applying default build. If the default-build property of a target specifies a value of a feature that is not present in the build request, that value is added.
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.
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.
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.
Adding the usage requirements produced 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.
Building the target using generators. To convert the sources to the desired type, Boost.Build uses "generators" --- objects that correspond to tools like compilers and linkers. Each generator declares what type of targets it 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.
Computing the usage requirements to be returned. The conditional properties in usage requirements are expanded and the result is returned.
Often, a user builds a complete project, not just one main target. In fact, invoking bjam without arguments builds the project defined in the current directory.
When a project is built, 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.