= CMake Macro Reference: `boost_add_library` =

This macro creates a new Boost library target that generates a compiled library
(.a, .lib, .dll, .so, etc) from source files. This routine will
actually build several different variants of the same library, with
different compilation options, as determined by the set of "default"
library variants.

{{{
boost_add_library(libname
                  source1 source2 ...
                  [COMPILE_FLAGS compileflags]
                  [feature_COMPILE_FLAGS compileflags]
                  [LINK_FLAGS linkflags]
                  [feature_LINK_FLAGS linkflags]
                  [LINK_LIBS linklibs]
                  [feature_LINK_LIBS linklibs]
                  [DEPENDS libdepend1 libdepend2 ...]
                  [STATIC_TAG]
                  [MODULE]
                  [NOT_feature]
                  [EXTRA_VARIANTS variant1 variant2 ...])
}}}

where `libname` is the name of Boost library binary (e.g.,
"boost_regex") and `source1`, `source2`, etc. are the source files used
to build the library, e.g., `cregex.cpp`.

This macro has a variety of options that affect its behavior. In
several cases, we use the placeholder "feature" in the option name
to indicate that there are actually several different kinds of
options, each referring to a different build feature, e.g., shared
libraries, multi-threaded, debug build, etc. For a complete listing
of these features, please refer to the page on [wiki:CMakeBuildFeatures CMake Build Features].

The options that affect this macro's behavior are:

  COMPILE_FLAGS::
    Provides additional compilation flags that will be
    used when building all variants of the library. For example, one
    might want to add "-DBOOST_SIGNALS_NO_LIB=1" through this option
    (which turns off auto-linking for the Signals library while
    building it).

  feature_COMPILE_FLAGS::
    Provides additional compilation flags that
    will be used only when building variants of the library that
    include the given feature. For example,
    `MULTI_THREADED_COMPILE_FLAGS` are additional flags that will be
    used when building a multi-threaded variant, while
    `SHARED_COMPILE_FLAGS` will be used when building a shared library
    (as opposed to a static library).

  LINK_FLAGS::
    Provides additional flags that will be passed to the
    linker when linking each variant of the library. This option
    should not be used to link in additional libraries; see `LINK_LIBS`
    and `DEPENDS`.

  feature_LINK_FLAGS::
    Provides additional flags that will be passed
    to the linker when building variants of the library that contain a
    specific feature, e.g., `MULTI_THREADED_LINK_FLAGS`. This option
    should not be used to link in additional libraries; see
    feature_LINK_LIBS.

  LINK_LIBS::
    Provides additional libraries against which each of the
    library variants will be linked. For example, one might provide
    "expat" as options to LINK_LIBS, to state that each of the library
    variants will link against the expat library binary. Use LINK_LIBS
    for libraries external to Boost; for Boost libraries, use DEPENDS.

  feature_LINK_LIBS::
    Provides additional libraries for specific
    variants of the library to link against. For example,
    `MULTI_THREADED_LINK_LIBS` provides extra libraries to link into
    multi-threaded variants of the library.

  DEPENDS::
    States that this Boost libraries depends on and links
    against another Boost library. The arguments to `DEPENDS` should be
    the unversioned name of the Boost library, such as
    "boost_filesystem". Like `LINK_LIBS`, this option states that all
    variants of the library being built will link against the stated
    libraries. Unlike `LINK_LIBS`, however, `DEPENDS` takes particular
    library variants into account, always linking the variant of one
    Boost library against the same variant of the other Boost
    library. For example, if the boost_mpi_python library `DEPENDS` on
    boost_python, multi-threaded variants of boost_mpi_python will
    link against multi-threaded variants of boost_python.

  STATIC_TAG::
    States that the name of static library variants on
    Unix need to be named differently from shared library
    variants. This particular option should only be used in rare cases
    where the static and shared library variants are incompatible,
    such that linking against the shared library rather than the
    static library will cause features. When this option is provided,
    static libraries on Unix variants will have "-s" appended to their
    names. Note: we hope that this is a temporary solution. At
    present, it is only used by the Test library.

  MODULE::
    This option states that, when building a shared library,
    the shared library should be built as a module rather than a
    normal shared library. Modules have special meaning an behavior on
    some platforms, such as Mac OS X.

  NOT_feature::
   States that library variants containing a particular
    feature should not be built. For example, passing
    `NOT_SINGLE_THREADED` suppresses generation of single-threaded
    variants of this library.

  EXTRA_VARIANTS::
    Specifies that extra variants of this library
    should be built, based on the features listed. Each "variant" is a 
    colon-separated list of features. For example, passing
    EXTRA_VARIANTS "PYTHON_NODEBUG:PYTHON_DEBUG"
    will result in the creation of an extra set of library variants,
    some with the `PYTHON_NODEBUG` feature and some with the
    `PYTHON_DEBUG` feature. 

== Example ==
The Boost.Thread library binary is built using the following invocation of the `boost_add_library` macro. The options passed to the macro indicate that CMake should define `BOOST_THREAD_BUILD_DLL` to 1 when building shared libraries and `BOOST_THREAD_BUILD_LIB` to 1 when building static libraries. The `NO_SINGLE_THREADED` option inhibits creation of any single-threaded variants of the library (which obviously would not make sense for a threading library!). The flags needed to compile the multi-threaded variants are automatically added.

{{{
boost_add_library(
  boost_thread
  barrier.cpp condition.cpp exceptions.cpp mutex.cpp once.cpp 
  recursive_mutex.cpp thread.cpp tss_hooks.cpp tss_dll.cpp tss_pe.cpp 
  tss.cpp xtime.cpp
  SHARED_COMPILE_FLAGS "-DBOOST_THREAD_BUILD_DLL=1"
  STATIC_COMPILE_FLAGS "-DBOOST_THREAD_BUILD_LIB=1"
  NO_SINGLE_THREADED
)
}}}

This example is from [http://svn.boost.org/svn/boost/branches/CMake/Boost_1_35_0/libs/thread/src/CMakeLists.txt libs/thread/src/CMakeLists.txt].

== Where Defined ==
This macro is defined in the Boost Core module in [http://svn.boost.org/svn/boost/branches/CMake/Boost_1_35_0/tools/build/CMake/BoostCore.cmake tools/build/CMake/BoostCore.cmake]