CMake Options for fmtlib: Complete Build Configuration Guide

The fmt library exposes 11 boolean CMake options in CMakeLists.txt that control documentation generation, installation targets, test suites, C++20 module support, and compiler warning levels.

The {fmt} library provides a fast, type-safe alternative to C printf and IOStreams. When integrating fmtlib/fmt into your project, understanding the available CMake options for fmtlib allows you to customize the build without modifying source files. These options are declared in the top-level CMakeLists.txt and evaluated during the configuration stage to determine which targets are generated and which compilation flags are applied.

Component Selection Options

The primary CMake options for fmtlib control whether documentation, installation rules, and various test suites are included in the build. These default to ON when fmt is the master project and OFF when included as a subdirectory.

• FMT_DOC: Generates the documentation target (make doc). Defaults to ON when fmt is the master project.
• FMT_INSTALL: Enables the install target so the library can be installed with cmake --install. Defaults to ON when fmt is the master project.
• FMT_TEST: Builds the built-in test suite. Defaults to ON when fmt is the master project.
• FMT_FUZZ: Builds fuzzing targets for libFuzzer or AFL. Always defaults to OFF.
• FMT_CUDA_TEST: Enables CUDA-specific tests requiring a CUDA-capable compiler. Defaults to OFF.

Feature and Compilation Flags

Additional CMake options for fmtlib manage C++20 modules, system header treatment, Unicode support, and compiler warning levels.

• FMT_OS: Includes OS-specific APIs such as fmt::fmt_system_error. Defaults to ON.
• FMT_MODULE: Builds fmt as a C++20 module library when compiler support is available. Defaults based on ${FMT_USE_MODULES}.
• FMT_SYSTEM_HEADERS: Exposes library headers as system headers, silencing warnings from user code that includes them. Defaults to OFF.
• FMT_UNICODE: Enables full Unicode/UTF-8 support in formatting functions. Defaults to ON.
• FMT_PEDANTIC: Activates strict compiler warnings and runs expensive tests. Defaults to OFF.
• FMT_WERROR: Treats compiler warnings as errors. Defaults to OFF.

Practical Configuration Examples

Use these command patterns to configure the fmt library for common scenarios.

Enable installation and treat warnings as errors:

cmake -S . -B build -DFMT_INSTALL=ON -DFMT_WERROR=ON
cmake --build build
cmake --install build

Build only the test suite, disabling documentation and fuzzing:

cmake -S . -B build -DFMT_TEST=ON -DFMT_DOC=OFF -DFMT_FUZZ=OFF
cmake --build build
ctest --test-dir build

Use fmt as a C++20 module (if the compiler supports it):

cmake -S . -B build -DFMT_MODULE=ON
cmake --build build

Compile with system-header mode to silence warnings from fmt headers:

cmake -S . -B build -DFMT_SYSTEM_HEADERS=ON
cmake --build build

Key Configuration Files

The CMake configuration for fmtlib is centralized in specific files that process these options:

• CMakeLists.txt – Top-level file where all options are defined and processed (lines 87-97).
• support/cmake/FindFmt.cmake – Helper module for locating fmt when used as a sub-project.
• test/**/CMakeLists.txt – Test subdirectories that respect FMT_TEST, FMT_FUZZ, and FMT_CUDA_TEST.

Summary

• The fmt library exposes 11 boolean options in its top-level CMakeLists.txt to control the build process.
• Options like FMT_DOC, FMT_INSTALL, and FMT_TEST default to ON for standalone builds but OFF when fmt is a subdirectory.
• Special-purpose options include FMT_MODULE for C++20 modules and FMT_SYSTEM_HEADERS for warning suppression.
• Compiler strictness is controlled via FMT_PEDANTIC and FMT_WERROR.
• All options are evaluated during the CMake configuration stage and influence both target generation and compilation flags.

Frequently Asked Questions

What is the default value of FMT_TEST in fmtlib?

FMT_TEST defaults to ON when the fmt repository is the master project (top-level) and OFF when it is included as a sub-project or subdirectory. This prevents unnecessary test compilation when fmt is used as a dependency via add_subdirectory.

How do I build fmt as a C++20 module?

Set -DFMT_MODULE=ON during CMake configuration. This option only takes effect if your compiler supports C++20 modules; the build system checks ${FMT_USE_MODULES} to determine availability. Use cmake -S . -B build -DFMT_MODULE=ON to enable this experimental feature.

Can I silence warnings from fmt headers in my project?

Yes. Enable the FMT_SYSTEM_HEADERS option by passing -DFMT_SYSTEM_HEADERS=ON to CMake. This marks the fmt headers as system headers, preventing compiler warnings from headers you do not control while preserving warnings for your own source files.

What is the difference between FMT_PEDANTIC and FMT_WERROR?

FMT_PEDANTIC enables an extensive set of compiler warnings (similar to -Wall -Wextra on GCC/Clang) and activates additional expensive runtime tests. FMT_WERROR simply treats all compiler warnings as errors, causing the build to fail if any warning is emitted. They can be used independently or together for maximum strictness.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}