## 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
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
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`.