https://github.com/kdab/kdspdsetup
A small library in modern C++ to initialize spdlog loggers from a toml configuration file.
https://github.com/kdab/kdspdsetup
cmake config cpp cpp20 library spdlog toml-config
Last synced: 7 months ago
JSON representation
A small library in modern C++ to initialize spdlog loggers from a toml configuration file.
- Host: GitHub
- URL: https://github.com/kdab/kdspdsetup
- Owner: KDAB
- Created: 2024-02-07T15:41:55.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-05T14:04:59.000Z (11 months ago)
- Last Synced: 2025-08-20T23:41:42.006Z (7 months ago)
- Topics: cmake, config, cpp, cpp20, library, spdlog, toml-config
- Language: C++
- Homepage: https://docs.kdab.com/kdspdsetup/unstable/
- Size: 193 KB
- Stars: 16
- Watchers: 35
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSES/MIT.txt
Awesome Lists containing this project
README
# KDSPDSetup
## Overview
KDSPDSetup is a minimal reimplementation of the unmaintained [spdlog_setup](https://github.com/guangie88/spdlog_setup) library for modern C++ projects.
Complete documentation is available [here](https://kdab.github.io/KDSPDSetup).
Given a TOML file containing configuration parameters, `spdlog` loggers for your project can be set up with a single call to `KDSPDSetup::setupFrom`, as shown below:
```cpp
#include
int main()
{
KDSPDSetup::setupFrom("example.toml");
auto logger = spdlog::get("root");
logger->debug("Hello spdlog!");
}
// [2023-10-30 14:35:19.244] [root] [debug] Hello spdlog!
```
The configuration file for this example, `example.toml`, might look like this:
```c
[[sink]]
name = "console_st"
type = "stdout_sink_st"
[[logger]]
name = "root"
sinks = ["console_st"]
level = "debug"
```
## Requirements
You will need a compiler that supports the C++20 standard.
Our CI has successfully built and tested on these environments:
|Platform|Kernel|Arch|Compiler|Compiler Version
|-|-|-|-|-
| Windows 10 | Microsoft Windows [Version 10.0.19044.1526] | x64 | MSVC | 19.34.31937.0
| Ubuntu GNU/Linux | 4.15.0-167-generic #175-Ubuntu SMP | x64 | GCC | 11.4.0
| MacOS | Darwin Kernel Version 22.6.0 xnu-8796.141.3.701.17 | arm64 | clang | 14.0.3.14030022
The following compiler versions should be sufficient, but this has not been fully tested:
|  |  |  |  | 
|-|-|-|-|-
| GCC 10+ | Clang 8+ | MSVC 19.22+ | NVCC 12.0+ | Intel C++ 2021.1+
If any [dependencies](#dependencies) are not found, CMake's FetchContent will use [`git`](https://git-scm.com/) to retrieve them. Thus, `git` is also a requirement in this case.
## Dependencies
Aside from [spdlog](https://github.com/gabime/spdlog), there are three additional dependencies:
| Purpose | Lib | Needed
| ------------- | --------------------------------------------- | ----------
| TOML parsing | [toml11](https://github.com/ToruNiina/toml11) | Always
| Testing | [doctest](https://github.com/doctest/doctest) | Tests only
| Documentation | [doxygen](https://github.com/doxygen/doxygen) | Documentation only
These dependencies will be automatically downloaded with `git` if not found.
## Build & Install
### Build
You'll need at least CMake 3.11 to build this library.
You can skip to the [CMake Presets](#cmake-presets) section if you'd like to use a preset that will set the source and build directories for you, along with some flags.
To configure and build, use the following `cmake` commands:
```bash
$ cmake -S -B
$ cmake --build
```
where `` is the root directory of this project and `` is the desired build directory.
`` can be empty or contain one or more of the flags detailed in the [Tests](#tests), [Examples](#examples), and [Documentation](#documentation) sections below.
For example, from this directory one might run the following:
```bash
$ cmake -S . -B build
$ cmake --build build
```
which creates the directory `build` if it does not exist, configures CMake, and builds the project.
### CMake Presets
There are a number of CMake presets included. These will configure a build with specific flags set for either development or release.
`dev-*` configurations will add tests and documentation to the build targets. They also build in CMake's `Debug` mode, which will enable debug symbols and will NOT use compiler optimization flags.
`release-*` configurations will not build tests or documentation. They build in CMake's `Release` mode, which will use compiler optimization and will NOT build with debug symbols.
Examples will be built with both types of preset unless explicitly disabled with [`-DKDSPDSETUP_BUILD_EXAMPLES=OFF`](#examples).
Here are all the presets:
- `dev-gcc`
- `dev-clang`
- `dev-msvc`
- `release-gcc`
- `release-clang`
- `release-msvc`
To build from this directory with a preset (we'll use `dev-gcc` as an example), one would run the following:
```bash
$ cmake --preset dev-gcc
$ cmake --build build-dev-gcc
```
Note that for preset name `presetName` the build directory will be titled `build-presetName`.
### Install
To install the library on your system, after completing the steps in the [Build](#build) section above, run the following command:
```bash
$ sudo cmake --install
```
### Tests
You can build the unit tests by passing the flag `-DKDSPDSETUP_BUILD_TESTS=ON` to CMake:
```bash
$ cmake -S -B -DKDSPDSETUP_BUILD_TESTS
$ cmake --build
```
The dependency [doctest](https://github.com/doctest/doctest) will only be used when this flag is on.
### Examples
Building examples is on by default.
To disable the basic examples, pass the flag `-DKDSPDSETUP_BUILD_EXAMPLES=OFF` to CMake:
```bash
$ cmake -S -B -DKDSPDSETUP_BUILD_EXAMPLES=OFF
$ cmake --build
```
### Documentation
The documentation for this project [is available online](https://kdab.github.io/KDSPDSetup).
To build the documentation locally, pass the flag `-DKDSPDSETUP_BUILD_DOCS=ON` to CMake.
```bash
$ cmake -S -B -DKDSPDSETUP_BUILD_DOCS
$ cmake --build
```
The dependency [doxygen](https://github.com/doxygen/doxygen) will only be used when this flag is on.
## Usage
### Use With CMake Project
To use the library in a CMake project, make sure to [install](#install) the library.
Then, simply write the following line in your `CMakeLists.txt`:
```cmake
find_package(KDSpdSetup)
```
and after adding your target, let's call it `untitled`, link with this CMake command:
```cmake
target_link_libraries(untitled KDSpdSetup::KDSpdSetup)
```
### Configuration
Writing configuration files that can be used by KDSPDSetup is simple.
#### Sinks
To configure a sink, a name and sink type must be provided:
```c
[[sink]]
name = "some_name"
type = "stdout_sink_st"
```
Optionally, a level can also be specified:
```c
[[sink]]
name = "stdout_error"
type = "stdout_sink_mt"
level = "err"
```
Some sink types require additional fields, or allow additional optional fields.
The list below details the sink types which have additional required fields:
|`type`|required field|value type
|-|-|-
|`basic_file_sink_st`
`basic_file_sink_mt` |`filename`|`string`
|`rotating_file_sink_st`
`rotating_file_sink_mt`|`base_filename`
`max_size`
`max_files`|`string`
`string`
`int`
|`daily_file_sink_st`
`daily_file_sink_mt`|`base_filename`
`rotation_hour`
`rotation_minute`|`string`
`int`
`int`
All of the above sink types can also optionally specify the boolean `truncate`, which defaults to `false` if not specified.
The syslog sink types, `syslog_sink_st` and `syslog_sink_mt`, have four optional fields that generally do not need to be filled (but can be if needed):
|key name|value type|default value
|-|-|-
|`ident`|`string`|`""`
|`syslog_option`|`int`|`0`
|`syslog_facility`|`int`|`1`
Note that a `syslog_facility` value of `1` is the plain integer value for `LOG_USER`.
Here is a full list of currently supported sink types and the platforms on which they are available:
|Sink Type|Platform(s)
|-|-
|`stdout_sink_st`|
|`stdout_sink_mt`|
|`color_stdout_sink_st`|
|`color_stdout_sink_mt`|
|`basic_file_sink_st`|
|`basic_file_sink_mt`|
|`rotating_file_sink_st`|
|`rotating_file_sink_mt`|
|`daily_file_sink_st`|
|`daily_file_sink_mt`|
|`null_sink_st`|
|`null_sink_mt`|
|`syslog_sink_st`|
|`syslog_sink_mt`|
|`msvc_sink_st`|
|`msvc_sink_mt`|
Please note that the suffix `_st` refers to single thread, and `_mt` to multiple threads.
#### Patterns
The global pattern is defined as a free-standing key-value pair (not under a `[[pattern]]` or any other table):
```c
global_pattern = "[%Y-%m-%dT%T%z] [%L] <%n>: %v"
```
If `global_pattern` is not specified, the spdlog uses the default pattern `“[%Y-%m-%d %H:%M:%S. %e] [%l] [%n] %v”`.
Additionally, named patterns can be defined and reused with several different loggers:
```c
[[pattern]]
name = "short_pattern"
value = "%c-%L: %v"
```
#### Thread Pools
An async logger takes a thread pool as an argument to its constructor. This can be either a global thread pool, or a manually constructed one.
The global thread pool is defined as a table with single brackets (`[global_thread_pool]`, **not** `[[global_thread_pool]]`) because it is one table, not an array of tables. Named thread pools are members of the array of tables `[[threadpool]]`.
Both require integers `queue_size` and `num_threads`, while non-global thread pools also require a name.
```c
[global_thread_pool]
queue_size = 8192
num_threads = 1
[[thread_pool]]
name = "tp"
queue_size = 4096
num_threads = 2
```
#### Loggers
Loggers require a name, and a list of sink names:
```c
[[logger]]
name = "my_logger"
sinks = ["console_sink_st", "console_sink_mt", "file_out", "file_err"]
```
Please keep in mind that each sink name must be a `name` from a `[[sink]]` defined somewhere in the configuration file. If the name is not found, `std::out_of_range` will be thrown.
Loggers can also optionally specify patterns and levels:
```c
[[logger]]
name = "root"
sinks = [
"console_st", "console_mt",
"color_console_st", "color_console_mt",
"daily_out", "daily_err",
"file_out", "file_err",
"rotate_out", "rotate_err",
"null_sink_st", "null_sink_mt",
"syslog_st", "syslog_mt"]
level = "trace"
pattern = "short_pattern"
```
The pattern name also must be defined somewhere in the configuration.
Asynchronous loggers can be defined by specifying `type = "async"`:
```c
[[logger]]
type = "async"
name = "my_async"
sinks = ["console_mt"]
```
Optionally, async loggers can have a specified thread pool and overflow policy:
```c
[[logger]]
type = "async"
name = "local_async"
sinks = ["console_mt"]
pattern = "succient"
thread_pool = "tp"
overflow_policy = "overrun_oldest"
```
If no thread pool is specified, the global thread pool is used.
The options for overflow policy are `"block"` and `"overrun_oldest"`. If not specified, `"block"` is used by default.
#### Example Files
This repository contains a few example configuration files:
- `examples/example.toml`
- `tests/full/full-linux.toml`
- `tests/full/full-linux.toml`
- `tests/pre/pre.toml`
Huge thanks to [guangie88](https://github.com/guangie88) for providing these examples in the original [spdlog_setup](https://github.com/guangie88/spdlog_setup) project. The files in that project are available under the terms of the [MIT](https://github.com/guangie88/spdlog_setup/blob/master/LICENSE) license.
## Licensing
KDSPDSetup is (C) 2023, Klarälvdalens Datakonsult AB, and is available under the terms of the [MIT](LICENSES/MIT.txt) license.
Contact KDAB at if you need different licensing options.
## About KDAB
KDSPDSetup is supported and maintained by Klarälvdalens Datakonsult AB (KDAB).
The KDAB Group is the global No.1 software consultancy for Qt, C++ and OpenGL applications across desktop, embedded and mobile platforms.
The KDAB Group provides consulting and mentoring for developing Qt applications from scratch and in porting from all popular and legacy frameworks to Qt. We continue to help develop parts of Qt and are one of the major contributors to the Qt Project. We can give advanced or standard trainings anywhere around the globe on Qt as well as C++, OpenGL, 3D and more.
Please visit to meet the people who write code like this.
Stay up-to-date with KDAB product announcements:
- [KDAB Newsletter](https://news.kdab.com)
- [KDAB Blogs](https://www.kdab.com/category/blogs)
- [KDAB on Twitter](https://twitter.com/KDABQt)