Configuration Options in tweakme.h for spdlog Customization: Complete Macro Reference

The tweakme.h header provides compile-time configuration macros that let you customize clock sources, disable thread-local storage, switch formatting backends, and define custom log levels by uncommenting definitions in include/spdlog/tweakme.h.

The spdlog library achieves its reputation as a fast, header-only C++ logging solution through aggressive compile-time optimization. All configuration options in tweakme.h for spdlog customization reside in include/spdlog/tweakme.h, a file that include/spdlog/common.h automatically includes before processing the rest of the library. By modifying this header, you eliminate unwanted features at the preprocessor stage, ensuring zero runtime overhead for disabled functionality.

How tweakme.h Works

The file include/spdlog/tweakme.h contains commented-out macro definitions that permeate the entire codebase. When you uncomment a macro, it affects implementation details in src/spdlog.cpp, src/async.cpp, and src/file_sinks.cpp. Because these are evaluated at pre-processor time, the resulting binary contains only the code paths you require, minimizing both compile-time and runtime overhead.

Compile-Time Performance Options

SPDLOG_ACTIVE_LEVEL

This macro sets a zero-cost compile-time filter. When defined, logging macros below the specified level compile to no-ops.

/* In include/spdlog/tweakme.h */
#define SPDLOG_ACTIVE_LEVEL SPDLOG_LEVEL_INFO

#include <spdlog/spdlog.h>

int main() {
    spdlog::debug("This will be stripped out");  // No code generated
    spdlog::info("Application started");         // Executed
}

SPDLOG_NO_SOURCE_LOC

Eliminates source-location data (__FILE__, __LINE__, SPDLOG_FUNCTION) from log messages, shrinking output and avoiding associated overhead.

/* In include/spdlog/tweakme.h */
#define SPDLOG_NO_SOURCE_LOC

#include <spdlog/spdlog.h>

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

SPDLOG_NO_THREAD_ID

Disables thread-ID lookup for the %t pattern placeholder. If a pattern contains %t, the value becomes 0.

SPDLOG_NO_TLS

Prevents usage of thread-local storage for loggers. This is essential when the process forks to avoid undefined thread IDs in child processes.

SPDLOG_NO_ATOMIC_LEVELS

Removes atomic operations on logger levels. This is safe only when levels are never changed concurrently after initialization.

SPDLOG_CLOCK_COARSE

On Linux, switches the clock source to CLOCK_REALTIME_COARSE for faster but less accurate timestamps.

Platform and Character Encoding Options

SPDLOG_WCHAR_FILENAMES

Enables wchar_t file-name support for file sinks on Windows.

SPDLOG_WCHAR_TO_UTF8_SUPPORT

Enables automatic conversion of wchar_t messages to UTF-8 before logging.

SPDLOG_EOL

Overrides the default end-of-line sequence ("\n" on Linux, "\r\n" on Windows).

SPDLOG_FOLDER_SEPS

Supplies a custom set of characters treated as folder separators in file paths.

SPDLOG_FUNCTION

Allows overriding the macro used for function names, such as substituting __PRETTY_FUNCTION__ for __FUNCTION__.

External Dependencies and Formatting Backends

SPDLOG_FMT_EXTERNAL

Skips spdlog’s bundled copy of the fmt library, requiring you to link against an external version.

/* 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);
}

SPDLOG_USE_STD_FORMAT

Replaces the fmt library with C++20 std::format for formatting operations.

Process Management and Initialization

SPDLOG_PREVENT_CHILD_FD

Stops child processes from inheriting log file descriptors after fork()/exec() calls.

/* 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 */ 
        execvp("ls", nullptr); 
    }
}

SPDLOG_DISABLE_DEFAULT_LOGGER

Skips creation of the implicit global logger in src/spdlog.cpp, saving initialization time in specialized environments.

Customizing Log Level Names

SPDLOG_LEVEL_NAMES

Defines custom full names for log levels as a compile-time array.

/* In include/spdlog/tweakme.h */
#define SPDLOG_LEVEL_NAMES { "TRC", "DBG", "INF", "WRN", "ERR", "CRT", "OFF" }

#include <spdlog/spdlog.h>

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

SPDLOG_SHORT_LEVEL_NAMES

Defines custom short (typically single-character) level identifiers used by the %l pattern specifier.

Summary

• All configuration options in tweakme.h for spdlog customization are centralized in include/spdlog/tweakme.h, which include/spdlog/common.h includes automatically.
• These macros are evaluated at preprocessor time, completely eliminating code paths for disabled features rather than adding runtime checks.
• Key implementation files affected by these settings include src/spdlog.cpp (default logger), src/async.cpp (threading), and src/file_sinks.cpp (file operations).
• You can define these macros either by editing tweakme.h directly or by passing -D flags to your compiler command line.

Frequently Asked Questions

Where is the tweakme.h file located in the spdlog repository?

The file is located at include/spdlog/tweakme.h in the gabime/spdlog repository. According to the source code, this header is automatically included by include/spdlog/common.h, ensuring your configuration is applied across all spdlog components.

Do I need to rebuild my project after modifying tweakme.h?

Yes. Because these are compile-time configuration options processed by the C++ preprocessor, you must recompile all translation units that include spdlog headers after uncommenting any macros in tweakme.h.

Can I define tweakme.h macros via compiler flags instead of editing the file?

Absolutely. You can pass definitions directly to your compiler (e.g., -DSPDLOG_ACTIVE_LEVEL=SPDLOG_LEVEL_INFO or -DSPDLOG_FMT_EXTERNAL) to override the defaults without modifying the tweakme.h file itself, which is useful for maintaining pristine submodule copies.

What happens if I enable SPDLOG_NO_THREAD_ID but my format pattern includes %t?

According to the spdlog source implementation, if SPDLOG_NO_THREAD_ID is defined but your log pattern contains the %t placeholder, the output will display 0 for the thread ID rather than the actual system thread identifier.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}