How to create a header-only library in C ? (Best Practices)

Header-only C libraries place all code in .h/.hpp files, requiring inline functions, templates, and constexpr entities to avoid ODR violations; use include guards, minimize dependencies, prefer templates, and test across compilers.

A header-only C library means all declarations and definitions live in one or more .h (or .hpp) files — no separate compilation step, no linking required. It’s simple to distribute and use, but requires careful design to avoid ODR violations, bloat, and poor compile times.

Use include guards and #pragma once

Prevent multiple inclusions — essential for headers. Prefer both for robustness:

• #pragma once is widely supported and efficient
• Fallback to traditional include guards (#ifndef MYLIB_HPP_...) for maximum portability

Declare and define everything in the header — but mind the ODR

Only inline functions, templates, constexpr entities, and class definitions belong directly in headers. Avoid non-inline free functions or static data unless marked inline (C 17) or static:

• ✅ inline void helper() { ... } — safe across TUs
• ✅ template<typename t> T identity(T x) { return x; }</typename>
• ❌ void bad_helper() { ... } — violates ODR if included in multiple TUs
• ✅ inline constexpr int version = 1; — safe since C 17

Prefer templates and constexpr over non-templated logic

Templates naturally live in headers and generate code only when instantiated. Use them for generic utilities, algorithms, and type-safe wrappers:

• Implement containers, math helpers, or serialization traits as templates
• Mark constexpr functions and variables where possible — they’re implicitly inline and enable compile-time evaluation
• Avoid “hidden” non-templated implementation details — if you need complex logic, consider whether it truly belongs in a header-only form

Minimize dependencies and transitive includes

Header-only libraries are pulled into every translation unit that includes them. Heavy dependencies (e.g., <boost></boost> or large third-party headers) increase compile time and coupling:

• Include only what’s strictly needed — forward-declare types when possible
• Prefer standard headers like <type_traits></type_traits>, <utility></utility>, or <memory></memory> over heavier ones like <sstream></sstream> unless necessary
• Document optional features behind preprocessor guards (e.g., #ifdef MYLIB_ENABLE_JSON) so users can exclude unused parts

Test and document usage clearly

Since there’s no build step, users just #include and go — but they need to know how:

• Provide a minimal working example in comments or a README
• Specify minimum compiler versions (e.g., C 17 for inline variables or if constexpr)
• Test with multiple compilers (GCC, Clang, MSVC) and standard modes (-std=c 17, -std=c 20)
• Use static_assert to validate assumptions (e.g., trait requirements or platform constraints)

Done right, a header-only library delivers simplicity without sacrificing correctness or performance — just keep definitions inline, dependencies lean, and interfaces intentional.

The above is the detailed content of How to create a header-only library in C ? (Best Practices). For more information, please follow other related articles on the PHP Chinese website!