coffee/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2025-12-07 17:26:54 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'fmtlib:master' into master

Browse Source
This commit is contained in:
LiangHu 2025-10-15 12:42:39 +08:00 committed by GitHub
commit d4acfbb029
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 43 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
doc/api.md
View File

@ -709,43 +709,52 @@ following differences:
(ignoring redundant digits and sign in exponent) and may procude more
decimal digits than necessary.
## Compile-Time Configuration
## Configuration Options
{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`).
{fmt} provides configuration via CMake options and preprocessor macros to
enable or disable features and to optimize for binary size. For example, you
can disable OS-specific APIs defined in `fmt/os.h` with `-DFMT_OS=OFF` when
configuring CMake.
### Available Options
### CMake 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(...)`. |
- **`FMT_OS`**: When set to `OFF`, disables OS-specific APIs (`fmt/os.h`).
- **`FMT_UNICODE`**: When set of `OFF`, disables Unicode support on
Windows/MSVC. Unicode support is always enabled on other platforms.
### Size Optimization Recipe
### Macros
To minimize your binary footprint, use the following CMake configuration and compile definitions:
- **`FMT_HEADER_ONLY`**: Enables the header-only mode when defined. It is an
alternative to using the `fmt::fmt-header-only` CMake target.
Default: not defined.
```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
)
```
- **`FMT_USE_EXCEPTIONS`**: Disables the use of exceptions when set to `0`.
Default: `1` (`0` if compiled with `-fno-exceptions`).
- **`FMT_USE_LOCALE`**: When set to `0`, disables locale support.
Default: `1` (`0` when `FMT_OPTIMIZE_SIZE > 1`).
- **`FMT_CUSTOM_ASSERT_FAIL`**: When set to `1`, allows users to provide a
custom `fmt::assert_fail` function which is called on assertion failures and,
if exceptions are disabled, on runtime errors. Default: `0`.
- **`FMT_BUILTIN_TYPES`**: When set to `0`, disables built-in handling of
arithmetic and string types other than `int`. This reduces library size at
the cost of per-call overhead. Default: `1`.
- **`FMT_OPTIMIZE_SIZE`**: Controls binary size optimizations:
- `0` - off (default)
- `1` - disables locale support and applies some optimizations
- `2` - disables some Unicode features, named arguments and applies more
aggresive optimizations
### Binary Size Optimization
To minimize the binary footprint of {fmt} as much as possible at the cost of
some features, you can use the following configuration:
- CMake options:
- `FMT_OS=OFF`
- Macros:
- `FMT_BUILTIN_TYPES=0`
- `FMT_OPTIMIZE_SIZE=2`