Header Organization and Compiled Binaries
This section covers the basics of the organization of Boost libraries in the folder structure, a list of libraries requiring compilation into binaries, or optionally using compilation, and the tools which you might use to compile the headers.
Header Organization
The organization of Boost library headers isn’t entirely uniform, but most libraries follow a few patterns:
-
Some older libraries and most very small libraries place all public headers directly into Boost.
-
Most libraries' public headers live in a subdirectory of boost, named after the library. For example, you’ll find the Python library’s
def.hppheader inboost/python/def.hpp. -
Some libraries have an “aggregate header” in boost that includes all of the library’s other headers. For example, Boost.Python's aggregate header is
boost/python.hpp. -
Most libraries place private headers in a subdirectory called detail, or aux. Don’t expect to find anything you can use in these directories.
It’s important to note the following:
-
The path to the boost root directory (often /usr/local/boost_1_82_0) is sometimes referred to as
$BOOST_ROOTin documentation and mailing lists. -
To compile anything in Boost, you need a directory containing the boost subdirectory in your
#includepath. -
Since all of Boost’s header files have the
.hppextension, and live in the boost subdirectory of the boost root, your Boost#includedirectives will look like:#include <boost/whatever.hpp>or#include "boost/whatever.hpp", depending on your preference regarding the use of angle bracket includes. -
Don’t be distracted by the doc subdirectory; it only contains a subset of the Boost documentation. Start with
libs/index.htmlif you’re looking for the whole enchilada.
Required Compiled Binaries
Most Boost libraries are header-only: they consist entirely of header files containing templates and inline functions, and require no separately-compiled library binaries or special treatment when linking.
The Boost libraries that must be built separately are:
-
- Note
-
The B2 build system will automatically build these library binaries for you. Just make sure to add a link to the folder containing the built libraries to your programming project.
Optional Compiled Binaries
A few libraries have optional separately-compiled binaries:
| Library | Binary Version Notes |
|---|---|
Binary version is needed for Extended Allocators and some Polymorphic Memory Resource classes |
|
Provides non-intrusive implementation of exception_ptr for 32-bit |
|
as a binary component that is only needed if you intend to parse GraphViz files. |
|
Including the header file in your code removes the need to link to the compiled binary |
|
Has binary components for the TR1 and C99 cmath functions. |
|
Has a binary component which is only needed if you’re using |
|
Is header-only since Boost 1.69. A stub library is still built for compatibility, but linking to it is no longer necessary. |
|
Can be used in “header-only” or “separately compiled” mode, although separate compilation is recommended for serious use. |
Identify Your Toolset
In order to build binaries from source, find the toolset corresponding to your compiler in the following table:
| Toolset | Vendor / project | Status | Primary use |
|---|---|---|---|
|
GNU Project |
Current |
GCC-based C++ development |
|
LLVM |
Current |
Clang/LLVM development |
|
Microsoft |
Current |
Microsoft Visual C++ on Windows |
|
LLVM |
Current |
Clang targeting Windows |
|
Apple |
Current |
Apple/Xcode development |
|
Emscripten |
Current / Specialized |
WebAssembly |
|
Intel |
Specialized |
Intel C++ on Linux |
|
QNX |
Specialized |
QNX development |
|
IBM |
Specialized |
IBM C++ environments |
|
NVIDIA / Portland Group |
Legacy / Specialized |
HPC environments |
|
Embarcadero |
Legacy |
Older Windows environments |
|
Oracle |
Legacy |
Older Solaris environments |
|
IBM |
Legacy |
Older IBM environments |
|
GNU |
Legacy |
Historical Windows GCC |
|
Comeau |
Obsolete |
Historical compiler |
|
Hewlett-Packard |
Obsolete |
Historical HP compiler |
|
Hewlett-Packard |
Obsolete |
Historical Tru64 compiler |
|
SGI |
Obsolete |
Historical IRIX compiler |
|
PathScale |
Obsolete |
Historical HPC compiler |
|
KAI |
Obsolete |
Historical Unix compiler |
|
Borland |
Obsolete |
Historical Linux compiler |
|
Metrowerks |
Obsolete |
Historical CodeWarrior |
|
HP/Compaq |
Obsolete |
Historical Tru64 |
|
DEC/VSI |
Specialized / Legacy |
OpenVMS |
Selecting a compiler version: If multiple versions of a compiler are installed, B2 can be configured to use a specific version. The syntax varies somewhat between toolsets - though is often simply a hyphen; for example, gcc-13 will select GCC version 13. Consult the documentation for the particular toolset when selecting a specific compiler version.