Setting Up - filipdutescu/small-better-logger GitHub Wiki

Including in Your Projects

All you need to do if you wish to use SBLogger (in a C++ project) is to clone/fork the repo or download the SmallBetterLogger.hpp file to your project and add it as a header file in your code:

...
#include "SmallBetterLogger.hpp"
...

Using Older C++ Standards

The SBLogger library makes use of the predefined __cplusplus macro, which provides the compiler version, to auto-detect which code needs to change in order for it to be used in the project it is included in.

If you are using a pre C++17 (C++11 or C++14) compiler which does not support/properly implement the __cplusplus macro (such as MSVC), you should define the macro SBLOGGER_LEGACY, in order to use this library. If you are using a pre C++20 compiler that lacks support for the aforementioned __cplusplus, you should define the SBLOGGER_OLD_DATES macro, in order to make use of this library.

Please define them either before including SBLogger or in the first line of the SmallBetterLogger.hpp file, as shown bellow.

#define SBLOGGER_LEGACY     // Pre C++17 Compiler
#define SBLOGGER_OLD_DATES  // Pre C++20 Compiler

Note: For MSVC you can fix this problem, by setting up the /Zc:__cplusplus compiler option. If you do not know how to do this, please refer to the following Microsoft guide for setting it up.

Cross-Platform Info

In order for SBLogger to work properly outside of MS Windows, SBLogger automatically detects the OS (based on the criteria found here), defining the following macros:

  • #define SBLOGGER_NIX - for Unix/Linux and Mac OS X+
  • #define SBLOGGER_OS9 - for Mac OS 9 and lower

Note: By default, MS Windows is assumed as the OS for this library. The way SBLogger detects different operating systems is the following:

// Detect OS and set the appropriate macros
#if macintosh || Macintos
	#define SBLOGGER_OS9
#elif !_WIN32
	#define SBLOGGER_NIX
#endif

// Assumes a default of MS Windows, defines specific Macro for MacOS 9 and assumes all others are Unix-like systems

Compilers and platforms tested on:

  • Windows 10 Home (both x86 and x64) with MSVC 2019 (in VS 16.5.0) using standards C++14 and C++17
  • Arch Linux (on x64) with GCC 9.2.0 using standards C++11, C++14 and C++17

Default Log Level

During compile time, it is possible to set a default log level for all of the loggers, by defining the SBLOGGER_LOG_LEVEL and giving it a value ranging between 0 and 6 (the meaning will be explained a bit further in this section). By default, the loggers are all given the level of Trace. All loggers contain the static method void sblogger::SetLoggingLevel(const sblogger::LogLevel& level), which can be set to update the logging level at runtime for all loggers (more about LOG_LEVELS further in this section).

To set the desired log level at compile time, either uncomment the line in the SmallBetterLogger.hpp file which defines the previously mentioned macro as SBLOGGER_LEVEL_TRACE, or define your own before including SBLogger:

#define SBLOGGER_LOG_LEVEL SBLOGGER_LEVEL_TRACE // Example found in "SmallBetterLogger.hpp"

Or using a number rather than another macro:

#define SBLOGGER_LOG_LEVEL 0    // Equivalent to the example above

The values that SBLOGGER_LOG_LEVEL macro can take values from 0 to 6, each of them having the following meanings, as defined in the SmallBetterLogger.hpp file:

// Log Levels macros to be used with "SBLOGGER_LOG_LEVEL" macro for defining a default level
#define SBLOGGER_LEVEL_TRACE     0
#define SBLOGGER_LEVEL_DEBUG     1
#define SBLOGGER_LEVEL_INFO      2
#define SBLOGGER_LEVEL_WARN      3
#define SBLOGGER_LEVEL_ERROR     4
#define SBLOGGER_LEVEL_CRITICAL  5
#define SBLOGGER_LEVEL_OFF       6

Note: Should any other value be provided - concretely, any value lower than 0 or higher than 6, SBLogger will assume a default level of SBLOGGER_LEVEL_TRACE.

To change the level of all logs (for all loggers, concretely: sblogger::StreamLogger, sblogger::FileLogger or sblogger::DailyLogger) during runtime, one can use the void sblogger::SetLoggingLevel(const sblogger::LogLevel& level) static method, accessible from all of the loggers. It takes as its parameter a value of the sblogger::LOG_LEVEL enum, which can be one of the following:

// Log level enum. Contains all possible log levels, such as TRACE, ERROR, FATAL etc.
enum class LogLevel
{ 
  TRACE /*= 0*/, DEBUG /*= 1*/, INFO /*= 2*/, WARN /*= 3*/, ERROR /*= 4*/, CRITICAL /*= 5*/, OFF /*= 6*/ 
};

As you can see, they mirror the previously defined log level macros. With this, one can now set the logging level during runtime, as follows:

...
sblogger::Logger::SetLoggingLevel(sblogger::LogLevel::WARN);  // Example of setting the level to WARN at runtime
...

The current logging level can also be found out at runtime, by using the const sblogger::LogLevel sblogger::GetLoggingLevel() static method, also found in all loggers:

...
auto currentLevel = sblogger::Logger::GetLoggingLevel();  // Example of getting the current level
...

Using Colours in the Standard Streams

In order to allow the usage of colours in any of the 3 supported standard streams (concretely, STDOUT, STDERR, STDLOG), you should define the SBLOGGER_COLOURS/SBLOGGER_COLORS predefined macro, either uncomment the line in the SmallBetterLogger.hpp file which contains it or define your own before including SBLogger:

#define SBLOGGER_COLOURS

Or:

#define SBLOGGER_COLORS

Note: Available colours can be found in the Placeholders section.