C++ Cookbook

1.8. Building a Static Library Using Boost.Build

Problem

You want to use Boost.Build to build a static library from a collection of C++ source files, such as those listed in Example 1-1.

Solution

Create a Jamroot file in the directory where you wish the static library to be created. In the file Jamroot, invoke the lib rule to declare a library target, specifying your .cpp files as sources and the property <link>static as a requirement. Add a usage requirement of the form <include>path to specify the library’s include directory, i.e., the directory with respect to which include directives for library headers should be resolved. You may need to add one or more requirements of the form <include>path to tell the compiler where to search for included headers. Finally, run bjam from the directory containing Jamroot, as described in Recipe 1.7.

For example, to build a static library from the source files listed in Example 1-1, your Jamroot might look like Example 1-11.

Example 1-11. A Jamfile to build the static library libjohnpaul.lib or libjohnpaul.a

# Jamfile for project libjohnpaul

lib libjohnpaul
    : # sources
      john.cpp paul.cpp johnpaul.cpp
    : # requirements 
      <link>static
    : # default-build
    : # usage-requirements
      <include>..
    ;

To build the library, enter:

> bjam libjohnpaul

Discussion

The lib rule is used to declare a target representing a static or dynamic library. It takes the same form as the exe rule, as illustrated in Example 1-9. The usage requirement <include>.. frees projects that depend on your library from having to explicitly specify your library’s include directory in their requirements. The requirement <link>static specifies that your target should always be built as a static library. If you want the freedom to build a library target either as static or as dynamic, you can omit the requirement <link>static. Whether the library is built as static or dynamic can then be specified on the command line, or in the requirements of a target that depends on the library target. For example, if the requirement <link>static were omitted in Example 1-11, you could build the target libjohnpaul as a static library by entering the command:

> bjam libjohnpaul link=static

Writing source code for a library that can be built either as static or dynamic is a bit tricky, however, as discussed in Recipe 1.9.

See Also

Recipe 1.3, Recipe 1.11, and Recipe 1.16