{"id":25827052,"url":"https://github.com/guangie88/spdlog_setup","last_synced_at":"2025-02-28T15:52:21.420Z","repository":{"id":48860756,"uuid":"100186525","full_name":"guangie88/spdlog_setup","owner":"guangie88","description":"spdlog setup initialization via file configuration for convenience.","archived":false,"fork":false,"pushed_at":"2021-07-08T08:26:28.000Z","size":325,"stargazers_count":74,"open_issues_count":27,"forks_count":32,"subscribers_count":9,"default_branch":"master","last_synced_at":"2023-03-11T16:08:16.260Z","etag":null,"topics":["config","configuration","cpp","init","initialize","log","logger","logging","setup","spdlog"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guangie88.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-13T15:35:46.000Z","updated_at":"2022-10-18T22:23:16.000Z","dependencies_parsed_at":"2022-08-31T22:10:17.590Z","dependency_job_id":null,"html_url":"https://github.com/guangie88/spdlog_setup","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guangie88%2Fspdlog_setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guangie88%2Fspdlog_setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guangie88%2Fspdlog_setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guangie88%2Fspdlog_setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guangie88","download_url":"https://codeload.github.com/guangie88/spdlog_setup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241176625,"owners_count":19922732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["config","configuration","cpp","init","initialize","log","logger","logging","setup","spdlog"],"created_at":"2025-02-28T15:52:20.830Z","updated_at":"2025-02-28T15:52:21.393Z","avatar_url":"https://github.com/guangie88.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `spdlog_setup` (spdlog setup)\n\n## Overview\n\nHeader-only [`spdlog`](https://github.com/gabime/spdlog) file-based setup\nlibrary for convenience in initializing spdlog. Inspired by\n[`spdlog-config`](https://github.com/objectx/spdlog-config) for using\n[`TOML`](https://github.com/toml-lang/toml) configuration, a format that is\nsimple and easy-to-read.\n\n[![Build Status](https://travis-ci.org/guangie88/spdlog_setup.svg?branch=master)](https://travis-ci.org/guangie88/spdlog_setup)\n[![Build status](https://ci.appveyor.com/api/projects/status/srek5xih80104eds/branch/master?svg=true)](https://ci.appveyor.com/project/guangie88/spdlog-setup/branch/master)\n[![codecov](https://codecov.io/gh/guangie88/spdlog_setup/branch/master/graph/badge.svg)](https://codecov.io/gh/guangie88/spdlog_setup)\n\n## Requirements\n\nRequires at least `CMake 3.3`, `g++-4.9` for Linux, or `MSVC2015` with `MSBuild`\nfor Windows, providing sufficient C++11 features.\n\n`g++-4.8` will notably fail because of the missing `std::regex` implementation.\n`MSVC2013` will fail too as it does not accept `noexcept`, which is used in some\nof the functions.\n\nTested against:\n\n- `g++-4.9`\n- `g++-5`\n- `g++-6`\n- `g++-7`\n- `g++-8`\n- `clang-3.6`\n- `clang-3.7`\n- `clang-3.8`\n- `clang-3.9`\n- `clang-4.0`\n- `clang-5.0`\n- `clang-6.0`\n- `clang-7`\n- `cl` (v140 / MSVC2015)\n- `cl` (v141 / MSVC2017)\n\n## Features\n\n- Header-only (check [`How to Install`](#how-to-install) to extract out the\n  header files).\n- Initialization of `spdlog` sinks, patterns and loggers based on `TOML`\n  configuration file.\n- Tag replacement (e.g. \"{tagname}-log.txt\") within the `TOML` configuration\n  file.\n- Throw exception describing the error during the parsing of the config file.\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for more details.\n\n## Repository Checkout\n\nSince this repository has other git-based dependencies as `git` submodules, use\nthe command:\n`git clone --recursive https://github.com/guangie88/spdlog_setup.git` in order\nto clone all the submodule dependencies.\n\nIf the repository has already been cloned without the submodules, then instead\nrun: `git submodule update --init --recursive` in order to clone all the\nsubmodule dependencies.\n\n## Dependencies\n\nThis repository uses the following external dependencies directly:\n\n- [`Catch`](https://github.com/philsquared/Catch) (only for unit-tests, not\n  included in installation)\n- [`spdlog`](https://github.com/gabime/spdlog)\n\nIn addition, the following dependencies are inlined as part of the include:\n\n- [`cpptoml`](https://github.com/skystrife/cpptoml)\n- [`fmt`](https://github.com/fmtlib/fmt.git)\n\n## How to Build\n\nThis guide prefers a `CMake` out-of-source build style. For build with unit\ntests, add `-DSPDLOG_SETUP_INCLUDE_UNIT_TESTS=ON` during the CMake\nconfiguration.\n\n## How to Install\n\nIf a recent enough `spdlog` is already available, and unit tests are not to be\nrun, it is possible to just copy the `spdlog_setup` directory within `include`\ninto another solution for header-only include, as long as `spdlog` can be found\nin that solution.\n\nIf `spdlog` is not available, the installation step of `CMake` can copy out the\nentire list of header files required for `spdlog_setup` into the installation\ndirectory, including `spdlog`. To change the installation directory, add\n`-DCMAKE_INSTALL_PREFIX=\u003cpath-to-install\u003e` during the CMake configuration.\n\n### Linux (`GCC`)\n\nIn the root directory after `git` cloning:\n\n#### Debug without Installation\n\n- `mkdir build-debug`\n- `cd build-debug`\n- `cmake .. -DCMAKE_BUILD_TYPE=Debug -DSPDLOG_SETUP_INCLUDE_UNIT_TESTS=ON`\n- `cmake --build .`\n\nNow the unit test executable should be compiled and residing in\n`build-debug/spdlog_setup_unit_test`.\n\n#### Release with Installation\n\n- `mkdir build-release`\n- `cd build-release`\n- `cmake .. -DCMAKE_BUILD_TYPE=Release -DSPDLOG_SETUP_INCLUDE_UNIT_TESTS=ON -DCMAKE_INSTALL_PREFIX=install`\n- `cmake --build . --target install`\n\nNow the unit test executable should be compiled and residing in\n`build-release/spdlog_setup_unit_test`.\n\nThe header files should be installed in `build-release/install/include`.\n\n### Windows (`MSVC2015` as Example)\n\nEnsure that [`Microsoft Build Tools 2015`](https://www.microsoft.com/en-sg/download/details.aspx?id=48159)\nand [`Visual C++ Build Tools 2015`](http://landinghub.visualstudio.com/visual-cpp-build-tools)\n(or `Visual Studio 2015`) have been installed.\n\nIn the root directory after `git` cloning:\n\n- `mkdir build`\n- `cd build`\n- `cmake .. -G \"Visual Studio 14 Win64\" -DSPDLOG_SETUP_INCLUDE_UNIT_TESTS=ON -DCMAKE_INSTALL_PREFIX=install`\n- (Debug) `cmake --build . --config Debug`\n- (Release with installation) `cmake --build . --config Release --target install`\n\nNow the unit test executable should be compiled and residing in\n\n- (Debug) `build/Debug/spdlog_setup_unit_test.exe` or\n- (Release) `build/Release/spdlog_setup_unit_test.exe`.\n\nThe header files should be installed in `build/install/include`.\n\n## Supported Sinks\n\n- `stdout_sink_st`\n- `stdout_sink_mt`\n- `stderr_sink_st`\n- `stderr_sink_mt`\n- `color_stdout_sink_st`\n- `color_stdout_sink_mt`\n- `color_stderr_sink_st`\n- `color_stderr_sink_mt`\n- `basic_file_sink_st`\n- `basic_file_sink_mt`\n- `rotating_file_sink_st`\n- `rotating_file_sink_mt`\n- `daily_file_sink_st`\n- `daily_file_sink_mt`\n- `null_sink_st`\n- `null_sink_mt`\n- `syslog_sink` (only for Linux, `SPDLOG_ENABLE_SYSLOG` preprocessor definition\n  must be defined before any `spdlog`/`spdlog_setup` header is included)\n\nCurrently `ostream_sink` and `dist_sink` do not fit into the use case and are\nnot supported.\n\nFor more information about how the above sinks work in `spdlog`, please refer to\nthe original `spdlog` sinks wiki page at:\n\u003chttps://github.com/gabime/spdlog/wiki/4.-Sinks\u003e.\n\n## TOML Configuration Example\n\n### Static File Configuration\n\n```toml\n# level is optional for both sinks and loggers\n# level for error logging is 'err', not 'error'\n# _st =\u003e single threaded, _mt =\u003e multi threaded\n# syslog_sink is automatically thread-safe by default, no need for _mt suffix\n\n# max_size supports suffix\n# - T (terabyte)\n# - G (gigabyte)\n# - M (megabyte)\n# - K (kilobyte)\n# - or simply no suffix (byte)\n\n# check out https: // github.com/gabime/spdlog/wiki/3.-Custom-formatting\nglobal_pattern = \"[%Y-%m-%dT%T%z] [%L] \u003c%n\u003e: %v\"\n\n[[sink]]\nname = \"console_st\"\ntype = \"stdout_sink_st\"\n\n[[sink]]\nname = \"console_mt\"\ntype = \"stdout_sink_mt\"\n\n[[sink]]\nname = \"color_console_st\"\ntype = \"color_stdout_sink_st\"\n\n[[sink]]\nname = \"color_console_mt\"\ntype = \"color_stdout_sink_mt\"\n\n[[sink]]\nname = \"file_out\"\ntype = \"basic_file_sink_st\"\nfilename = \"log/spdlog_setup.log\"\n# truncate field is optional\n# truncate = false (default)\nlevel = \"info\"\n# optional flag to indicate the set - up to create the log dir first\ncreate_parent_dir = true\n\n[[sink]]\nname = \"file_err\"\ntype = \"basic_file_sink_mt\"\nfilename = \"log/spdlog_setup_err.log\"\ntruncate = true\nlevel = \"err\"\n# to show that create_parent_dir is indeed optional(defaults to false)\n\n[[sink]]\nname = \"rotate_out\"\ntype = \"rotating_file_sink_st\"\nbase_filename = \"log/rotate_spdlog_setup.log\"\nmax_size = \"1M\"\nmax_files = 10\nlevel = \"info\"\n\n[[sink]]\nname = \"rotate_err\"\ntype = \"rotating_file_sink_mt\"\nbase_filename = \"log/rotate_spdlog_setup_err.log\"\nmax_size = \"1M\"\nmax_files = 10\nlevel = \"err\"\n\n[[sink]]\nname = \"daily_out\"\ntype = \"daily_file_sink_st\"\nbase_filename = \"log/daily_spdlog_setup.log\"\nrotation_hour = 17\nrotation_minute = 30\nlevel = \"info\"\n\n[[sink]]\nname = \"daily_err\"\ntype = \"daily_file_sink_mt\"\nbase_filename = \"log/daily_spdlog_setup_err.log\"\nrotation_hour = 17\nrotation_minute = 30\nlevel = \"err\"\n\n[[sink]]\nname = \"null_sink_st\"\ntype = \"null_sink_st\"\n\n[[sink]]\nname = \"null_sink_mt\"\ntype = \"null_sink_mt\"\n\n# only works for Linux\n[[sink]]\nname = \"syslog_st\"\ntype = \"syslog_sink_st\"\n# generally no need to fill up the optional fields below\n# ident = \"\" (default)\n# syslog_option = 0 (default)\n# syslog_facility = LOG_USER (default macro value)\n\n# only works for Linux\n[[sink]]\nname = \"syslog_mt\"\ntype = \"syslog_sink_mt\"\n# generally no need to fill up the optional fields below\n# ident = \"\" (default)\n# syslog_option = 0 (default)\n# syslog_facility = LOG_USER (default macro value)\n\n# only works for Windows\n[[sink]]\nname = \"msvc_st\"\ntype = \"msvc_sink_st\"\n\n# only works for Windows\n[[sink]]\nname = \"msvc_mt\"\ntype = \"msvc_sink_mt\"\n\n[[pattern]]\nname = \"succient\"\nvalue = \"%c-%L: %v\"\n\n[[logger]]\nname = \"root\"\nsinks = [\n    \"console_st\", \"console_mt\",\n    \"color_console_st\", \"color_console_mt\",\n    \"daily_out\", \"daily_err\",\n    \"file_out\", \"file_err\",\n    \"rotate_out\", \"rotate_err\",\n    \"null_sink_st\", \"null_sink_mt\",\n    \"syslog_st\", \"syslog_mt\"]\nlevel = \"trace\"\n\n[[logger]]\nname = \"windows_only\"\nsinks = [\"msvc_st\", \"msvc_mt\"]\n\n[[logger]]\nname = \"console\"\nsinks = [\"console_st\", \"console_mt\"]\npattern = \"succient\"\n\n# Async\n\n[global_thread_pool]\nqueue_size = 8192\nnum_threads = 1\n\n[[thread_pool]]\nname = \"tp\"\nqueue_size = 4096\nnum_threads = 2\n\n[[logger]]\ntype = \"async\"\nname = \"global_async\"\nsinks = [\"console_mt\"]\npattern = \"succient\"\n\n[[logger]]\ntype = \"async\"\nname = \"local_async\"\nsinks = [\"console_mt\"]\npattern = \"succient\"\nthread_pool = \"tp\"\noverflow_policy = \"overrun_oldest\"  # block (default) | overrun_oldest\n```\n\n### Tagged-Base Pre-TOML File Configuration\n\n```toml\n# level is optional for both sinks and loggers\n# level for error logging is 'err', not 'error'\n\n# max_size supports suffix\n# - T (terabyte)\n# - G (gigabyte)\n# - M (megabyte)\n# - K (kilobyte)\n# - or simply no suffix (byte)\n\n[[sink]]\nname = \"console\"\ntype = \"stdout_sink_mt\"\n\n[[sink]]\nname = \"rotate_out\"\ntype = \"rotating_file_sink_mt\"\nbase_filename = \"log/{index}-info/simple-{path}.log\"\nmax_size = \"1M\"\nmax_files = 10\nlevel = \"info\"\n# optional flag to indicate the set - up to create the log dir first\ncreate_parent_dir = true\n\n[[sink]]\nname = \"simple_err\"\ntype = \"basic_file_sink_mt\"\nfilename = \"log/{index}-err/simple-{path}.log\"\ntruncate = false\nlevel = \"err\"\n# optional flag to indicate the set - up to create the log dir first\ncreate_parent_dir = true\n\n[[logger]]\nname = \"root\"\nsinks = [\"console\", \"rotate_out\", \"simple_err\"]\nlevel = \"trace\"\n```\n\n## Use Examples\n\n### Static Configuration File\n\n```c++\n#include \"spdlog_setup/conf.h\"\n\n#include \u003ciostream\u003e\n#include \u003cstring\u003e\n\nint main() {\n    try {\n        // spdlog_setup::setup_error thrown if file not found\n        spdlog_setup::from_file(\"log_conf.toml\");\n\n        // assumes that root logger has been initialized\n        auto logger = spdlog::get(\"root\");\n        logger-\u003etrace(\"trace message\");\n        logger-\u003edebug(\"debug message\");\n        logger-\u003einfo(\"info message\");\n        logger-\u003ewarn(\"warn message\");\n        logger-\u003eerror(\"error message\");\n        logger-\u003ecritical(\"critical message\");\n\n        // ...\n    } catch (const spdlog_setup::setup_error \u0026) {\n        // ...\n    } catch (const std::exception \u0026) {\n        // ...\n    }\n}\n```\n\n### Tagged Based Configuration File\n\n```c++\n#include \"spdlog_setup/conf.h\"\n\n#include \u003cstring\u003e\n\nint main(const int argc, const char * argv[]) {\n    // assumes both index and path are given by command line arguments\n\n    try {\n        // gets index integer, e.g. 123\n        const auto index = std::stoi(argv[1]);\n\n        // gets path string, e.g. a/b/c\n        const auto path = std::string(argv[2]);\n\n        // performs parsing with dynamic tag value replacements\n        // tags are anything content that contains {xxx}, where xxx is the name\n        // of the tag to be replaced\n        spdlog_setup::from_file_with_tag_replacement(\n            \"log_conf.pre.toml\",\n            // replaces {index} with actual value in current variable index via\n            // fmt mechanism\n            fmt::arg(\"index\", index),\n            // replaces {path} with actual value in current variable path\n            fmt::arg(\"path\", path));\n\n        auto logger = spdlog::get(\"root\");\n        // ...\n    } catch (const spdlog_setup::setup_error \u0026) {\n        // ...\n    } catch (const std::exception \u0026) {\n        // ...\n    }\n}\n```\n\n## Notes\n\n- Make sure that the directory for the log files to reside in exists before\n  using `spdlog`, unless the `create_parent_dir` flag is set to true for the\n  sink.\n- For the current set of unit tests, the working directory must be at the git\n  root directory or in `build` directory so that the TOML configuration files in\n  `config` directory can be found.\n\n## Contributions\n\nPull requests are welcome!\n\nTo make the code formatting more objective, `clang-format` is used to format\nall the source code files.\n\nPlease try to run\n\n```bash\n./run-clang-format.sh\n```\n\nwhich will pull the appropriate Docker image to run the formatting command over\nthe entire repository directory.\n\nIf your `docker` command requires `sudo`, then you will need to run it as\n\n```bash\nsudo sh ./run-clang-format.sh\n```\n\nAlternatively, you could also try to set up your own `clang-format` (currently\nthis repository uses version 7), and run\n\n```bash\nclang-format -i path_to_h_cpp_file\n```\n\nover the changed files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguangie88%2Fspdlog_setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguangie88%2Fspdlog_setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguangie88%2Fspdlog_setup/lists"}