FindBoost — CMake 3.17.2 Documentation

# FindBoost

Find Boost include dirs and libraries

Use this module by invoking find_package with the form:

    find_package(Boost
      [version] [EXACT]      # Minimum or EXACT version e.g. 1.67.0
      [REQUIRED]             # Fail with error if Boost is not found
      [COMPONENTS <libs>...] # Boost libraries by their canonical name
                             # e.g. "date_time" for "libboost_date_time"
      [OPTIONAL_COMPONENTS <libs>...]
                             # Optional Boost libraries by their canonical name)
      )                      # e.g. "date_time" for "libboost_date_time"

This module finds headers and requested component libraries OR a CMake package configuration file provided by a “Boost CMake” build. For the latter case skip to the “Boost CMake” section below. For the former case results are reported in variables:

    Boost_FOUND            - True if headers and requested libraries were found
    Boost_INCLUDE_DIRS     - Boost include directories
    Boost_LIBRARY_DIRS     - Link directories for Boost libraries
    Boost_LIBRARIES        - Boost component libraries to be linked
    Boost_<C>_FOUND        - True if component <C> was found (<C> is upper-case)
    Boost_<C>_LIBRARY      - Libraries to link for component <C> (may include
                             target_link_libraries debug/optimized keywords)
    Boost_VERSION_MACRO    - BOOST_VERSION value from boost/version.hpp
    Boost_VERSION_STRING   - Boost version number in x.y.z format
    Boost_VERSION          - if CMP0093 NEW => same as Boost_VERSION_STRING
                             if CMP0093 OLD or unset => same as Boost_VERSION_MACRO
    Boost_LIB_VERSION      - Version string appended to library filenames
    Boost_VERSION_MAJOR    - Boost major version number (X in X.y.z)
                             alias: Boost_MAJOR_VERSION
    Boost_VERSION_MINOR    - Boost minor version number (Y in x.Y.z)
                             alias: Boost_MINOR_VERSION
    Boost_VERSION_PATCH    - Boost subminor version number (Z in x.y.Z)
                             alias: Boost_SUBMINOR_VERSION
    Boost_VERSION_COUNT    - Amount of version components (3)
    Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
                           - Pass to add_definitions() to have diagnostic
                             information about Boost's automatic linking
                             displayed during compilation

Note that Boost Python components require a Python version suffix (Boost 1.67 and later), e.g. `python36` or `python27` for the versions built against Python 3.6 and 2.7, respectively. This also applies to additional components using Python including `mpi_python` and `numpy`. Earlier Boost releases may use distribution-specific suffixes such as `2`, `3` or `2.7`. These may also be used as suffixes, but note that they are not portable.

This module reads hints about search locations from variables:

    BOOST_ROOT             - Preferred installation prefix
     (or BOOSTROOT)
    BOOST_INCLUDEDIR       - Preferred include directory e.g. <prefix>/include
    BOOST_LIBRARYDIR       - Preferred library directory e.g. <prefix>/lib
    Boost_NO_SYSTEM_PATHS  - Set to ON to disable searching in locations not
                             specified by these hint variables. Default is OFF.
    Boost_ADDITIONAL_VERSIONS
                           - List of Boost versions not known to this module
                             (Boost install locations may contain the version)

and saves search results persistently in CMake cache entries:

    Boost_INCLUDE_DIR         - Directory containing Boost headers
    Boost_LIBRARY_DIR_RELEASE - Directory containing release Boost libraries
    Boost_LIBRARY_DIR_DEBUG   - Directory containing debug Boost libraries
    Boost_<C>_LIBRARY_DEBUG   - Component <C> library debug variant
    Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant

The following `IMPORTED` targets are also defined:

    Boost::headers                - Target for header-only dependencies
                                    (Boost include directory)
                                    alias: Boost::boost
    Boost::<C>                    - Target for specific component dependency
                                    (shared or static library); <C> is lower-
                                    case
    Boost::diagnostic_definitions - interface target to enable diagnostic
                                    information about Boost's automatic linking
                                    during compilation (adds BOOST_LIB_DIAGNOSTIC)
    Boost::disable_autolinking    - interface target to disable automatic
                                    linking with MSVC (adds BOOST_ALL_NO_LIB)
    Boost::dynamic_linking        - interface target to enable dynamic linking
                                    linking with MSVC (adds BOOST_ALL_DYN_LINK)

Implicit dependencies such as `Boost::filesystem` requiring `Boost::system` will be automatically detected and satisfied, even if system is not specified when using `find_package()` and if `Boost::system` is not added to `target_link_libraries()`. If using `Boost::thread`, then `Threads::Threads` will also be added automatically.

It is important to note that the imported targets behave differently than variables created by this module: multiple calls to `find_package(Boost)` in the same directory or sub-directories with different options (e.g. static or shared) will not override the values of the targets created by the first call.

Users may set these hints or results as `CACHE` entries. Projects should not read these entries directly but instead use the above result variables. Note that some hint names start in upper-case “BOOST”. One may specify these as environment variables if they are not specified as CMake variables or cache entries.

This module first searches for the `Boost` header files using the above hint variables (excluding `BOOST_LIBRARYDIR`) and saves the result in `Boost_INCLUDE_DIR`. Then it searches for requested component libraries using the above hints (excluding `BOOST_INCLUDEDIR` and `Boost_ADDITIONAL_VERSIONS`), “lib” directories near `Boost_INCLUDE_DIR`, and the library name configuration settings below. It saves the library directories in `Boost_LIBRARY_DIR_DEBUG` and `Boost_LIBRARY_DIR_RELEASE` and individual library locations in `Boost_<C>_LIBRARY_DEBUG` and `Boost_<C>_LIBRARY_RELEASE`. When one changes settings used by previous searches in the same build tree (excluding environment variables) this module discards previous search results affected by the changes and searches again.

Boost libraries come in many variants encoded in their file name. Users or projects may tell this module which variant to find by setting variables:

    Boost_USE_DEBUG_LIBS     - Set to ON or OFF to specify whether to search
                               and use the debug libraries.  Default is ON.
    Boost_USE_RELEASE_LIBS   - Set to ON or OFF to specify whether to search
                               and use the release libraries.  Default is ON.
    Boost_USE_MULTITHREADED  - Set to OFF to use the non-multithreaded
                               libraries ('mt' tag).  Default is ON.
    Boost_USE_STATIC_LIBS    - Set to ON to force the use of the static
                               libraries.  Default is OFF.
    Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
                               libraries linked statically to the C++ runtime
                               ('s' tag).  Default is platform dependent.
    Boost_USE_DEBUG_RUNTIME  - Set to ON or OFF to specify whether to use
                               libraries linked to the MS debug C++ runtime
                               ('g' tag).  Default is ON.
    Boost_USE_DEBUG_PYTHON   - Set to ON to use libraries compiled with a
                               debug Python build ('y' tag). Default is OFF.
    Boost_USE_STLPORT        - Set to ON to use libraries compiled with
                               STLPort ('p' tag).  Default is OFF.
    Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
                             - Set to ON to use libraries compiled with
                               STLPort deprecated "native iostreams"
                               ('n' tag).  Default is OFF.
    Boost_COMPILER           - Set to the compiler-specific library suffix
                               (e.g. "-gcc43").  Default is auto-computed
                               for the C++ compiler in use.  A list may be
                               used if multiple compatible suffixes should
                               be tested for, in decreasing order of
                               preference.
    Boost_ARCHITECTURE       - Set to the architecture-specific library suffix
                               (e.g. "-x64").  Default is auto-computed for the
                               C++ compiler in use.
    Boost_THREADAPI          - Suffix for "thread" component library name,
                               such as "pthread" or "win32".  Names with
                               and without this suffix will both be tried.
    Boost_NAMESPACE          - Alternate namespace used to build boost with
                               e.g. if set to "myboost", will search for
                               myboost_thread instead of boost_thread.

Other variables one may set to control this module are:

    Boost_DEBUG              - Set to ON to enable debug output from FindBoost.
                               Please enable this before filing any bug report.
    Boost_REALPATH           - Set to ON to resolve symlinks for discovered
                               libraries to assist with packaging.  For example,
                               the "system" component library may be resolved to
                               "/usr/lib/libboost_system.so.1.67.0" instead of
                               "/usr/lib/libboost_system.so".  This does not
                               affect linking and should not be enabled unless
                               the user needs this information.
    Boost_LIBRARY_DIR        - Default value for Boost_LIBRARY_DIR_RELEASE and
                               Boost_LIBRARY_DIR_DEBUG.

On Visual Studio and Borland compilers Boost headers request automatic linking to corresponding libraries. This requires matching libraries to be linked explicitly or available in the link library search path. In this case setting `Boost_USE_STATIC_LIBS` to `OFF` may not achieve dynamic linking. Boost automatic linking typically requests static libraries with a few exceptions (such as `Boost.Python`). Use:

    add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})

to ask Boost to report information about automatic linking requests.

Example to find Boost headers only:

    find_package(Boost 1.36.0)
    if(Boost_FOUND)
      include_directories(${Boost_INCLUDE_DIRS})
      add_executable(foo foo.cc)
    endif()

Example to find Boost libraries and use imported targets:

    find_package(Boost 1.56 REQUIRED COMPONENTS
                 date_time filesystem iostreams)
    add_executable(foo foo.cc)
    target_link_libraries(foo Boost::date_time Boost::filesystem
                              Boost::iostreams)

Example to find Boost Python 3.6 libraries and use imported targets:

    find_package(Boost 1.67 REQUIRED COMPONENTS
                 python36 numpy36)
    add_executable(foo foo.cc)
    target_link_libraries(foo Boost::python36 Boost::numpy36)

Example to find Boost headers and some static (release only) libraries:

    set(Boost_USE_STATIC_LIBS        ON)  # only find static libs
    set(Boost_USE_DEBUG_LIBS         OFF) # ignore debug libs and
    set(Boost_USE_RELEASE_LIBS       ON)  # only find release libs
    set(Boost_USE_MULTITHREADED      ON)
    set(Boost_USE_STATIC_RUNTIME    OFF)
    find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
    if(Boost_FOUND)
      include_directories(${Boost_INCLUDE_DIRS})
      add_executable(foo foo.cc)
      target_link_libraries(foo ${Boost_LIBRARIES})
    endif()

## Boost CMake

If Boost was built using the boost-cmake project or from Boost 1.70.0 on it provides a package configuration file for use with find_package’s config mode. This module looks for the package configuration file called `BoostConfig.cmake` or `boost-config.cmake` and stores the result in `CACHE` entry “Boost_DIR”. If found, the package configuration file is loaded and this module returns with no further action. See documentation of the Boost CMake package configuration for details on what it provides.

Set `Boost_NO_BOOST_CMAKE` to `ON`, to disable the search for boost-cmake.