| Home | Libraries | People | FAQ | More

## 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:

- hello.cpp
- jamroot.jam

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:

- jamroot.jam
- hello.cpp

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:

- a.cpp
- jamroot.jam
- jamfile.jam
- libs/jamfile.jam
- libs/l.cpp

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.