C++ Cookbook

1.9. Building a Dynamic Library Using Boost.Build

Problem

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

Solution

Create a Jamroot file in the directory where you wish the dynamic library—and the import library, if any—to be created. In the file Jamroot, invoke the lib rule to declare a library target, specifying your .cpp files as sources and the properties <link>shared 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. If your source files include headers from other libraries, you may need to add several requirements of the form <include>path to tell the compiler where to search for included headers. You may also need to add one or more requirements of the form <define>symbol to ensure that your dynamic library’s symbols will be exported using _ _declspec(dllexport) on Windows. Finally, run bjam from the directory containing Jamroot, as described in Recipe 1.7.

For example, to build a dynamic library from the source files listed in Example 1-2, create a file named Jamroot in the directory georgeringo, as shown in Example 1-12.

Example 1-12. A Jamfile to build the dynamic library georgeringo.so, georgeringo.dll, or georgeringo.dylib

# Jamfile for project georgringo

lib libgeorgeringo
    : # sources
      george.cpp ringo.cpp georgeringo.cpp
    : # requirements
      <link>shared
      <define>GEORGERINGO_DLL
    : # default-build
    : # usage-requirements
      <include>..
    ;

To build the library, enter:

> bjam libgeorgeringo

Discussion

As discussed in Recipe 1.8, the lib rule is used to declare a target representing a static or dynamic library. The usage requirement <include>.. frees projects which depend on your library from having to explicitly specify your library’s include directory in their requirements. The requirement <link>shared specifies that the target should always be built as a dynamic library. If you want the freedom to build a library target either as static or as dynamic, you can omit the requirement <link>shared and specify this property on the command line, or in the requirements of a target that depends on the library target. Writing a library which can be built as either static or dynamic requires some care, however, because of the preprocessor directives necessary to ensure that symbols are properly exported on Windows. Rewriting Example 1-2 so that it can be built as either static or dynamic makes a good exercise.

See Also

Recipe 1.4, Recipe 1.12, Recipe 1.16, and Recipe 1.19