fmtlib/fmt
1
0
Fork 1
mirror of https://github.com/fmtlib/fmt.git synced 2025-10-02 01:20:55 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add compile-time options to API documentation (#4551)

Browse Source
This commit is contained in:
teruyamato0731
2025-10-01 06:03:11 +09:00
committed by GitHub
parent 5f66e07cb0
commit 4801f54e59
1 changed files with 41 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
doc/api.md
View File

@@ -708,3 +708,44 @@ following differences:
`std::to_chars` which tries to generate the smallest number of characters `std::to_chars` which tries to generate the smallest number of characters
(ignoring redundant digits and sign in exponent) and may procude more (ignoring redundant digits and sign in exponent) and may procude more
decimal digits than necessary. decimal digits than necessary.
## Compile-Time Configuration
{fmt} provides configuration via CMake options and preprocessor macros to enable or disable features and to optimize for binary size. You can set CMake options when generating your build system (e.g. `-DFMT_OS=OFF`) and define macros or pass them to your compiler (e.g. `-DFMT_USE_EXCEPTIONS=0`).
### Available Options
| Option | Type | Default | Description |
| -------------------- | ------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Header-Only Mode | CMake target | `fmt::fmt` | Enable header-only usage by linking the `fmt::fmt-header-only` target. |
| `FMT_HEADER_ONLY` | 0 / 1 | 0 | Enables header-only mode when set to 1 (CMake target `fmt::fmt-header-only` defines it); disable with 0 for library mode. |
| `FMT_OS` | ON / OFF | ON | Enables OS-specific APIs (`fmt/os.h`); disable with OFF. |
| `FMT_UNICODE` | ON / OFF | ON | Enables Unicode support; disable with OFF. |
| `FMT_USE_EXCEPTIONS` | 0 / 1 | 1 (0 if compiled with `-fno-exceptions`) | Enables exception-based error handling; disable with 0. |
| `FMT_BUILTIN_TYPES` | 0 / 1 | 1 | Enables built-in type formatters; disable with 0. |
| `FMT_OPTIMIZE_SIZE` | 0 / 1 / 2 | 0 | Controls size-optimized routines: 0 = off, 1 = size optimization, >1 = aggressive size optimization disabling format-string checks. |
| `FMT_USE_LOCALE` | 0 / 1 | 1 (0 when `FMT_OPTIMIZE_SIZE > 1`) | Enables locale-dependent formatting; disable with 0. |
| `FMT_THROW(x)` | macro | `throw x` (or `abort`) | Defines error handling via macro (not a toggle flag): if exceptions enabled, `throw x`; otherwise, `fmt::assert_fail(...)`. |
### Size Optimization Recipe
To minimize your binary footprint, use the following CMake configuration and compile definitions:
```cmake
# Link to the header-only target
target_link_libraries(${PROJECT_NAME} PRIVATE fmt::fmt-header-only)
# Disable OS-specific APIs
set(FMT_OS OFF CACHE BOOL "" FORCE)
# Disable Unicode support
set(FMT_UNICODE OFF CACHE BOOL "" FORCE)
# Add compile definitions to your target
target_compile_definitions(
${PROJECT_NAME}
PRIVATE
FMT_USE_EXCEPTIONS=0
FMT_OS=0
FMT_BUILTIN_TYPES=0
FMT_OPTIMIZE_SIZE=2
FMT_USE_LOCALE=0
)
```