CMake Options for fmtlib: How to Configure FMT_UNICODE, FMT_PEDANTIC, and FMT_WERROR

The fmt library exposes three primary CMake cache variables—FMT_UNICODE, FMT_PEDANTIC, and FMT_WERROR—in its top-level CMakeLists.txt to control Unicode support, strict compiler warnings, and fatal error policies, respectively.

The fmtlib/fmt repository provides a high-performance, header-only capable C++ formatting library. When embedding the library into your project, you can customize the build behavior via specific CMake options for configuring fmtlib without touching the source code. These switches are declared in the root CMakeLists.txt and affect everything from binary size to compilation strictness.

FMT_UNICODE: Enabling or Disabling UTF-8 Support

FMT_UNICODE defaults to ON in the build configuration according to CMakeLists.txt:89. When active, the library fully supports UTF-8 string handling and conversion routines. Setting this option to OFF forces the macro FMT_UNICODE to 0, which strips out UTF-8 specific code paths in include/fmt/base.h:451–455 and reduces final binary size for ASCII-only applications.

FMT_PEDANTIC: Activating Extra Warnings and Expensive Tests

FMT_PEDANTIC defaults to OFF as defined in CMakeLists.txt:90. Enabling this option appends aggressive compiler flags such as -Wall, -Wextra, and /W4 (when using MSVC) to the build. Additionally, the test suite logic in test/CMakeLists.txt:115 checks this variable to include computationally expensive validation tests that verify strict C++ standard conformance, which are skipped by default to preserve CI speed.

FMT_WERROR: Treating Warnings as Errors

FMT_WERROR defaults to OFF (CMakeLists.txt:91). When toggled to ON, the build system injects -Werror for GCC and Clang or /WX for MSVC, converting every compiler warning into a hard error. This ensures that all diagnosed issues must be resolved before the library compiles, enforcing a zero-warning policy for production builds.

Architectural Wiring of CMake Options in fmtlib

Understanding how these settings propagate from CMake to compiled code clarifies their impact.

From CMake Cache to Compiler Flags

In the top-level CMakeLists.txt, each option is declared using the standard option() command, making them visible in ccmake or cmake-gui and overridable via the command line. The values are cached in CMakeCache.txt and persist across incremental builds.

Integration with Source Headers

The FMT_UNICODE value is passed as a compile definition. In include/fmt/base.h, the code contains a static assertion verifying that the use_utf8 template parameter aligns with the FMT_UNICODE macro state. Disabling the option removes UTF-8 conversion branches at compile time, preventing linkage of related routines.

Impact on the Test Harness

The FMT_PEDANTIC flag does not alter library headers directly; instead, it drives the test infrastructure. When enabled, test/CMakeLists.txt appends additional warning flags to test targets and defines FMT_PEDANTIC=1, allowing conditional inclusion of pedantic test cases that perform deep conformance checks.

Practical Configuration Examples

Configure a minimal, strict build that disables Unicode, enables pedantic checks, and treats warnings as errors:

cmake -B build \
      -DCMAKE_BUILD_TYPE=Release \
      -DFMT_UNICODE=OFF \
      -DFMT_PEDANTIC=ON \
      -DFMT_WERROR=ON

Verify the configuration in your C++ source using preprocessor directives:

#include <fmt/base.h>

#if FMT_UNICODE
    // Conditionally compile Unicode-specific formatting logic
#endif

#ifdef FMT_PEDANTIC
    // Enable additional runtime assertions during testing
#endif

Summary

• FMT_UNICODE (CMakeLists.txt:89) controls UTF-8 support in include/fmt/base.h and defaults to ON for full internationalization.
• FMT_PEDANTIC (CMakeLists.txt:90) injects strict compiler diagnostics and expensive tests defined in test/CMakeLists.txt:115, defaulting to OFF.
• FMT_WERROR (CMakeLists.txt:91) elevates warnings to errors via -Werror or /WX, defaulting to OFF to permit incremental development.

Frequently Asked Questions

What is the default value of FMT_UNICODE in fmtlib?

According to the fmtlib/fmt source code in CMakeLists.txt:89, FMT_UNICODE defaults to ON, ensuring that UTF-8 string processing is available unless explicitly disabled by the user.

Does enabling FMT_PEDANTIC change the library's runtime behavior?

No. FMT_PEDANTIC only affects compile-time warning levels and expands the test suite to include strict conformance checks. It does not modify the runtime logic or performance characteristics of the compiled fmt library.

Can I use FMT_WERROR on Windows with MSVC?

Yes. The build script automatically detects the MSVC compiler and applies the /WX flag when FMT_WERROR is enabled, ensuring warnings are treated as errors on Windows exactly as -Werror does on GCC and Clang.

Where are these CMake options documented in the repository?

These options are declared in the root CMakeLists.txt (lines 89–91) and publicly documented in doc/api.md, which provides an overview of all cache variables available for customizing the fmt build.

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