boost.png (6897 bytes) Home Libraries People FAQ More

PrevUpHomeNext

Static and shared libaries

Libraries can be either static, which means they are included in executable files that use them, or shared (a.k.a. dynamic), which are only referred to from executables, and must be available at run time. Boost.Build can create and use both kinds.

The kind of library produced from a lib target is determined by the value of the link feature. Default value is shared, and to build static library, the value should be static. You can either requiest static build on the command line:

bjam link=static
    

or in the library's requirements:

lib l : l.cpp : <link>static ;
    

We can also use the <link> property to express linking requirements on a per-target basis. For example, if a particular executable can be correctly built only with the static version of a library, we can qualify the executable's target reference to the library as follows:

exe important : main.cpp helpers/<link>static ;

No matter what arguments are specified on the bjam command-line, important will only be linked with the static version of helpers.

Specifying properties in target references is especially useful if you use a library defined in some other project (one you can't change) but you still want static (or dynamic) linking to that library in all cases. If that library is used by many targets, you could use target references everywhere:

exe e1 : e1.cpp /other_project//bar/<link>static ;
exe e10 : e10.cpp /other_project//bar/<link>static ;

but that's far from being convenient. A better approach is to introduce a level of indirection. Create a local alias target that refers to the static (or dynamic) version of foo:

alias foo : /other_project//bar/<link>static ;
exe e1 : e1.cpp foo ;
exe e10 : e10.cpp foo ;

The alias rule is specifically used to rename a reference to a target and possibly change the properties.

Tip

When one library uses another, you put the second library is the source list of the first. For example:

lib utils : utils.cpp /boost/filesystem//fs ;   
lib core : core.cpp utils ;
exe app : app.cpp core ;

This works no matter what kind of linking is used. When core is built as a shared library, it is linked directly into utils. Static libraries can't link to other libraries, so when core is built as a static library, its dependency on utils is passed along to core's dependents, causing app to be linked with both core and utils."

Note

(Note for non-UNIX system). Typically, shared libraries must be installed to a directory in the dynamic linker's search path. Otherwise, applications that use shared libraries can't be started. On Windows, the dynamic linker's search path is given by the PATH environment variable. This restriction is lifted when you use Boost.Build testing facilities—the PATH variable will be automatically adjusted before running executable.


PrevUpHomeNext