Examples

Introduction

Here we include a collection of simple to complex fully working examples of using Boost Build v2 for various tasks. They show the gamut from simple to advanced features. If you find yourself looking at the examples and not finding something you want to see working please post to our support list and we'll try and come up with a solution and add it here for others to learn from.

Hello

This example shows a very basic Boost Build project set up so it compiles a single executable from a single source file.

Files:

Our jamroot.jam is minimal and only specifies one exe target for the program:

exe hello : hello.cpp ;

Building the example yields:

> cd /example/hello
> b2
...found 8 targets...
...updating 4 targets...
common.mkdir bin/clang-darwin-4.2.1
common.mkdir bin/clang-darwin-4.2.1/debug
clang-darwin.compile.c++ bin/clang-darwin-4.2.1/debug/hello.o
clang-darwin.link bin/clang-darwin-4.2.1/debug/hello
...updated 4 targets...
> bin/clang-darwin-4.2.1/debug/hello
Hello!

	Note
	The actual paths in the `bin` sub-directory will depend on your toolset.

Time Action

This example shows how to use the testing.time utility to show time information for building a target.

Files:

Our jamroot.jam specifies the target we build and the time declaration to time the target we build:

import testing ;

exe hello : hello.cpp ;

time hello.time : hello ;

	Import the time rule from the testing module.
	The target we are timing just builds a hello program.
	This target records the time to build the `hello` target.

Building the example yields:

> cd /example/time
> b2
...found 9 targets...
...updating 6 targets...
common.mkdir bin
common.mkdir bin/clang-darwin-4.2.1
common.mkdir bin/clang-darwin-4.2.1/debug
clang-darwin.compile.c++ bin/clang-darwin-4.2.1/debug/hello.o
clang-darwin.link bin/clang-darwin-4.2.1/debug/hello
testing.time bin/clang-darwin-4.2.1/debug/hello.time
user: [hello] 0.013509
system: [hello] 0.045641
clock: [hello] 0.000000
...updated 6 targets...

	Note
	The actual paths in the `bin` sub-directory will depend on your toolset.

Build Variants

This example shows how user can create his own build variants. Two variants are defined: "crazy", which is just a random combination of properties, and "super-release", which is inherited from "release", and differs by a single define.

Files:

In this project the jamroot.jam specifies the custom build variants and the targets are specified in the two jamfile.jam files.

variant crazy : <optimization>speed <inlining>off
                <debug-symbols>on <profiling>on ;

variant super_release : release : <define>USE_ASM ;

	Define a build variant which is just combination of four properties.
	Define a built variant inherited from 'release'. It defines one new property and gets all properties from the parent `release` variant.

The top-level jamfile.jam:

project : default-build crazy super_release ;

exe a : a.cpp libs//l ;

	By default, build the project with the two variants we have defined in jamroot.jam.
	We build an `a` exe target that links a built library. The library builds with the propagated properties of the exe.

And the library jamfile.jam that the top-level jamfile.jam refers to:

lib l : l.cpp ;

The library l just needs the sources. By default it will be a shared library.

Building the example yields:

> cd /example/variant
> b2
...found 20 targets...
...updating 16 targets...
common.mkdir bin
common.mkdir bin/clang-darwin-4.2.1
common.mkdir bin/clang-darwin-4.2.1/crazy
clang-darwin.compile.c++ bin/clang-darwin-4.2.1/crazy/a.o
common.mkdir libs/bin
common.mkdir libs/bin/clang-darwin-4.2.1
common.mkdir libs/bin/clang-darwin-4.2.1/crazy
clang-darwin.compile.c++ libs/bin/clang-darwin-4.2.1/crazy/l.o
clang-darwin.link.dll libs/bin/clang-darwin-4.2.1/crazy/libl.dylib
clang-darwin.link bin/clang-darwin-4.2.1/crazy/a
common.mkdir bin/clang-darwin-4.2.1/super_release
clang-darwin.compile.c++ bin/clang-darwin-4.2.1/super_release/a.o
common.mkdir libs/bin/clang-darwin-4.2.1/super_release
clang-darwin.compile.c++ libs/bin/clang-darwin-4.2.1/super_release/l.o
clang-darwin.link.dll libs/bin/clang-darwin-4.2.1/super_release/libl.dylib
clang-darwin.link bin/clang-darwin-4.2.1/super_release/a
...updated 16 targets...

As specified in the top-level jamfile.jam both custom variants where built by default. Once can override that by specifying the variant one wants to build directly on the command line with a variant=super_release. Or just with a super_release as variants can be referred to by their name only. For example using that argument yields:

> cd /example/variant
> b2 super_release
...found 14 targets...
...updating 10 targets...
common.mkdir bin
common.mkdir bin/clang-darwin-4.2.1
common.mkdir bin/clang-darwin-4.2.1/super_release
clang-darwin.compile.c++ bin/clang-darwin-4.2.1/super_release/a.o
common.mkdir libs/bin
common.mkdir libs/bin/clang-darwin-4.2.1
common.mkdir libs/bin/clang-darwin-4.2.1/super_release
clang-darwin.compile.c++ libs/bin/clang-darwin-4.2.1/super_release/l.o
clang-darwin.link.dll libs/bin/clang-darwin-4.2.1/super_release/libl.dylib
clang-darwin.link bin/clang-darwin-4.2.1/super_release/a
...updated 10 targets...

	Note
	The actual paths in the `bin` sub-directory will depend on your toolset.