24

I want to write a library that to use, you only need to include one header file. However, if you have multiple source files and include the header in both, you'll get multiple definition errors, because the library is both declared and defined in the header. I have seen header-only libraries, in Boost I think. How did they do that?

Epro
  • 673
  • 2
  • 7
  • 9

4 Answers4

38

Declare your functions inline, and put them in a namespace so you don't collide:

namespace fancy_schmancy
{
  inline void my_fn()
  {
    // magic happens
  }
};
John Dibling
  • 99,718
  • 31
  • 186
  • 324
  • 1
    But, is it recommended to make **all** functions `inline` irrespective of their nature? I thought only "short" functions should be `inline`'d. – Arun Oct 19 '10 at 23:57
  • 6
    Ignore your professors. They don't write code for a living. "Only short functions should be inlined" is a rule of thumb, but there are so many exceptions and so many other more important reasons why you should or should *not* inline a function so as to make the rule of thumb almost useless. – John Dibling Oct 20 '10 at 00:10
  • 1
    "Premature micro-optimization is the root of all evil" being the first reason not to inline that comes to mind. – John Dibling Oct 20 '10 at 00:14
  • 4
    @Arun: The compiler isn't required to inline all `inline` functions, and it can't in the case you call through a function pointer. The `inline` keyword is a hint that inlining might be nice, but more importantly it's a linkage modifier. It's an unfortunate misnomer. Anyway, don't worry about your compiler doing anything stupid. – Potatoswatter Oct 20 '10 at 00:33
  • Dibing, @Potatoswatter: Thanks. May be I am missing something, but these comments sound like one could/should make whole project with `inline` functions. What is a good guideline to follow? Any link or book-chapter reference is appreciated. – Arun Oct 20 '10 at 00:42
  • 3
    @Arun: No *not* make the whole project `inline`. `inline` is a tool which serves a purpose ( a couple purposes, actually). In this case, and in most cases these days, the reason why we use `inline` is to satisfy the ODR -- not as a performance tweak. Understand the tool, where it applies and what it's effects are, and then use it where appropriate. – John Dibling Jan 29 '15 at 15:20
6

The main reason why Boost is largely header-only is because it's heavily template oriented. Templates generally get a pass from the one definition rule. In fact to effectively use templates, you must have the definition visible in any translation unit that uses the template.

Another way around the one definition rule (ODR) is to use inline functions. Actually, getting a free-pass from the ODR is what inline really does - the fact that it might inline the function is really more of an optional side-effect.

A final option (but probably not as good) is to make your functions static. This may lead to code bloat if the linker isn't able to figure out that all those function instances are really the same. But I mention it for completeness. Note that compilers will often inline static functions even if they aren't marked as inline.

Michael Burr
  • 333,147
  • 50
  • 533
  • 760
  • Well, the Boost docs cites the header-only nature of much of the library as a feature. And it's only the stuff that can't reasonably be header only (e.g. the regexp stuff has OS dependencies) that isn't header only. So while some sub-libraries undoubtedly are header only because they're template code, it's wrong to ascribe that reason to Boost as a whole, at least according to the docs. – Cheers and hth. - Alf Oct 19 '10 at 22:59
2

Boost uses header-only libraries a lot because like the STL, it's mostly built using class and function templates, which are almost always header-only.

If you are not writing templates I would avoid including code in your header files - it's more trouble than it's worth. Make this a plain old static library.

Steve Townsend
  • 53,498
  • 9
  • 91
  • 140
1

There are many truly header-only Boost libraries, but they tend to be very simple (and/or only templates). The bigger libraries accomplish the same effect through some trickery: they have "automatic linking" (you'll see this term used here). They essentially have a bunch of preprocessor directives in the headers that figure out the appropriate lib file for your platform and use a #pragma to instruct the linker to link it in. So you don't have to explicitly link it, but it is still being linked.

rmeador
  • 25,504
  • 18
  • 62
  • 103
  • How do you use the automatic linking thing in g++? I know in MSVC++ you can use `#pragma(lib, "blah.lib")` but how do you do the same with g++? – Epro Oct 20 '10 at 00:18
  • @Epro: I'm afraid I don't know how it's done. You might have to look at the Boost source. – rmeador Oct 20 '10 at 15:36