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

> Master fmtlib CMake options like FMT_UNICODE, FMT_PEDANTIC, and FMT_WERROR. Control Unicode, pedantic warnings, and error policies for robust C++ formatting. Configure your build effectively.

- Repository: [Hello World Foundation/fmt](https://github.com/fmtlib/fmt)
- Tags: how-to-guide
- Published: 2026-09-04

---

**The fmt library exposes three primary CMake cache variables—`FMT_UNICODE`, `FMT_PEDANTIC`, and `FMT_WERROR`—in its top-level [`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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
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:

```cpp
#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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt) (lines 89–91) and publicly documented in [`doc/api.md`](https://github.com/fmtlib/fmt/blob/main/doc/api.md), which provides an overview of all cache variables available for customizing the `fmt` build.