# How to Configure fmtlib During the CMake Build Process: Complete Options Guide

> Learn how to configure fmtlib during your CMake build process. This guide covers all available options for documentation testing installation and module support.

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

---

**The fmt library exposes cache variables in [`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt) (lines 87‑99) that control documentation generation, testing, installation, and module support, which you can override using CMake `-D` flags.**

The {fmt} library provides a flexible CMake-based build system that allows you to customize every aspect of the compilation process. Whether you need a minimal header-only dependency, a shared library with C++20 modules, or a debug build with fuzzing support, you can configure fmtlib during the CMake build process through specific cache options. This guide covers the available configuration variables defined in the top-level [`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt) and demonstrates how to use them effectively.

## Core CMake Configuration Options

The primary configuration options are defined in [[`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt)](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt#L87-L99) around lines 87‑99. When building fmt as the master project, these cache variables determine which targets are generated and how the library behaves:

- **FMT_DOC** (`ON` by default) — Builds the documentation target (`make doc`).
- **FMT_INSTALL** (`ON` by default) — Creates the install target (`make install`).
- **FMT_TEST** (`ON` by default) — Compiles the test suite (`make test`).
- **FMT_FUZZ** (`OFF` by default) — Enables the fuzzing target for security testing.
- **FMT_CUDA_TEST** (`OFF` by default) — Builds CUDA-specific test targets.
- **FMT_OS** (`ON` by default) — Includes OS-specific APIs from `src/os.cc`.
- **FMT_MODULE** (`${FMT_USE_MODULES}` by default) — Builds the C++20 module library (`fmt-module`).
- **FMT_SYSTEM_HEADERS** (`OFF` by default) — Marks fmt headers as system headers to suppress compiler warnings.
- **FMT_UNICODE** (`ON` by default) — Enables Unicode support (adds `/utf-8` on MSVC).
- **FMT_PEDANTIC** (`OFF` by default) — Activates extra warnings and expensive compiler checks.
- **FMT_WERROR** (`OFF` by default) — Treats compiler warnings as errors.

## Setting Build Options with CMake Command Line

To configure fmtlib during the CMake build process, pass `-D` arguments when generating the build system. This approach modifies the CMake cache before compilation begins.

```bash

# Example: Release build without tests or documentation

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DFMT_TEST=OFF \
  -DFMT_DOC=OFF \
  -DFMT_INSTALL=ON

```

The `-S .` flag points CMake to the repository root, while `-B build` specifies a separate build directory. The `CMAKE_BUILD_TYPE` parameter determines optimization levels and debugging information.

## Advanced Configuration Scenarios

### Controlling Build Types and Debug Postfixes

According to the source code at [[`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt)](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt#L44-L48) lines 44‑48, the build type defaults to **Release** when `CMAKE_BUILD_TYPE` is unset. You can explicitly set this to `Debug`, `RelWithDebInfo`, or `MinSizeRel`.

When building in Debug mode, the library name receives the debug postfix defined at lines 12‑14. The `FMT_DEBUG_POSTFIX` variable defaults to `d`, producing `fmtd` instead of `fmt`.

```bash

# Debug build with warnings as errors

cmake -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DFMT_WERROR=ON \
  -DFMT_PEDANTIC=ON

```

### Enabling C++20 Module Support

Module support depends on your CMake version, compiler capabilities, and generator, as implemented in [[`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt)](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt#L58-L78) lines 58‑78. The `FMT_MODULE` option controls whether CMake generates the `fmt-module` target.

```bash

# Force C++20 module build (requires compatible compiler)

cmake -B build -DFMT_MODULE=ON

# Explicitly disable module support

cmake -B build -DFMT_MODULE=OFF

```

### Custom Installation Paths

You can override the default installation directories using variables defined around lines 107‑110 and 500‑506. These control where headers, libraries, and CMake config files are installed.

```bash
cmake -B build \
  -DFMT_INC_DIR=/usr/local/include/fmt \
  -DFMT_LIB_DIR=/usr/local/lib \
  -DFMT_CMAKE_DIR=/usr/local/lib/cmake/fmt

```

## Common Build Configurations

### Minimal Shared Library Build

For production deployments where you need only the runtime library without development overhead:

```bash
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DFMT_TEST=OFF \
  -DFMT_DOC=OFF \
  -DBUILD_SHARED_LIBS=ON
cmake --build build
cmake --install build

```

### Header-Only Integration

If your project requires a header-only version of fmt, no special CMake flags are needed during the fmt build. Instead, link against the `fmt-header-only` target in your project's [`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt). This target is defined at [[`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt)](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt#L54-L59) lines 54‑59.

```cmake
find_package(fmt REQUIRED)
target_link_libraries(my_app PRIVATE fmt::fmt-header-only)

```

### Security-Focused Debug Build

For fuzzing and strict warning checks during development:

```bash
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DFMT_FUZZ=ON \
  -DFMT_PEDANTIC=ON \
  -DFMT_WERROR=ON
cmake --build build

```

### C Interface Only

To build only the C compatibility layer (`fmt-c`) without the C++ library, as defined at lines 60‑86:

```bash
cmake -S . -B build -DFMT_INSTALL=ON
cmake --build build --target fmt-c

```

## Summary

- **Cache variables** such as `FMT_DOC`, `FMT_TEST`, and `FMT_INSTALL` in [`CMakeLists.txt`](https://github.com/fmtlib/fmt/blob/main/CMakeLists.txt) (lines 87‑99) control which targets fmt generates.
- **Build types** default to Release (lines 44‑48) but can be overridden with `CMAKE_BUILD_TYPE`, automatically applying the debug postfix `d` (lines 12‑14).
- **Module support** (`FMT_MODULE`) requires C++20 and appropriate CMake versions (lines 58‑78).
- **Installation paths** are customizable via `FMT_INC_DIR`, `FMT_LIB_DIR`, and `FMT_CMAKE_DIR`.
- **Header-only usage** requires no build-time flags; simply link to `fmt::fmt-header-only` in your consuming project.

## Frequently Asked Questions

### How do I disable test building in fmtlib?

Set `-DFMT_TEST=OFF` when running CMake. By default, `FMT_TEST` is `ON` when fmt is the master project, but disabling it reduces build time significantly in CI/CD pipelines and production builds.

### Can I build fmtlib as a shared library?

Yes. Pass `-DBUILD_SHARED_LIBS=ON` to CMake. This produces shared object files or DLLs instead of static archives. Ensure the `FMT_INSTALL` option remains enabled if you need the install target for system-wide deployment.

### What is the difference between `FMT_PEDANTIC` and `FMT_WERROR`?

`FMT_PEDANTIC` enables additional compiler warnings and expensive static analysis checks suitable for development and CI environments. `FMT_WERROR` elevates all warnings to errors, causing the build to fail if any warnings are emitted. These are typically used together in quality assurance workflows.

### How do I enable C++20 modules for fmt?

Set `-DFMT_MODULE=ON` during configuration. This requires a compiler with C++20 module support (such as GCC 11+, Clang 16+, or MSVC 2019 16.11+) and a compatible CMake generator. The option creates the `fmt-module` target in addition to the standard `fmt` target.