Boost C++ Libraries

PrevUpHomeNext

Libraries

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

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

In the most common case, the lib creates a library from the specified sources. Depending on the value of <link> feature the library will be either static or shared. There are two other cases. First is when the library is installed somewhere in compiler's search paths, and should be searched by the compiler (typically, using the -l option). The second case is where the library is available as a prebuilt file and the full path is known.

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 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. On the other hand, the search feature only adds a library path, and the name feature gives the basic name of the library. The search rules are specific to the linker. 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's possible to use release version of a and debug version of b. Had we used the name and search features, the linker would always pick either release or debug versions.

For convenience, the following syntax is allowed:

lib z ;
lib gui db aux ;

and is does exactly the same as:

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

When a library uses another library you should put that other library in the 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 won't work. For example:

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

[Note] Note

When a library (say, a), that has another library, (say, b) is linked dynamically, the b library will be incorporated in a. (If b is dynamic library as well, then a will only refer to it, and not include any extra code.) When the a library is linked statically, Boost.Build will assure that all executables that link to a will also link to b.

One feature of Boost.Build that is very important for libraries is usage requirements. For example, if you write:

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

then the compiler include path for all targets that use helpers will contain the directory where the target is defined.path to "helpers.cpp". The user only needs to add helpers to the list of sources, and needn't consider the requirements its use imposes on a dependent target. This feature greatly simplifies Jamfiles.

[Note] Note

If you don't want shared libraries to include all libraries that are specified in sources (especially statically linked ones), you'd need to use the following:

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

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


PrevUpHomeNext