Question

On the Boost library documentation page, there are two categories named “Header Only Libraries” and “Automatic Linking“.

I suppose “Header Only Libraries” means you don’t have to link against Boost libraries in order to use them, and “Automatic Linking” means you have to link.

But when I use Boost.Timer, I have to link a static or dynamic library named timer (libboost_timer.a and libboost_timer.so.1.48.0 and various soft links to these under Linux library path), which is apparently the exact library file of Boost.Timer. I even need to link against Boost.System and Boost.Chrono, though it is understandable that the library itself uses some other libraries that need to be linked.

On the other side, Boost has clearly stated that Boost.Asio belongs to “Automatic Linking”, but there aren’t any library files named anything like asio.

So what does it actually mean to be a “header-only library” or “automatic linking“? Or is it purely a mistake?

Answer 1

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.