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 : . ;

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.

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 Jamfilethe Jamfile that resides in a directory that is an ancestor of the directories containing all the other Jamfilesis 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
 : 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

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 targetor a target corresponding to a static or dynamic libraryis 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 filesspecified as file names or as main target namesto 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

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

 

See Also

Recipe 1.2 and Recipe 1.15

Building C++ Applications

Code Organization

Numbers

Strings and Text

Dates and Times

Managing Data with Containers

Algorithms

Classes

Exceptions and Safety

Streams and Files

Science and Mathematics

Multithreading

Internationalization

XML

Miscellaneous

Index



C++ Cookbook
Secure Programming Cookbook for C and C++: Recipes for Cryptography, Authentication, Input Validation & More
ISBN: 0596003943
EAN: 2147483647
Year: 2006
Pages: 241

Flylib.com © 2008-2020.
If you may any questions please contact us: flylib@qtcs.net