C++ Cookbook

1.7. Building a Simple “Hello, World” Application Using Boost.Build

Problem

You want to use Boost.Build to build a simple “Hello, World” program, such as the one in Example 1-4.

Solution

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:

> bjam hello

This command builds the executable hello or hello.exe in a subdirectory of the current directory. Finally, enter the command:

> bjam dist

This command copies the executable to the directory specified by the location property, which in this case is the current directory.

Tip

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 bjam hello, enter bjam --v2 hello.

Discussion

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 an application.

The 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

exe target-name 
    : sources
    : requirements
    : default-build
    : usage-requirements
    ;

Here, 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 <feature>value. For example, to declare an executable that will always be built with thread support, you could write:

exe hello 
    : hello.cpp
    : <threading>multi
    ;

Tip

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

Feature	Value	Effect
include	Path	Specifies an include path
define	name [= value ]	Defines a macro
threading	multi or single	Enables or disables thread support
runtime-link	static or shared	Specifies runtime library linking[8]
variant	debug or release	Requests a debug or release build
[8] See Recipe 1.23.

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 hello.cpp.

The install 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

install target-name 
    : files
    : requirements
    : default-build
    : usage-requirements
    ;

Here, target-name is the name of the target being declared and files is a list of one or more files or targets to be copied. The remaining arguments, requirements, default-build, and 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 target like so:

install . : hello ;

You could then install the executable as follows:

> bjam .

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 xxx with your default toolset, enter the command:

> bjam xxx

To build the target xxx with the toolset yyy, enter the command:

> bjam xxx toolset=yyy

To build the target xxx with version vvv of toolset yyy, enter the command:

> bjam xxx toolset=yyy-vvv

To build specify a standard library zzz from the command line, use the syntax:

> bjam xxx stdlib=zzz

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:

> bjam

To remove all the files created during the build process, including the executable, enter:

> bjam --clean

Tip

A property of the form <feature>value can be specified on the command line as feature=value.

See Also

Recipe 1.2 and Recipe 1.15