Header-Only vs Compiled Libraries

C++ libraries come in two flavors:

• Header-only — implementation in headers; consumer compiles everything
• Compiled — separate source files compiled into a static or shared library

Strengths:

• Trivial to integrate — copy and include
• No build configuration
• Works across compilers and standards
• Compiler can inline aggressively

Weaknesses:

• Slow compile times — every consumer rebuilds everything
• ABI is whatever the consumer compiles with
• Implementation visible to all consumers
• Increases binary size if many TUs use the same templates

Many popular libraries are header-only:

• nlohmann/json
• spdlog (header-only mode)
• cxxopts
• Catch2 (header-only variant)

Strengths:

• Fast compile times for consumers
• Implementation details hidden
• Single instantiation of templates
• Can ship as a binary (no source disclosure)

Weaknesses:

• ABI compatibility is fragile
• Build configuration must match between library and consumer
• Static linking bloats binaries; dynamic linking needs runtime loading

Two compiled forms:

• Static (.a, .lib) — linked into the executable at build time
• Shared (.so, .dll, .dylib) — loaded at runtime

Templates resist non-header-only distribution — generic code is instantiated per consumer. Some libraries provide a "non-templated" core in a compiled .a and headers for thin templates.

Some libraries support both — single-header mode for quick use, multi-file mode for faster builds.

If your header-only library is large, precompiled headers (PCH) can significantly speed up consumer builds.

C++20 modules promise to replace headers — better encapsulation, faster builds, less reliance on the preprocessor. Adoption is gradual due to compiler and tooling support.

Quick guide:

• Small utility libraries → header-only
• Large libraries with significant implementation → compiled
• Heavily templated libraries → header-only or hybrid

What is the biggest disadvantage of header-only libraries for consumers?

Header-only libraries are easy to integrate but slow consumer builds. Compiled libraries are faster to use but trickier to distribute. Templates favor header-only; large implementations favor compiled. C++20 modules may replace headers in the future.