From f4c22b03d5d3aa753cca8e716636ac4eb29b0917 Mon Sep 17 00:00:00 2001 From: Sergey Podobry Date: Mon, 21 Oct 2019 14:51:34 +0300 Subject: [PATCH] Update README.md, prepare for 1.1.5 release --- README.md | 66 +++++++++++++++------------- samples/CMakeLists.txt | 2 +- samples/NativeEOL/CMakeLists.txt | 3 -- samples/NativeEOL/Main.cpp | 21 --------- samples/SkipNativeEOL/CMakeLists.txt | 3 ++ samples/SkipNativeEOL/Main.cpp | 23 ++++++++++ 6 files changed, 63 insertions(+), 55 deletions(-) delete mode 100644 samples/NativeEOL/CMakeLists.txt delete mode 100644 samples/NativeEOL/Main.cpp create mode 100644 samples/SkipNativeEOL/CMakeLists.txt create mode 100644 samples/SkipNativeEOL/Main.cpp diff --git a/README.md b/README.md index a94579cf..a43ec950 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,9 @@ Pretty powerful logging library in about 1000 lines of code [![Build Status](htt - [Record](#record) - [Formatter](#formatter) - [TxtFormatter](#txtformatter) + - [TxtFormatterUtcTime](#txtformatterutctime) - [CsvFormatter](#csvformatter) + - [CsvFormatterUtcTime](#csvformatterutctime) - [FuncMessageFormatter](#funcmessageformatter) - [MessageOnlyFormatter](#messageonlyformatter) - [Converter](#converter) @@ -45,6 +47,7 @@ Pretty powerful logging library in about 1000 lines of code [![Build Status](htt - [Wide string support](#wide-string-support) - [Performance](#performance) - [Printf style formatting](#printf-style-formatting) + - [LOG_XXX macro name clashes](#log_xxx-macro-name-clashes) - [Extending](#extending) - [Custom data type](#custom-data-type) - [Custom appender](#custom-appender) @@ -60,23 +63,28 @@ Pretty powerful logging library in about 1000 lines of code [![Build Status](htt # Introduction ## Hello log! -Plog is a C++ logging library that is designed to be as simple, small and flexible as possible. It is created as an alternative to existing large libraries and provides some unique features as [CSV log format]((#csvformatter)) and [automatic 'this' pointer capture](#automatic-this-pointer-capture). +Plog is a C++ logging library that is designed to be as simple, small and flexible as possible. It is created as an alternative to existing large libraries and provides some unique features as [CSV log format]((#csvformatter)) and [wide string support](#wide-string-support). Here is a minimal hello log sample: ```cpp -#include // Step1: include the header. +#include // Step1: include the header int main() { - plog::init(plog::debug, "Hello.txt"); // Step2: initialize the logger. + plog::init(plog::debug, "Hello.txt"); // Step2: initialize the logger - // Step3: write log messages using a special macro. - // There are several log macros, use the macro you liked the most. + // Step3: write log messages using a special macro + // There are several log macros, use the macro you liked the most PLOGD << "Hello log!"; // short macro PLOG_DEBUG << "Hello log!"; // long macro PLOG(plog::debug) << "Hello log!"; // function-style macro + + // Also you can use LOG_XXX macro but it may clash with other logging libraries + LOGD << "Hello log!"; // short macro + LOG_DEBUG << "Hello log!"; // long macro + LOG(plog::debug) << "Hello log!"; // function-style macro return 0; } @@ -97,7 +105,7 @@ And its output: - No 3rd-party dependencies - Cross-platform: Windows, Linux, FreeBSD, macOS, Android, RTEMS (gcc, clang, msvc, mingw, mingw-w64, icc, c++builder) - Thread and type safe -- Formatters: [TXT](#txtformatter), [CSV](#csvformatter), [FuncMessage](#funcmessageformatter) +- Formatters: [TXT](#txtformatter), [CSV](#csvformatter), [FuncMessage](#funcmessageformatter), [MessageOnly](#messageonlyformatter) - Appenders: [RollingFile](#rollingfileappender), [Console](#consoleappender), [ColorConsole](#colorconsoleappender), [Android](#androidappender), [EventLog](#eventlogappender), [DebugOutput](#debugoutputappender) - [Automatic 'this' pointer capture](#automatic-this-pointer-capture) (supported only on msvc) - [Lazy stream evaluation](#lazy-stream-evaluation) @@ -105,6 +113,8 @@ And its output: - Doesn't require C++11 - [Extendable](#extending) - No `windows.h` dependency +- Can use UTC or local time +- Uses modern CMake # Usage To start using plog you need to make 3 simple steps. @@ -114,7 +124,6 @@ At first your project needs to know about plog. For that you have to: 1. Add `plog/include` to the project include paths 2. Add `#include ` into your cpp/h files (if you have precompiled headers it is a good place to add this include there) -3. If the project include paths include `` or `` or any other header that defines macros with names starting with "LOG", add `#define PLOG_OMIT_LOG_DEFINES` **before** `#include ` ## Step 2: Initialization The next step is to initialize the [Logger](#logger). This is done by the following `plog::init` function: @@ -623,6 +632,9 @@ This is a classic log format available in almost any log library. It is good for 2014-11-11 00:29:06.261 DEBUG [4460] [Object::~Object@13] ``` +### TxtFormatterUtcTime +This is a variant of [TxtFormatter](#txtformatter) that uses UTC time instead of local time. + ### CsvFormatter This is the most powerful log format. It can be easily read without any tools (but slighlty harder than [TXT format](#txtformatter)) and can be heavily analyzed if it is opened with a CSV-aware tool (like Excel). One rows can be highlighted according to their cell values, another rows can be hidden, columns can be manipulated and you can even run SQL queries on log data! This is a recommended format if logs are big and require heavy analysis. Also 'this' pointer is shown so object instances can be told apart. @@ -640,6 +652,9 @@ Date;Time;Severity;TID;This;Function;Message *Note: message size is limited to 32000 chars.* +### CsvFormatterUtcTime +This is a variant of [CsvFormatter](#csvformatter) that uses UTC time instead of local time. + ### FuncMessageFormatter This format is designed to be used with appenders that provide their own timestamps (like [AndroidAppender](#androidappender) or linux syslog facility). @@ -800,27 +815,12 @@ Stream output in plog has several improvements over the standard `std::ostream`: ## Headers to include The core plog functionality is provided by inclusion of `plog/Log.h` file. Extra components require inclusion of corresponding extra headers after `plog/Log.h`. -![Plog core and extra components](http://gravizo.com/g?@startuml;package%20"Plog%20core\\n%28no%20additional%20include,%20just%20plog/Log.h%29"%20{;%20%20class%20TxtFormatter;%20%20class%20CsvFormatter;%20%20class%20UTF8Converter;%20%20class%20RollingFileAppender;};package%20"Plog%20extra\\n%28requires%20additional%20include%29"%20{;%20%20class%20FuncMessageFormatter;%20%20class%20ConsoleAppender;%20%20class%20ColorConsoleAppender;%20%20class%20AndroidAppender;%20%20class%20DebugOutputAppender;%20%20class%20EventLogAppender;};hide%20empty%20members;hide%20empty%20fields;@enduml) - +Core components are: +- [TxtFormatter](#txtformatter)/[TxtFormatterUtcTime](#txtformatterutctime) +- [CsvFormatter](#csvformatter)/[CsvFormatterUtcTime](#csvformatterutctime) +- [UTF8Converter](#utf8converter) +- [NativeEOLConverter](#nativeeolconverter) +- [RollingFileAppender](#rollingfileappender) ## Unicode Plog is unicode aware and wide string friendly. All messages are converted to a system native char type: @@ -880,6 +880,11 @@ PLOGI.printf("%d %s", 42, "test"); PLOGI.printf(L"%d %S", 42, "test"); // wchar_t version ``` +## LOG_XXX macro name clashes +`LOG_XXX` macro names may be in conflict with other libraries (for example [syslog](https://linux.die.net/man/3/syslog)). In such cases you can disable `LOG_XXX` macro by defining `PLOG_OMIT_LOG_DEFINES` and use `PLOG_XXX`. + +*Define `PLOG_OMIT_LOG_DEFINES` before `#include ` or in the project settings!* + # Extending Plog can be easily extended to support new: @@ -977,9 +982,10 @@ There are a number of samples that demonstrate various aspects of using plog. Th |[Library](samples/Library)|Shows plog usage in static libraries.| |[MultiAppender](samples/MultiAppender)|Shows how to use multiple appenders with the same logger.| |[MultiInstance](samples/MultiInstance)|Shows how to use multiple logger instances, each instance has its own independent configuration.| -|[NativeEOL](samples/NativeEOL)|Shows how to use [NativeEOLConverter](#nativeeolconverter).| +|[SkipNativeEOL](samples/SkipNativeEOL)|Shows how to skip [NativeEOLConverter](#nativeeolconverter).| |[ObjectiveC](samples/ObjectiveC)|Shows that plog can be used in ObjectiveC++.| |[Performance](samples/Performance)|Measures time per a log call.| +|[UtcTime](samples/UtcTime)|Shows how to use UTC time instead of local time.| # References @@ -1013,7 +1019,7 @@ Plog is licensed under the [MPL version 2.0](http://mozilla.org/MPL/2.0/). You c # Version history -## Version 1.1.5 (TBD) +## Version 1.1.5 (21 Oct 2019) - New: Use `NativeEOLConverter` by default (#145) - New: Add logger `instanceId` into `Record` (#141) - New: Add support for the printf style formatting (#139) diff --git a/samples/CMakeLists.txt b/samples/CMakeLists.txt index 9f040caa..a5e65dc5 100644 --- a/samples/CMakeLists.txt +++ b/samples/CMakeLists.txt @@ -54,7 +54,7 @@ add_subdirectory(Hello) add_subdirectory(Library) add_subdirectory(MultiAppender) add_subdirectory(MultiInstance) -add_subdirectory(NativeEOL) +add_subdirectory(SkipNativeEOL) add_subdirectory(ObjectiveC) add_subdirectory(Performance) add_subdirectory(UtcTime) \ No newline at end of file diff --git a/samples/NativeEOL/CMakeLists.txt b/samples/NativeEOL/CMakeLists.txt deleted file mode 100644 index 634c934f..00000000 --- a/samples/NativeEOL/CMakeLists.txt +++ /dev/null @@ -1,3 +0,0 @@ -add_executable(NativeEOL Main.cpp) -target_link_libraries(NativeEOL plog) -set_target_properties(NativeEOL PROPERTIES FOLDER Samples) \ No newline at end of file diff --git a/samples/NativeEOL/Main.cpp b/samples/NativeEOL/Main.cpp deleted file mode 100644 index 792ab780..00000000 --- a/samples/NativeEOL/Main.cpp +++ /dev/null @@ -1,21 +0,0 @@ -// -// NativeEOL - shows how to use NativeEOLConverter. -// - -#include -#include - -int main() -{ - // NativeEOLConverter will use on Windows and on everything else as line endings. As a template parameter it accepts another converter (by default UTF8Converter). - static plog::RollingFileAppender > fileAppender("NativeEOL.log", 8000, 3); // Create an appender with NativeEOLConverter. - plog::init(plog::debug, &fileAppender); // Initialize the logger. - - // Write some data. - for (int i = 0; i < 100; ++i) - { - PLOGI << "i: " << i; - } - - return 0; -} diff --git a/samples/SkipNativeEOL/CMakeLists.txt b/samples/SkipNativeEOL/CMakeLists.txt new file mode 100644 index 00000000..45bfe54a --- /dev/null +++ b/samples/SkipNativeEOL/CMakeLists.txt @@ -0,0 +1,3 @@ +add_executable(SkipNativeEOL Main.cpp) +target_link_libraries(SkipNativeEOL plog) +set_target_properties(SkipNativeEOL PROPERTIES FOLDER Samples) diff --git a/samples/SkipNativeEOL/Main.cpp b/samples/SkipNativeEOL/Main.cpp new file mode 100644 index 00000000..9425cc8a --- /dev/null +++ b/samples/SkipNativeEOL/Main.cpp @@ -0,0 +1,23 @@ +// +// SkipNativeEOL - shows how to skip NativeEOLConverter. +// + +#include +#include + +int main() +{ + // NativeEOLConverter will use on Windows and on everything else as line endings. + // It's used by default. + // If you want to always use you can skip NativeEOLConverter and specify UTF8Converter directly. + static plog::RollingFileAppender fileAppender("SkipNativeEOL.log", 8000, 3); // Create an appender without NativeEOLConverter. + plog::init(plog::debug, &fileAppender); // Initialize the logger. + + // Write some data. + for (int i = 0; i < 100; ++i) + { + PLOGI << "i: " << i; + } + + return 0; +}