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

Forefend

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

Emiliaemiliaromagna

or .hpp, or .hxx, or something else ;) – Marquittamarr

and is it there any advantage for doing this in terms of execution speed, code clarity, organization, etc? – Forefend

@gpu_drug: Read the last para. I added it for you. :-) – Emiliaemiliaromagna

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.

Gibun

Answer 3

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

Nicobarese

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.

Epithelioma

Newbie question: So, every #includeed file is template code? If not (if only declarations are #included), where are the definitions? Or, the definition part is already compiled and exists somewhere as static library files, ready to be linked when the final executable is made? – Fremantle

Includes include definitions of functions and template declarations. The definitions allow the compiler to know these functions are implemented elsewhere. Templates inform the compiler how to build the code that rely on them. – Epithelioma

Answer 5

It means that all of the code is in header files; there are no libraries associated with the library. What that means in practice depends—in the worst case, it means that the author has never even compiled the code:-). Most likely, it means that the code has never been tested with the exact combination of compiler, version and options that you use, and that compile times will shoot way up. On the other hand, it means that you can use the library even if the author doesn't have access to the same compiler as you, and you're not forced to use whatever options he used when he compiled the library. Or alternatively, if it is open source, you don't have to build the library yourself.

Overissue

Answer 6

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.

Pelagic

Answer 7

For template libraries, it's possible to provide all of the functionality in just header (.h files) because traditionally compilers needed the full definition of the template class in order to instantiate for a given type. There is nothing to put in a library unless the library is going to provide pre-instantiated versions or if there is some portion of the template library that doesn't need to be templated.

Forgetful

Answer 8

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.

Loyalist

Answer 9

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.

Pinworm