📝 Add logging examples

Problem:
- There are no examples for various use cases of logging.

Solution:
- Add examples.

Author: elbeno

CMakeLists.txt

@@ -188,10 +188,16 @@ target_sources(
               BASE_DIRS
               include
               FILES
+              include/log/module_id.hpp
+              include/log/string_id.hpp
+              include/log/unit.hpp
+              include/log/catalog/arguments.hpp
+              include/log/catalog/builder.hpp
               include/log/catalog/catalog.hpp
               include/log/catalog/encoder.hpp
               include/log/catalog/mipi_builder.hpp
-              include/log/catalog/mipi_messages.hpp)
+              include/log/catalog/mipi_messages.hpp
+              include/log/catalog/writer.hpp)
 
 add_library(cib_nexus INTERFACE)
 target_compile_features(cib_nexus INTERFACE cxx_std_20)

docs/logging.adoc

@@ -221,6 +221,38 @@ wrapper function (`gen_str_catalog`)] that drives the process. See
 https://github.com/intel/compile-time-init-build/blob/main/test/CMakeLists.txt[the
 test] that exercises that functionality for an example.
 
+`gen_str_catalog` is the CMake function that drives the string catalog generation.
+
+[source,cpp]
+----
+gen_str_catalog(
+    [GEN_STR_CATALOG <python-file>]
+    OUTPUT_CPP <output-cpp-file>
+    OUTPUT_JSON <output-json-file>
+    OUTPUT_XML <output-xml-file>
+    INPUT_LIBS <lib-files...>
+    INPUT_JSON <json-files...>
+    STABLE_JSON <json-files...>
+    INPUT_HEADERS <header-files...>
+    CLIENT_NAME <client-name>
+    VERSION <version>
+    GUID_ID <guid>
+    GUID_MASK <guid>
+    MODULE_ID_MAX <max-id>
+    OUTPUT_LIB <target-name>
+    OUTPUTS_TARGET <target-name>
+   [FORGET_OLD_IDS])
+----
+- `INPUT_LIBS` is a required argument: this will be the input libraries from which the undefined symbols are extracted.
+- `OUTPUT_{CPP,JSON,XML}` are the generated files. Also required.
+- `INPUT_JSON` is optional extra JSON that will be copied verbatim into the generated JSON.
+- `STABLE_JSON` is optional information about stable string and module IDs -- for example, from a previous build.
+- `CLIENT_NAME`, `VERSION`, `GUID_ID` and `GUID_MASK` are all optional input fields for the MIPI-SyS-T XML.
+- `MODULE_ID_MAX` is an optional upper bound on the assigned module IDs. This is useful to limit module ID bit-space.
+- `OUTPUT_LIB` is an optional (`STATIC`) library target consisting of the `OUTPUT_CPP` file.
+- `FORGET_OLD_IDS` is optional, and if present disregards the `STABLE_JSON` information.
+- `GEN_STR_CATALOG` is optional, and allows pointing to a different python script.
+
 === Implementing a logger
 
 Each logging implementation (configuration) provides a customization point: a
@@ -458,3 +490,20 @@ CIB_TRACE("Hello");
 
 See the https://www.mipi.org/specifications/sys-t[MIPI Sys-T spec] for more
 details.
+
+=== Examples/How-Tos
+
+I want to...
+
+- ...use the fmt logger...
+  * https://github.com/intel/compile-time-init-build/tree/main/examples/log/fmt_normal[...as my normal logger]
+  * https://github.com/intel/compile-time-init-build/tree/main/examples/log/fmt_tests[...in tests, to make sure my code logs correctly]
+  * https://github.com/intel/compile-time-init-build/tree/main/examples/log/fmt_multi[...to output to multiple places (stdout, file, etc)]
+  * https://github.com/intel/compile-time-init-build/tree/main/examples/log/fmt_custom_level[...with a custom level enumeration]
+- ...use the binary logger...
+  * https://github.com/intel/compile-time-init-build/tree/main/examples/log/binary_normal[...as my normal logger]
+  * https://github.com/intel/compile-time-init-build/tree/main/examples/log/binary_custom[...with my own binary format]
+  * https://github.com/intel/compile-time-init-build/tree/main/examples/log/binary_stable_ids[...and keep string IDs stable from build to build]
+  * https://github.com/intel/compile-time-init-build/tree/main/examples/log/binary_fixed_id[...and fix a string ID in code]
+- https://github.com/intel/compile-time-init-build/tree/main/examples/log/custom[...use my own logger]
+- https://github.com/intel/compile-time-init-build/tree/main/examples/log/secure[...use a secure logger as well as a "normal" one]

examples/CMakeLists.txt

@@ -1,14 +1,23 @@
 add_custom_target(examples)
 
+function(transform_to_example VAR VALUE)
+    cmake_path(GET CMAKE_CURRENT_LIST_DIR PARENT_PATH pp)
+    cmake_path(GET pp FILENAME prefix)
+    string(PREPEND VALUE "EXAMPLE.${prefix}.")
+    set(${VAR}
+        ${VALUE}
+        PARENT_SCOPE)
+endfunction()
+
 function(add_example)
     set(singleValueArgs NAME)
-    set(multiValueArgs FILES)
+    set(multiValueArgs FILES LIBS)
     cmake_parse_arguments(EX "" "${singleValueArgs}" "${multiValueArgs}"
                           ${ARGN})
-    string(PREPEND EX_NAME "EXAMPLE.")
+    transform_to_example(EX_NAME ${EX_NAME})
 
     add_executable(${EX_NAME} ${EX_FILES})
-    target_link_libraries(${EX_NAME} cib)
+    target_link_libraries(${EX_NAME} ${EX_LIBS})
     add_dependencies(examples ${EX_NAME})
 endfunction()
 

examples/flow/daily_routine/CMakeLists.txt

@@ -32,7 +32,7 @@ if(NOT TARGET cib)
 endif()
 
 if(COMMAND add_example)
-    add_example(NAME daily_routine FILES main.cpp)
+    add_example(NAME daily_routine FILES main.cpp LIBS cib)
 else()
     add_executable(daily_routine main.cpp)
     target_link_libraries(daily_routine cib)

examples/log/CMakeLists.txt

@@ -1 +1,12 @@
+add_subdirectory(fmt_custom_level)
+add_subdirectory(fmt_multi)
+add_subdirectory(fmt_normal)
+add_subdirectory(fmt_tests)
 
+add_subdirectory(binary_custom)
+add_subdirectory(binary_fixed_id)
+add_subdirectory(binary_stable_ids)
+add_subdirectory(binary_normal)
+
+add_subdirectory(custom)
+add_subdirectory(secure)

examples/log/binary_custom/CMakeLists.txt

@@ -0,0 +1,64 @@
+cmake_minimum_required(VERSION 3.25)
+
+project(binary_custom LANGUAGES CXX)
+
+if(NOT TARGET cib)
+    # to fetch cib, either use CPM (https://github.com/cpm-cmake/CPM.cmake) or
+    # use plain old CMake functionality
+    set(USE_CPM 1)
+
+    set(CIB_VERSION "c388a4d") # update this to a more recent commit ID (or tag)
+                               # for your project
+
+    if(USE_CPM)
+        file(
+            DOWNLOAD
+            https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.42.0/CPM.cmake
+            ${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake
+            EXPECTED_HASH
+                SHA256=2020b4fc42dba44817983e06342e682ecfc3d2f484a581f11cc5731fbe4dce8a
+        )
+        include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)
+
+        cpmaddpackage("gh:intel/compile-time-init-build#${CIB_VERSION}")
+    else()
+        include(FetchContent)
+        FetchContent_Declare(
+            cib
+            GIT_REPOSITORY https://github.com/intel/compile-time-init-build.git
+            GIT_TAG ${CIB_VERSION})
+        FetchContent_MakeAvailable(cib)
+    endif()
+endif()
+
+if(COMMAND add_example)
+    transform_to_example(binary_custom_lib binary_custom_lib)
+    transform_to_example(binary_custom_strings_lib binary_custom_strings_lib)
+    transform_to_example(binary_custom binary_custom)
+else()
+    set(binary_custom_lib binary_custom_lib)
+    set(binary_custom_strings_lib binary_custom_strings_lib)
+    set(binary_custom binary_custom)
+endif()
+
+# build the bulk of the code as a library
+add_library(${binary_custom_lib} lib.cpp)
+target_link_libraries(${binary_custom_lib} PRIVATE cib_log_binary)
+
+# generate the strings from that library
+gen_str_catalog(
+    OUTPUT_CPP
+    ${CMAKE_CURRENT_BINARY_DIR}/strings.cpp
+    OUTPUT_JSON
+    ${CMAKE_CURRENT_BINARY_DIR}/strings.json
+    OUTPUT_XML
+    ${CMAKE_CURRENT_BINARY_DIR}/strings.xml
+    INPUT_LIBS
+    ${binary_custom_lib}
+    OUTPUT_LIB
+    ${binary_custom_strings_lib})
+
+# link a stub executable with the "main" library and the strings library
+add_executable(${binary_custom} main.cpp)
+target_link_libraries(${binary_custom} ${binary_custom_lib}
+                      ${binary_custom_strings_lib})

examples/log/binary_custom/lib.cpp

@@ -0,0 +1,9 @@
+#include "logger.hpp"
+
+namespace lib {
+
+// Provide an environment for this scope that uses our builder.
+CIB_LOG_ENV(logging::binary::get_builder, custom::builder{});
+
+auto lib_func() -> void { CIB_INFO("Hello"); }
+} // namespace lib

examples/log/binary_custom/logger.hpp

@@ -0,0 +1,55 @@
+// include the binary logger and message machinery
+#include <log/catalog/encoder.hpp>
+#include <msg/message.hpp>
+
+#include <stdx/span.hpp>
+
+#include <cstddef>
+#include <cstdint>
+#include <iostream>
+
+namespace custom {
+namespace defn {
+using msg::at;
+using msg::dword_index_t;
+using msg::field;
+using msg::message;
+using msg::operator""_msb;
+using msg::operator""_lsb;
+
+// Define a message type for the custom binary format.
+// For simplicity, this message is just the 32-bit string ID.
+using id_f =
+    field<"id", std::uint32_t>::located<at{dword_index_t{0}, 31_msb, 0_lsb}>;
+using id_msg_t = message<"id", id_f>;
+} // namespace defn
+
+// Provide a builder: a structure with a build function that takes
+// various arguments and returns an (owning) message.
+struct builder : logging::mipi::default_builder<> {
+    template <auto Level, logging::packable... Ts>
+    static auto build(string_id, module_id, logging::mipi::unit_t, Ts...) {
+        using namespace msg;
+        return owning<defn::id_msg_t>{"id"_field = 42};
+    }
+};
+
+// Provide a destination: a structure with a call operator that takes a
+// stdx::span.
+struct log_destination {
+    template <std::size_t N>
+    auto operator()(stdx::span<std::uint32_t const, N> packet) const {
+        // write the binary log packet somewhere...
+        std::cout << "Got a binary log packet, string ID: " << packet[0]
+                  << '\n';
+        ;
+    }
+};
+} // namespace custom
+
+// Specialize the logging config variable template to use the binary logger with
+// a destination.
+// Remember: each translation unit that logs must see this same specialization!
+template <>
+inline auto logging::config<> =
+    logging::binary::config{custom::log_destination{}};

examples/log/binary_custom/main.cpp

@@ -0,0 +1,7 @@
+// the "main" application is a stub that calls into the library code
+
+namespace lib {
+auto lib_func() -> void;
+}
+
+auto main() -> int { lib::lib_func(); }

examples/log/binary_fixed_id/CMakeLists.txt

@@ -0,0 +1,65 @@
+cmake_minimum_required(VERSION 3.25)
+
+project(binary_fixed_id LANGUAGES CXX)
+
+if(NOT TARGET cib)
+    # to fetch cib, either use CPM (https://github.com/cpm-cmake/CPM.cmake) or
+    # use plain old CMake functionality
+    set(USE_CPM 1)
+
+    set(CIB_VERSION "c388a4d") # update this to a more recent commit ID (or tag)
+                               # for your project
+
+    if(USE_CPM)
+        file(
+            DOWNLOAD
+            https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.42.0/CPM.cmake
+            ${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake
+            EXPECTED_HASH
+                SHA256=2020b4fc42dba44817983e06342e682ecfc3d2f484a581f11cc5731fbe4dce8a
+        )
+        include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)
+
+        cpmaddpackage("gh:intel/compile-time-init-build#${CIB_VERSION}")
+    else()
+        include(FetchContent)
+        FetchContent_Declare(
+            cib
+            GIT_REPOSITORY https://github.com/intel/compile-time-init-build.git
+            GIT_TAG ${CIB_VERSION})
+        FetchContent_MakeAvailable(cib)
+    endif()
+endif()
+
+if(COMMAND add_example)
+    transform_to_example(binary_fixed_id_lib binary_fixed_id_lib)
+    transform_to_example(binary_fixed_id_strings_lib
+                         binary_fixed_id_strings_lib)
+    transform_to_example(binary_fixed_id binary_fixed_id)
+else()
+    set(binary_fixed_id_lib binary_fixed_id_lib)
+    set(binary_fixed_id_strings_lib binary_fixed_id_strings_lib)
+    set(binary_fixed_id binary_fixed_id)
+endif()
+
+# build the bulk of the code as a library
+add_library(${binary_fixed_id_lib} lib.cpp)
+target_link_libraries(${binary_fixed_id_lib} PRIVATE cib_log_binary)
+
+# generate the strings from that library
+gen_str_catalog(
+    OUTPUT_CPP
+    ${CMAKE_CURRENT_BINARY_DIR}/strings.cpp
+    OUTPUT_JSON
+    ${CMAKE_CURRENT_BINARY_DIR}/strings.json
+    OUTPUT_XML
+    ${CMAKE_CURRENT_BINARY_DIR}/strings.xml
+    INPUT_LIBS
+    ${binary_fixed_id_lib}
+    OUTPUT_LIB
+    ${binary_fixed_id_strings_lib})
+
+# link a stub executable with the "main" library and the strings library
+add_executable(${binary_fixed_id} main.cpp)
+target_link_libraries(${binary_fixed_id} ${binary_fixed_id_lib}
+                      ${binary_fixed_id_strings_lib})