You want to use Boost.Build to build a simple "Hello, World" program, such as the one in Example 1-4.
Create a text file named Jamroot in the directory
where you wish the executable and any accompanying intermediate files to be created. In
the file Jamroot, invoke two rules, as follows. First, invoke the
exe rule to declare an executable
target, specifying your .cpp file as a source. Next, invoke the
install rule, specifying the executable target name and the location where
you want the install directory. Finally, run bjam to
build your program.
For example, to build an executable hello or hello.exe from the file hello.cpp in Example 1-1, create a file named Jamroot with the following content in the directory containing hello.cpp, as shown in Example 1-8.
Example 1-8. Jamfile for project hello
# jamfile for project hello exe hello : hello.cpp ; install dist : hello : <location>. ;
Next, change to the directory containing hello.cpp and Jamroot and enter the following command:
This command builds the executable hello or hello.exe in a subdirectory of the current directory. Finally, enter the command:
This command copies the executable to the directory specified by the
location property, which in this case is the current
As this book goes to press, the Boost.Build developers are preparing for the
official release of Boost.Build version 2. By the time you read this, Version 2 will
probably already have been released; if not, you can enable the behavior described in
this chapter by passing the command-line option —v2
to bjam. For example, instead of entering
The file Jamroot is an example of a Jamfile. While a small collection of C++ source files might be managed using a single Jamfile, a large codebase will typically require many Jamfiles, organized hierarchically. Each Jamfile resides in a separate directory and corresponds to a separate project. Most Jamfiles are simply named Jamfile, but the highest-level Jamfile—the Jamfile that resides in a directory that is an ancestor of the directories containing all the other Jamfiles—is named Jamroot. The project defined by this highest-level Jamfile is known as the project root. Each project except the project root has a parent project , defined as the project in the nearest ancestor directory containing a Jamfile.
This hierarchical design is quite powerful: for example, it makes it easy to apply a requirement, such as thread support, to a project and all its descendants.
Each project is a collection of targets. Targets
are declared by
invoking rules, such as the
exe rule and the
install rule. Most targets correspond to binary files, or more
precisely, to collections of related binary files, such as the debug and release builds of
exe rule is used to declare an executable
target. An invocation of this rule has the form shown in Example 1-9.
Example 1-9. Invocation of the exe rule
target-name specifies the name of the executable,
sources specifies a list of source files and libraries;
requirements specifies properties that will apply to the target regardless of any
additional properties requested on the command line or inherited from another project;
default-build specifies properties that will apply to the target unless a feature with a
different value is explicitly requested;
usage-requirements specifies properties that will be propagated to all other targets that depend
on this target.
Properties are specified in the form
value. For example, to declare an executable
that will always be built with thread support, you could write:
exe hello : hello.cpp : <threading>multi ;
You don't have to write colons separating trailing arguments to a Boost.Build rule unless you specify values for those arguments.
Several common features, and their possible values, are listed in Table 1-15.
Table 1-15. Common Boost.Build features
Specifies an include path
Defines a macro
Enables or disables thread support
Specifies runtime library linking
Requests a debug or release build
When an executable target—or a target corresponding to a static or dynamic library—is built, the file corresponding to the target is created in a descendent directory of the directory containing the Jamfile. The relative pathname of this directory depends on the toolset and build configuration, but it always begins with bin. For example, the executable from Example 1-8 might be created in the directory bin/msvc/debug.
For simplicity I asked you to create the Jamfile from Example 1-8 in the same directory as the
source file hello.cpp. In a real world project,
however, you will often want to keep your source and binary files in separate directories.
In Example 1-8 you can place the Jamfile
anywhere you like, as long as you adjust the pathname
hello.cpp so that it points to the file
rule instructs Boost.Build to copy the one or more files—specified as file
names or as main target names—to a specified location. An invocation of this rule has the
form shown in Example 1-10.
Example 1-10. Invocation of the install rule
target-name is the name of the target being declared
files is a list of one or more files or targets to be
copied. The remaining arguments,
usage-requirements have the same meaning as in Example 1-9.
The location where the files are to be copied can be specified either as the target
name or as the value of the
location property of a
target requirement. For example, in Example
1-8 you could have written the
install . : hello ;
You could then install the executable as follows:
The method used in Example 1-8 is preferable, however, since it's easier to remember a named target than a file pathname.
Finally, let's look briefly at the syntax of the bjam command line. To build the target
your default toolset, enter the command:
To build the target
xxx with the toolset
yyy, enter the command:
To build the target
xxx with version
vvv of toolset
yyy, enter the
To build specify a standard library
zzz from the command
line, use the syntax:
You can build several targets at once by entering several target names on the command line, and build all targets in the given project by specifying no target. Consequently, you could have built and installed the executable from Example 1-9 by simply entering: