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

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.

Answer 2

You've pretty much nailed it -- a header only library is one where all the code for that library is contained in the header(s), so you only have to include them, not link against a library to use them.

That said, it's entirely possible to write a header-only library that depends on some other library, which may not be of the header-only variety. In this case, even though you don't have to tell the linker about the first library you're using, you still have to tell it about the second. Especially when/if all the code might be stuffed into one of what the linker thinks of as a library (e.g., one .lib or .a file), that may end up mostly a distinction without a difference (just to be clear: that isn't necessarily the case here, but it can and does arise anyway).