Boost C++ Libraries

Libraries

Library targets are created using the lib rule, which follows the common syntax . For example:

lib helpers : helpers.cpp ;

This will define a library target named helpers built from the helpers.cpp source file.

Depending on the given <link> feature value the library will be either static or shared.

Library targets may be used to represent:

Built libraries that get built from specified sources, as is the one in the example above.
Prebuilt libraries which already exist on the system and are just supposed to be used by the build system. Such libraries may be searched for by the tools using them (typically linkers referencing the library using the -l option) or their path may be known in advance by the build system.

The syntax for these case is given below:

lib z : : <name>z <search>/home/ghost ;
lib compress : : <file>/opt/libs/compress.a ;

The name property specifies the name that should be passed to the -l option, and the file property specifies the file location. The search feature specifies paths in which to search for the library. That feature can be specified several times or it can be omitted, in which case only the default compiler paths will be searched.

The difference between using the file feature as opposed to the name feature together with the search feature is that file is more precise. A specific file will be used as opposed to the search feature only adding a library path, or the name feature giving only the basic name of the library. The search rules are specific to the linker used. For example, given these definition:

lib a : : <variant>release <file>/pool/release/a.so ;
lib a : : <variant>debug <file>/pool/debug/a.so ;
lib b : : <variant>release <file>/pool/release/b.so ;
lib b : : <variant>debug <file>/pool/debug/b.so ;

It is possible to use a release version of a and debug version of b. Had we used the name and search features, the linker would have always picked either the release or the debug versions.

For convenience, the following syntax is allowed:

lib z ;
lib gui db aux ;

which has exactly the same effect as:

lib z : : <name>z ;
lib gui : : <name>gui ;
lib db : : <name>db ;
lib aux : : <name>aux ;

When a library references another library you should put that other library in its list of sources. This will do the right thing in all cases. For portability, you should specify library dependencies even for searched and prebuilt libraries, othewise, static linking on Unix will not work. For example:

lib z ;
lib png : z : <name>png ;

Note

	Note
When a library has a shared library defined as its source, or a static library has another static library defined as its source then any target linking to the first library with automatically link to its source library as well. On the other hand, when a shared library has a static library defined as its source then the first library will be built so that it completely includes the second one. If you do not want shared libraries to include all libraries specified in its sources (especially statically linked ones), you would need to use the following: lib b : a.cpp ; lib a : a.cpp : <use>b : : <library>b ; This specifies that library `a` uses library `b`, and causes all executables that link to `a` also link to `b`. In this case, even for shared linking, the `a` library will not even refer to `b`.

When a library has a shared library defined as its source, or a static library has another static library defined as its source then any target linking to the first library with automatically link to its source library as well.

On the other hand, when a shared library has a static library defined as its source then the first library will be built so that it completely includes the second one.

If you do not want shared libraries to include all libraries specified in its sources (especially statically linked ones), you would need to use the following:

lib b : a.cpp ;
lib a : a.cpp : <use>b : : <library>b ;

This specifies that library a uses library b, and causes all executables that link to a also link to b. In this case, even for shared linking, the a library will not even refer to b.

One Boost.Build feature that is often very useful for defining library targets are usage requirements. For example, imagine that you want you build a helpers library and its interface is described in its helpers.hpp header file located in the same directory as the helpers.cpp source file. Then you could add the following to the Jamfile located in that same directory:

lib helpers : helpers.cpp : : : <include>. ;

which would automatically add the directory where the target has been defined (and where the library's header file is located) to the compiler's include path for all targets using the helpers library. This feature greatly simplifies Jamfiles.