# CMake Options for fmtlib: Complete Build Configuration Guide

> Explore all 11 CMake options for fmtlib to configure documentation, installation, tests, C++20 modules, and warning levels for your build.

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

---

**The fmt library exposes 11 boolean CMake options in [`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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:

```bash
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:

```bash
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):

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

```

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

```bash
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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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.