C++ header-only template library

Question

Looking at this project (http://www.savarese.com/software/libssrckdtree/) I found the definition "C++ header-only template library". At the moment I have basic C++ knowledge but would like to know what this exactly means and why this people use it on this project

Answer 1

The short answer is that templates are much like macros for the compiler to generate code. Each time you instantiate it (for esample, using a type like std::list<int>), the compiler has to have the original code to insert the correct type (in this case int) in the code of the template class. This is why template classes are included in .h files each time you have to use them in .cpp files.

Answer 2

It means that there are no modules in the library, only headers. That means the library can be used without requiring it to be first compiled and later linked in; just include the headers in your own source modules.

The benefits of this approach are

1. It's easier to include, since you don't need to specify linker options in your build system.
2. You always compile all the library code with the same compiler (options) as the rest of your code, since the library's functions get inlined in your code.
3. It may be a lot faster.

In this case, the container datastructure implemented templated on the type of data it contains, so it cannot be fully compiled.

Answer 3

It exactly means that library redistributed only as headers. To use it, you only need #include it in your source files.

Answer 4

It means all the definitions of template (function template or class template) are in the headers only. There is no .cpp file. There are only .h files (or some other extensions such as .hpp or no extension at all like <vector>, string> etc)

C++ compilers require the definitions of templates to be present in the same file in which they're declared. As such, the header-only library is neither static library or dynamic library. Its source-code library which means you can see the implementation in the headers. You've include the header files in your code, which gets compiled along with the headers from the library.

Note the part of the C++ Standard Library which makes use of templates such as <vector>, string>, <map>, etc is header-only library.

Actually templates (class templates and function templates) cannot be compiled into static or dynamic library to be linked to programs. A template is, as the term itself says, a template; it's not normal code; its only when you use it in your code passing template argument(s) (which is either type or value), the compiler generates a compilable function/class out of the function/class template:

template<typename T>
struct A
{
   T data;
};

struct B
{
   int data;
};

Here, A cannot be compiled into binary (static library or dynamic library), because the compiler doesn't know what T is. But B can be compiled into binary, as the compiler has complete information about it.

So you can read the phrase "class template A" as : A is a template for a class. A itself is not a class. But B is a class, its not a template.

As the class template A cannot be compiled into static or dynamic library to be linked to your programs, so A can be shipped only as header-only library with full source code. Likewise

Answer 5

It means that you do not have to link any external libraries during the linking phase of your development. You only have to download the library and use #include macros to use the library. It simplifies deployment of your application down the road, but sometimes at the expense of longer compiler times.

Answer 6

It's "header only" because it contains no separate .cpp files, only .h files and so you can just #include all the library code into your code.

This can be advantageous since you don't have to link against a static library which can be very painful.