Which Boost Libraries Are Header-Only

Which Boost libraries are header-only?

The list of libraries that require building is here for Unix-like systems, and here for Windows.

For the current release, 1.58, both are the same:

• Boost.Chrono
• Boost.Context
• Boost.Filesystem
• Boost.GraphParallel
• Boost.IOStreams
• Boost.Locale
• Boost.MPI
• Boost.ProgramOptions
• Boost.Python
• Boost.Regex
• Boost.Serialization
• Boost.Signals
• Boost.System
• Boost.Thread
• Boost.Timer
• Boost.Wave

A few libraries have optional separately-compiled binaries:

• Boost.DateTime
• Boost.Graph
• Boost.Math
• Boost.Random
• Boost.Test
• Boost.Exception

Note that some libraries may depend on these (for example, Asio depends on System as pointed out in the comments), so you may still need to build something even if the library you want isn't on the list.

Why are not all Boost libraries header-only?

Different points, I guess.

• Binary size. Could header-only put a size burden on the client?
• Compilation times. Could header-only mean a significant decrease in compilation performance?
• Runtime Performance. Could header-only give superior performance?
• Restrictions. Does the design require header-only?

About binary size.

^{and a bit of security}

If there's a lot of reachable code in the boost library, or code about which the compiler can't argue whether it is reachable by the client, it has to be put into the final binary. ^(*)

On operating systems that have package management (e.g. RPM- or .deb-based), shared libraries can mean a big decrease in binary distribution size and have a security advantage: Security fixes are distributed faster and are then automatically used by all .so/.DLL users. So you had one recompile and one redistribution, but N profiteers. With a header-only library, you have N recompiles, N redistributions, always for each fix, and some member of those N are huge in themselves already.

^{(*) reachable here means "potentially executed"}

About compilation times.

Some boost libraries are huge. If you would #include it all, each time you change a bit in your source-file, you have to recompile everything you #included.

This can be counter-measured with cherry picked headers, e.g.

#include <boost/huge-boost-library.hpp> // < BAD
#include <boost/huge-boost-library/just-a-part-of-it.hpp> // < BETTER

but sometimes the stuff you really need to include is already big enough to cripple your recompiles.

The countermeasure is to make it a static or shared library, in turn meaning "compile completely exactly once (until the next boost update)".

About runtime performance.

We are still not in an age were global optimization solves all of our C++ performance problems. To make sure you give the compiler all the information it needs, you can make stuff header-only and let the compiler make inlining decisions.

In that respect, note that inlining gives not always superior performance because of caching and speculation issues on the CPU.

Note also that this argument is mostly with regards to boost libraries that might be used frequently enough, e.g. one could expect boost::shared_ptr<> to be used very often, and thus be a relevant performance factor.

But consider the real and only relevant reason boost::shared_ptr<> is header-only ...

About restrictions.

Some stuff in C++ can not be put into libraries, namely templates and enumerations.

But note that this is only halfway true. You can write typesafe, templated interfaces to your real data structures and algorithms, which in turn have their runtime-generic implementation in a library.

Likewise, some stuff in C++ should be put into source files, and in case of boost, libraries. Basically, this is everything that would give "multiple definition" errors, like static member variables or global variables in general.

Some examples can also be found in the standard library: std::cout is defined in the standard as extern ostream cout;, and so cout basically requires the distribution of something (library or sourcefile) that defines it once and only once.

Build Boost vs. include the headers

It depends on which library you wish to use. Almost all Boost libraries are header-only.

However, for example, Boost MPI needs to be compiled.

It is not a question of saving compilation time. There is no such thing as prebuilding header only library. (I am sure somebody will comment about precompiled headers, but it is another subject and is not recommended while using Boost.)

What does Boost mean by header-only libraries and automatic linking?

As you said, "Header only library" means that the whole library is in header files, so one (or several) #include lines is enough to use it. No linking is necessary.

"Automatic linking" means that, although the library needs some linking (either directly or as a dependency), you don't need to specify it in the compiler line, because the #include'd files will do some magic to bring in the appropriate libraries automatically, if supported by the compiler.

For example, in MSVC compilers, they use #pragman comment(lib, "..."); in Borland compilers they use #pragma defineoptions;, etc.

And most notably, "automatic linking" is not supported by the GNU compiler.

Automatic linking can be troublesome sometimes (for example, mixing debug and release versions), and you can selectively disable them by defining some preprocessor macros: BOOST_<libname>_NO_LIB. In that case you will have to do the linking manually.

UPDATE: About your comment below:

Boost.Timer claims to be a "Header only library" but it has lib files in the lib directory.

It looks like there is an error in the Boost documentation. Actually there are two different libraries named timer: The old, deprecated, header-only <boost/timer.hpp> and the new, improved, cooler, automatically linkable <boost/timer/timer.hpp>.

But for some reason, the main documentation page lists the properties of the old one.

There's no Boost.Asio lib files.

In the main Boost library documentation page library documentation page, you can see that Asio is listed as Automatic linking due to dependency. The specific dependencies are listed elsewhere: Boost.System and Boost.Regex, and both present automatic linking.

why does we need to build a boost library ,isn't it sufficient to just include the head files ,as boost are template

For a Boost question, the Boost website is a good place for answers, specifically the "header only libraries" section appearing in both getting started on Unix varients and getting started on Windows.

Nothing to Build?

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.

Note that "most" is used, not "all". In version 1.71, there are 16 libraries that must be built separately and 7 libraries that have optional separately-compiled components. (The Boost site has a list of these libraries, and that list gets updated as new versions are released.) If you're not using these particular libraries, then right, you can just include headers without linking to a Boost library.

How to export only a subset of header-only boost libraries?

Bootstrap and b2 are only required for building library binaries. As you said, you will use header-only only, so that's not required.

You can just zip up the boost/ include folders and be happy.

In theory you can prune the set of includes with BCP: https://www.boost.org/doc/libs/1_75_0/tools/bcp/doc/html/index.html

However, in practice I doubt it's worth the effort.

Which boost library to link to?

Boost libraries has a naming convention defined in the documentation here. E.g. libboost_thread.a is a static library for Boost.Thread.

In the header source you can find related library name, e.g. in boost/thread.hpp there is:

//  See www.boost.org/libs/thread for documentation. 

Next you need to understand library is header-only or not. Check the list here.

Some libraries requires the other Boost libraries, e.g. Boost.Asio requires Boost.System and Boost.Regex in some cases. Check library usage documentation to understand such dependencies.

Boost system 1.69.0 not header only?

Boost system is now indeed header-only, but provides a stub for backward compatibility with projects that require such a library.

Boost.System is now header-only. A stub library is still built for compatibility, but linking to it is no longer necessary.

It may be that Boost FileSystem is not yet updated to remove the stub as indicated on line: https://github.com/boostorg/filesystem/blob/develop/build/Jamfile.v2#L29

---

Related Topics