# spdlog Configuration Options in tweakme.h: Complete Compile-Time Customization Guide

> Unlock spdlog configuration options in tweakme.h for compile-time customization. Optimize logging with zero-cost filtering, coarse clocks, and external fmt integration.

- Repository: [Gabi Melman/spdlog](https://github.com/gabime/spdlog)
- Tags: deep-dive
- Published: 2026-07-12

---

**spdlog configuration options in tweakme.h allow you to customize logging behavior at compile time by uncommenting macros in [`include/spdlog/tweakme.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/tweakme.h), enabling optimizations like zero-cost filtering, coarse clocks, and external fmt library integration.**

spdlog is a header-only C++ logging library that achieves zero-overhead abstraction through compile-time configuration. The `spdlog configuration options in tweakme.h` provide a centralized mechanism to tailor performance characteristics, output formats, and platform-specific behaviors without runtime penalties. Located in [`include/spdlog/tweakme.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/tweakme.h), this file is automatically included by [`include/spdlog/common.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/common.h) and processed during the pre-processor phase, ensuring only required code paths exist in your final binary.

## Understanding tweakme.h Structure

The [`include/spdlog/tweakme.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/tweakme.h) file serves as the central configuration hub for the spdlog library. Unlike runtime configuration methods, these settings take effect during compilation, eliminating unnecessary overhead.

The file contains commented-out macro definitions that you uncomment to enable specific behaviors. Because [`include/spdlog/common.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/common.h) includes this file early in the compilation process, these definitions propagate throughout the library, affecting components in [`src/spdlog.cpp`](https://github.com/gabime/spdlog/blob/main/src/spdlog.cpp), [`src/async.cpp`](https://github.com/gabime/spdlog/blob/main/src/async.cpp), and [`src/file_sinks.cpp`](https://github.com/gabime/spdlog/blob/main/src/file_sinks.cpp).

## Performance Optimization Macros

### Clock Source Selection (SPDLOG_CLOCK_COARSE)

On Linux systems, uncomment `SPDLOG_CLOCK_COARSE` to use `CLOCK_REALTIME_COARSE` instead of the standard clock. This trades nanosecond precision for faster system calls, reducing latency in high-frequency logging scenarios.

### Eliminating Source Location Overhead (SPDLOG_NO_SOURCE_LOC)

When you define `SPDLOG_NO_SOURCE_LOC`, spdlog strips `__FILE__`, `__LINE__`, and `SPDLOG_FUNCTION` from log records. This reduces binary size and eliminates the overhead of capturing source locations, particularly beneficial in production builds where stack traces are handled externally.

```cpp
// In include/spdlog/tweakme.h
#define SPDLOG_NO_SOURCE_LOC

// In your application
#include <spdlog/spdlog.h>

int main() {
    spdlog::info("No __FILE__/__LINE__ info attached");
}

```

### Threading Optimizations

- **SPDLOG_NO_THREAD_ID**: Disables thread-ID lookup for the `%t` pattern placeholder. When enabled, `%t` resolves to `0`, eliminating thread-local storage lookups.
- **SPDLOG_NO_TLS**: Prevents thread-local storage usage for loggers. Essential when your application forks processes, as child processes inherit undefined thread IDs from parents.
- **SPDLOG_NO_ATOMIC_LEVELS**: Removes atomic operations on logger levels. Only safe when log levels remain static after initialization, removing memory barriers in hot paths.

## Content and Format Customization

### Custom Level Names (SPDLOG_LEVEL_NAMES and SPDLOG_SHORT_LEVEL_NAMES)

Redefine how severity levels appear in output:

```cpp
// In include/spdlog/tweakme.h
#define SPDLOG_LEVEL_NAMES { "TRC", "DBG", "INF", "WRN", "ERR", "CRT", "OFF" }
#define SPDLOG_SHORT_LEVEL_NAMES { "T", "D", "I", "W", "E", "C", "O" }

// In your application
#include <spdlog/spdlog.h>

int main() {
    spdlog::warn("This prints WRN instead of warning");
}

```

These arrays map directly to spdlog's level enum (trace, debug, info, warning, error, critical, off).

### Line Endings and Path Separators

- **SPDLOG_EOL**: Override the default newline sequence (`"\n"` on Linux, `"\r\n"` on Windows).
- **SPDLOG_FOLDER_SEPS**: Define custom characters recognized as folder separators for file sink path handling.
- **SPDLOG_FUNCTION**: Override the function name macro (default is `__FUNCTION__` or `__PRETTY_FUNCTION__` depending on compiler).

## Platform-Specific Configuration

### Windows Character Encoding

- **SPDLOG_WCHAR_FILENAMES**: Enables `wchar_t` support for file sink paths on Windows.
- **SPDLOG_WCHAR_TO_UTF8_SUPPORT**: Automatically converts wide-character log messages to UTF-8 encoding.

### File Descriptor Handling (SPDLOG_PREVENT_CHILD_FD)

Define `SPDLOG_PREVENT_CHILD_FD` to set `O_CLOEXEC` or equivalent flags on log file descriptors. This prevents child processes spawned via `fork()`/`exec()` from inheriting open log files, avoiding duplicate writes and file corruption in multi-process architectures.

```cpp
// In include/spdlog/tweakme.h
#define SPDLOG_PREVENT_CHILD_FD

#include <spdlog/sinks/basic_file_sink.h>
#include <unistd.h>

int main() {
    auto logger = spdlog::basic_logger_mt("file_logger", "app.log");
    pid_t pid = fork();
    if (pid == 0) { 
        /* child process - file descriptor is automatically closed */ 
        execvp("ls", nullptr); 
    }
}

```

## Third-Party Integration

### External Formatting Libraries

- **SPDLOG_FMT_EXTERNAL**: Links against an external **fmt** library instead of the bundled version. Requires adding `-I<path/to/fmt/include>` to your build flags and linking against fmt.
- **SPDLOG_USE_STD_FORMAT**: Switches to C++20 `std::format`, removing the fmt dependency entirely (requires C++20 compliant compiler).

```cpp
// In include/spdlog/tweakme.h
#define SPDLOG_FMT_EXTERNAL

// Build with: -I/path/to/fmt/include
#include <spdlog/spdlog.h>

int main() {
    spdlog::info("Formatted number: {}", 42);
}

```

### Default Logger Control

`SPDLOG_DISABLE_DEFAULT_LOGGER` skips creation of the implicit global logger in [`src/spdlog.cpp`](https://github.com/gabime/spdlog/blob/main/src/spdlog.cpp). Use this in embedded systems or when you explicitly manage all logger instances to save initialization time and memory.

## Compile-Time Level Filtering

The `SPDLOG_ACTIVE_LEVEL` macro provides zero-cost log level filtering. Unlike runtime `set_level()` calls, this macro causes logging macros below the specified level to compile to no-ops.

```cpp
// In include/spdlog/tweakme.h
#define SPDLOG_ACTIVE_LEVEL SPDLOG_LEVEL_INFO

// In your application
#include <spdlog/spdlog.h>

int main() {
    spdlog::debug("This call generates zero machine code");  // Eliminated at compile time
    spdlog::info("Application started");                     // Executed
}

```

Available levels: `SPDLOG_LEVEL_TRACE`, `SPDLOG_LEVEL_DEBUG`, `SPDLOG_LEVEL_INFO`, `SPDLOG_LEVEL_WARN`, `SPDLOG_LEVEL_ERROR`, `SPDLOG_LEVEL_CRITICAL`, `SPDLOG_LEVEL_OFF`.

## Practical Configuration Examples

### High-Performance Server Configuration

For production servers requiring minimal latency:

```cpp
// In include/spdlog/tweakme.h
#define SPDLOG_CLOCK_COARSE
#define SPDLOG_NO_SOURCE_LOC
#define SPDLOG_NO_THREAD_ID
#define SPDLOG_ACTIVE_LEVEL SPDLOG_LEVEL_INFO

```

### Fork-Safe Daemon Configuration

```cpp
// In include/spdlog/tweakme.h
#define SPDLOG_NO_TLS
#define SPDLOG_PREVENT_CHILD_FD

```

## Summary

- spdlog configuration options in tweakme.h reside in [`include/spdlog/tweakme.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/tweakme.h) and are included automatically by [`include/spdlog/common.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/common.h).
- These macros operate at compile time, eliminating runtime overhead for disabled features.
- **SPDLOG_ACTIVE_LEVEL** provides zero-cost filtering by compiling out log statements below the specified level.
- Performance options like **SPDLOG_CLOCK_COARSE**, **SPDLOG_NO_SOURCE_LOC**, and **SPDLOG_NO_ATOMIC_LEVELS** minimize latency in high-frequency logging scenarios.
- Platform-specific macros such as **SPDLOG_WCHAR_FILENAMES** and **SPDLOG_PREVENT_CHILD_FD** handle operating system differences.
- Integration macros **SPDLOG_FMT_EXTERNAL** and **SPDLOG_USE_STD_FORMAT** allow switching between bundled fmt, external fmt, or C++20 std::format.

## Frequently Asked Questions

### What is tweakme.h in spdlog?

The [`include/spdlog/tweakme.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/tweakme.h) file is the central compile-time configuration header for the spdlog library. It contains commented-out macro definitions that you uncomment to enable specific optimizations, customizations, and platform-specific behaviors. Because these settings are processed by the pre-processor before compilation, they create zero runtime overhead for features you disable.

### How do I use an external fmt library with spdlog?

Uncomment `SPDLOG_FMT_EXTERNAL` in [`include/spdlog/tweakme.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/tweakme.h) and ensure your build system includes the path to your fmt installation with `-I<path/to/fmt/include>` and links against the fmt library. This configuration forces spdlog to use your system's fmt headers instead of the bundled version in `include/spdlog/fmt/`.

### What is the difference between SPDLOG_ACTIVE_LEVEL and set_level()?

`SPDLOG_ACTIVE_LEVEL` is a compile-time filter defined in [`tweakme.h`](https://github.com/gabime/spdlog/blob/main/tweakme.h) that causes logging macros below the specified level to compile into no-operations, completely removing them from the binary. In contrast, `logger->set_level()` is a runtime method that checks the level during execution and can be changed dynamically. Use `SPDLOG_ACTIVE_LEVEL` for zero-cost filtering in performance-critical paths where levels won't change.

### How do I prevent child processes from inheriting log file descriptors?

Define `SPDLOG_PREVENT_CHILD_FD` in [`include/spdlog/tweakme.h`](https://github.com/gabime/spdlog/blob/main/include/spdlog/tweakme.h). This macro ensures that file sinks in [`src/file_sinks.cpp`](https://github.com/gabime/spdlog/blob/main/src/file_sinks.cpp) open files with `O_CLOEXEC` (or equivalent flags), preventing file descriptor inheritance across `fork()` and `exec()` calls. This is essential for daemon processes that spawn child processes to avoid duplicate log entries and file corruption.