diff --git a/.travis.yml b/.travis.yml index 7652f523..cc5571a4 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,13 +7,13 @@ addons: sources: - ubuntu-toolchain-r-test packages: - - gcc-6 - - g++-6 + - gcc-5 + - g++-5 - cmake3 - doxygen script: -- export CC=/usr/bin/gcc-6 CXX=/usr/bin/g++-6 +- export CC=/usr/bin/gcc-5 CXX=/usr/bin/g++-5 - git submodule update --init --recursive - mkdir build-debug - cd build-debug diff --git a/README.md b/README.md index a4f475fd..ab5418ee 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,20 @@ # `spdlog_setup` ## Overview -spdlog file configuration setup for convenience in initializing spdlog. Requires at least `CMake 3.3` + `GCC 6.0` for Linux, or `MSVC2015` with `MSBuild` for Windows to support c++14 features. Not suitable for serious production use. +[`spdlog`](https://github.com/gabime/spdlog) file configuration setup for convenience in initializing spdlog. Inspired by [`spdlog-config`](https://github.com/objectx/spdlog-config) for using [`TOML`](https://github.com/toml-lang/toml) configuration, a format that is simple and easy-to-read. Also heavily influenced by [`Rust`](https://www.rust-lang.org) language, leaning towards monadic return type style instead of throwing exceptions. Not battle-tested for production use yet. [![Build Status](https://travis-ci.org/guangie88/spdlog_setup.svg?branch=master)](https://travis-ci.org/guangie88/spdlog_setup) [![Build status](https://ci.appveyor.com/api/projects/status/srek5xih80104eds/branch/master?svg=true)](https://ci.appveyor.com/project/guangie88/spdlog-setup/branch/master) [![codecov](https://codecov.io/gh/guangie88/spdlog_setup/branch/master/graph/badge.svg)](https://codecov.io/gh/guangie88/spdlog_setup) +## Requirements +Requires at least `CMake 3.3`, `GCC 5.0` for Linux, or `MSVC2015` with `MSBuild` for Windows to support C++14 features. + +## Features +- Initialization of `spdlog` sinks and loggers based on `TOML` configuration file. +- Tag replacement (e.g. "{tagname}-log.txt") within the `TOML` configuration file. +- Does not throw exception (unless `std::string` constructor throws `bad_alloc` for now). + ## Repository Checkout Since this repository has other git-based dependencies as `git` submodules, use the command: `git clone --recursive https://github.com/guangie88/spdlog_setup.git` @@ -32,77 +40,21 @@ This guide prefers a `CMake` out-of-source build style. In the root directory after `git` cloning: - `mkdir build` - `cd build` -- `cmake ..` -- `make` +- (Debug) `cmake .. -DCMAKE_BUILD_TYPE=Debug` / (Release) `cmake .. -DCMAKE_BUILD_TYPE=Release` +- `cmake --build .` Now the unit test executable should be compiled and residing in `build/bin/unit_test`. ### Windows (`MSVC2015`) -Ensure that `MSBuild` can be located in `PATH`. +Ensure that [`Microsoft Build Tools 2015`](https://www.microsoft.com/en-sg/download/details.aspx?id=48159) and [`Visual C++ Build Tools 2015`](http://landinghub.visualstudio.com/visual-cpp-build-tools) (or `Visual Studio 2015`) have been installed. In the root directory after `git` cloning: - `mkdir build` - `cd build` - `cmake .. -G "Visual Studio 14 Win64"` -- `msbuild /p:Configuration=Debug spdlog_setup.sln` - -Now the unit test executable should be compiled and residing in `build/bin/Debug/unit_test.exe`. - -## Use Example - -### Static Configuration File - -```c++ -#include "spdlog_setup.h" - -#include - -int main() { - const auto res = ::spdlog_setup::from_file("log_conf.toml"); - - res.match_err([](const std::string &err_msg) { - // error parsing the TOML config file - // as the library follows a error code mechanism approach - // you may choose to throw an exception with err_msg if preferred - }); - - return 0; -} -``` - -### Tagged Based Configuration File - -```c++ -#include "spdlog_setup.h" - -#include -#include - -int main(const int argc, const char * argv[]) { - // assumes both index and path are given by command line arguments +- (Debug) `cmake --build . -- -p:Configuration=Debug spdlog_setup.sln` / (Release) `cmake --build . -- -p:Configuration=Release spdlog_setup.sln` - // gets index integer, e.g. 123 - const auto index = std::stoi(argv[1]); - - // gets path string, e.g. a/b/c - const auto path = std::string(argv[2]); - - // performs parsing with dynamic tag value replacements - // tags are anything content that contains {xxx}, where xxx is the name of the tag - // to be replaced - const auto res = ::spdlog_setup::from_file_with_tag_replacement("log_conf.pre.toml", - // replaces {index} with actual value in current variable index - std::make_pair("index", index), - // replaces {path} with actual value in current variable path - std::make_pair("path", path)); - - res.match_err([](const std::string &err_msg) { - // error actions - }); - - return 0; -} -``` +Now the unit test executable should be compiled and residing in `build/bin/Debug/unit_test.exe` / `build/bin/Release/unit_test.exe`. ## Currently Supported Sinks - `stdout_sink_st` @@ -205,6 +157,101 @@ sinks = ["console", "rotate_out", "simple_err"] level = "trace" ``` +## Use Example + +### Static Configuration File + +```c++ +#include "spdlog_setup.h" + +#include +#include + +int main() { + // generally no exception will be thrown unless std::bad_alloc due to std::string + const auto res = spdlog_setup::from_file("log_conf.toml"); + + // if-else syntax, has advantage of being able to perform early return out of main + if (res.is_err()) { + std::cerr << res.get_err_unchecked() << '\n'; + return 127; + } + + // (alternative) Rust-like match (error) syntax + // able to type check for error safely but unable to perform early return out of main + res.match_err([](const std::string &err_msg) { + // error parsing the TOML config file + // you may choose to throw an exception with err_msg if preferred + }); + + // assumes that root logger has been initialized + auto logger = spdlog::get("root"); + logger->trace("trace message"); + logger->debug("debug message"); + logger->info("info message"); + logger->warn("warn message"); + logger->error("error message"); + logger->critical("critical message"); + + return 0; +} +``` + +### Tagged Based Configuration File + +```c++ +#include "spdlog_setup.h" + +#include +#include + +int main(const int argc, const char * argv[]) { + // assumes both index and path are given by command line arguments + + // gets index integer, e.g. 123 + const auto index = std::stoi(argv[1]); + + // gets path string, e.g. a/b/c + const auto path = std::string(argv[2]); + + // performs parsing with dynamic tag value replacements + // tags are anything content that contains {xxx}, where xxx is the name of the tag + // to be replaced + const auto res = spdlog_setup::from_file_with_tag_replacement("log_conf.pre.toml", + // replaces {index} with actual value in current variable index + std::make_pair("index", index), + // replaces {path} with actual value in current variable path + std::make_pair("path", path)); + + // Rust-like match expression syntax + // able to type check for success and error safely + // but unable to perform early return because of closure usage + const auto value = res.match([](auto) { + // success case + // assumes that root logger has been initialized + auto logger = spdlog::get("root"); + + // ... + return 0; + + }, [](const std::string &err_msg) { + // error case + // return value type must be similar to the success case + return 127; + }); + + // (alternative) if-else syntax + if (res.is_ok()) { + // success case + // ... + + return 0; + } else { + return 127; + } +} +``` + ## Notes -- Make sure that the directory for the log files to reside in exists before using `spdlog`. +- Make sure that the directory for the log files to reside in exists before using `spdlog`, unless the `create_parent_dir` flag is set to true for the sink. - For the current set of unit tests, the working directory must be at the git root directory so that the `config` and `log` directories can be found. diff --git a/deps/Catch b/deps/Catch index 2ce6c74f..9c07718b 160000 --- a/deps/Catch +++ b/deps/Catch @@ -1 +1 @@ -Subproject commit 2ce6c74f8fcbd28c977e70d8c020939123a9ea3c +Subproject commit 9c07718b5f779bc1405f98ca6b5b693026f6eac7 diff --git a/deps/cpptoml b/deps/cpptoml index a82e9561..2051836a 160000 --- a/deps/cpptoml +++ b/deps/cpptoml @@ -1 +1 @@ -Subproject commit a82e9561e409bd0e6710f7b4f9ff892631b5953b +Subproject commit 2051836a96a25e5a2d5283be7f633a157848f15e diff --git a/deps/fmt b/deps/fmt index 39834389..2a619d96 160000 --- a/deps/fmt +++ b/deps/fmt @@ -1 +1 @@ -Subproject commit 398343897f98b88ade80bbebdcbe82a36c65a980 +Subproject commit 2a619d96dd5d8bf940e20ae60b4cf2a5106c7365 diff --git a/deps/rustfp b/deps/rustfp index 4cf46fb3..ba9b8ed4 160000 --- a/deps/rustfp +++ b/deps/rustfp @@ -1 +1 @@ -Subproject commit 4cf46fb325f60db7a71c37e64d77040eea761184 +Subproject commit ba9b8ed427366379857821e85d4b374c71225ffd diff --git a/deps/spdlog b/deps/spdlog index 5ed42698..3a21b765 160000 --- a/deps/spdlog +++ b/deps/spdlog @@ -1 +1 @@ -Subproject commit 5ed426980b366400d4854d28eac27d153bd7fbd4 +Subproject commit 3a21b765cb2c3c6764a33e4b29191c2b04b148b4