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

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 2

Some libraries take the form of a binary file you must link with your project, along with a header file that defines the available classes or functions. A "header-only library" would be one that includes no binary file, just a header you include in your source.

Templates are classes or functions that are customized to their particular use; they're typically defined in a header file since the compiler must read their source to customize them. You can't compile a template to a binary file until you know exactly how it's going to be used, so you include the source along with your own code and the compiler can then process them together.

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

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.