Skip to content

Commit 736a024

Browse files
elbenoelbeno
authored
Merge pull request #779 from elbeno/logging-examples
📝 Add logging examples
2 parents a4bffd8 + 0933ed7 commit 736a024

36 files changed

+973
-7
lines changed

‎CMakeLists.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -188,10 +188,16 @@ target_sources(
188188
BASE_DIRS
189189
include
190190
FILES
191+
include/log/module_id.hpp
192+
include/log/string_id.hpp
193+
include/log/unit.hpp
194+
include/log/catalog/arguments.hpp
195+
include/log/catalog/builder.hpp
191196
include/log/catalog/catalog.hpp
192197
include/log/catalog/encoder.hpp
193198
include/log/catalog/mipi_builder.hpp
194-
include/log/catalog/mipi_messages.hpp)
199+
include/log/catalog/mipi_messages.hpp
200+
include/log/catalog/writer.hpp)
195201

196202
add_library(cib_nexus INTERFACE)
197203
target_compile_features(cib_nexus INTERFACE cxx_std_20)

‎docs/logging.adoc‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,38 @@ wrapper function (`gen_str_catalog`)] that drives the process. See
221221
https://github.com/intel/compile-time-init-build/blob/main/test/CMakeLists.txt[the
222222
test] that exercises that functionality for an example.
223223

224+
`gen_str_catalog` is the CMake function that drives the string catalog generation.
225+
226+
[source,cpp]
227+
----
228+
gen_str_catalog(
229+
GEN_STR_CATALOG <python-file>
230+
OUTPUT_CPP <output-cpp-file>
231+
OUTPUT_JSON <output-json-file>
232+
OUTPUT_XML <output-xml-file>
233+
INPUT_LIBS <lib-files...>
234+
INPUT_JSON <json-files...>
235+
STABLE_JSON <json-files...>
236+
INPUT_HEADERS <header-files...>
237+
CLIENT_NAME <client-name>
238+
VERSION <version>
239+
GUID_ID <guid>
240+
GUID_MASK <guid>
241+
MODULE_ID_MAX <max-id>
242+
OUTPUT_LIB <target-name>
243+
OUTPUTS_TARGET <target-name>
244+
FORGET_OLD_IDS)
245+
----
246+
- `INPUT_LIBS` is a required argument: this will be the input libraries from which the undefined symbols are extracted.
247+
- `OUTPUT_{CPP,JSON,XML}` are the generated files. Also required.
248+
- `INPUT_JSON` is optional extra JSON that will be copied verbatim into the generated JSON.
249+
- `STABLE_JSON` is optional information about stable string and module IDs -- for example, from a previous build.
250+
- `CLIENT_NAME`, `VERSION`, `GUID_ID` and `GUID_MASK` are all optional input fields for the MIPI-SyS-T XML.
251+
- `MODULE_ID_MAX` is an optional upper bound on the assigned module IDs. This is useful to limit module ID bit-space.
252+
- `OUTPUT_LIB` is an optional (`STATIC`) library target consisting of the `OUTPUT_CPP` file.
253+
- `FORGET_OLD_IDS` is optional, and if present disregards the `STABLE_JSON` information.
254+
- `GEN_STR_CATALOG` is optional, and allows pointing to a different python script.
255+
224256
=== Implementing a logger
225257

226258
Each logging implementation (configuration) provides a customization point: a
@@ -458,3 +490,20 @@ CIB_TRACE("Hello");
458490

459491
See the https://www.mipi.org/specifications/sys-t[MIPI Sys-T spec] for more
460492
details.
493+
494+
=== Examples/How-Tos
495+
496+
I want to...
497+
498+
- ...use the fmt logger...
499+
* https://github.com/intel/compile-time-init-build/tree/main/examples/log/fmt_normal[...as my normal logger]
500+
* https://github.com/intel/compile-time-init-build/tree/main/examples/log/fmt_tests[...in tests, to make sure my code logs correctly]
501+
* https://github.com/intel/compile-time-init-build/tree/main/examples/log/fmt_multi[...to output to multiple places (stdout, file, etc)]
502+
* https://github.com/intel/compile-time-init-build/tree/main/examples/log/fmt_custom_level[...with a custom level enumeration]
503+
- ...use the binary logger...
504+
* https://github.com/intel/compile-time-init-build/tree/main/examples/log/binary_normal[...as my normal logger]
505+
* https://github.com/intel/compile-time-init-build/tree/main/examples/log/binary_custom[...with my own binary format]
506+
* https://github.com/intel/compile-time-init-build/tree/main/examples/log/binary_stable_ids[...and keep string IDs stable from build to build]
507+
* https://github.com/intel/compile-time-init-build/tree/main/examples/log/binary_fixed_id[...and fix a string ID in code]
508+
- https://github.com/intel/compile-time-init-build/tree/main/examples/log/custom[...use my own logger]
509+
- 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‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,23 @@
11
add_custom_target(examples)
22

3+
function(transform_to_example VAR VALUE)
4+
cmake_path(GET CMAKE_CURRENT_LIST_DIR PARENT_PATH pp)
5+
cmake_path(GET pp FILENAME prefix)
6+
string(PREPEND VALUE "EXAMPLE.${prefix}.")
7+
set(${VAR}
8+
${VALUE}
9+
PARENT_SCOPE)
10+
endfunction()
11+
312
function(add_example)
413
set(singleValueArgs NAME)
5-
set(multiValueArgs FILES)
14+
set(multiValueArgs FILES LIBS)
615
cmake_parse_arguments(EX "" "${singleValueArgs}" "${multiValueArgs}"
716
${ARGN})
8-
string(PREPEND EX_NAME "EXAMPLE.")
17+
transform_to_example(EX_NAME ${EX_NAME})
918

1019
add_executable(${EX_NAME} ${EX_FILES})
11-
target_link_libraries(${EX_NAME} cib)
20+
target_link_libraries(${EX_NAME} ${EX_LIBS})
1221
add_dependencies(examples ${EX_NAME})
1322
endfunction()
1423

‎examples/flow/daily_routine/CMakeLists.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ if(NOT TARGET cib)
3232
endif()
3333

3434
if(COMMAND add_example)
35-
add_example(NAME daily_routine FILES main.cpp)
35+
add_example(NAME daily_routine FILES main.cpp LIBS cib)
3636
else()
3737
add_executable(daily_routine main.cpp)
3838
target_link_libraries(daily_routine cib)

‎examples/log/CMakeLists.txt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,12 @@
1+
add_subdirectory(fmt_custom_level)
2+
add_subdirectory(fmt_multi)
3+
add_subdirectory(fmt_normal)
4+
add_subdirectory(fmt_tests)
15

6+
add_subdirectory(binary_custom)
7+
add_subdirectory(binary_fixed_id)
8+
add_subdirectory(binary_stable_ids)
9+
add_subdirectory(binary_normal)
10+
11+
add_subdirectory(custom)
12+
add_subdirectory(secure)

‎examples/log/binary_custom/CMakeLists.txt‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
cmake_minimum_required(VERSION 3.25)
2+
3+
project(binary_custom LANGUAGES CXX)
4+
5+
if(NOT TARGET cib)
6+
# to fetch cib, either use CPM (https://github.com/cpm-cmake/CPM.cmake) or
7+
# use plain old CMake functionality
8+
set(USE_CPM 1)
9+
10+
set(CIB_VERSION "c388a4d") # update this to a more recent commit ID (or tag)
11+
# for your project
12+
13+
if(USE_CPM)
14+
file(
15+
DOWNLOAD
16+
https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.42.0/CPM.cmake
17+
${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake
18+
EXPECTED_HASH
19+
SHA256=2020b4fc42dba44817983e06342e682ecfc3d2f484a581f11cc5731fbe4dce8a
20+
)
21+
include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)
22+
23+
cpmaddpackage("gh:intel/compile-time-init-build#${CIB_VERSION}")
24+
else()
25+
include(FetchContent)
26+
FetchContent_Declare(
27+
cib
28+
GIT_REPOSITORY https://github.com/intel/compile-time-init-build.git
29+
GIT_TAG ${CIB_VERSION})
30+
FetchContent_MakeAvailable(cib)
31+
endif()
32+
endif()
33+
34+
if(COMMAND add_example)
35+
transform_to_example(binary_custom_lib binary_custom_lib)
36+
transform_to_example(binary_custom_strings_lib binary_custom_strings_lib)
37+
transform_to_example(binary_custom binary_custom)
38+
else()
39+
set(binary_custom_lib binary_custom_lib)
40+
set(binary_custom_strings_lib binary_custom_strings_lib)
41+
set(binary_custom binary_custom)
42+
endif()
43+
44+
# build the bulk of the code as a library
45+
add_library(${binary_custom_lib} lib.cpp)
46+
target_link_libraries(${binary_custom_lib} PRIVATE cib_log_binary)
47+
48+
# generate the strings from that library
49+
gen_str_catalog(
50+
OUTPUT_CPP
51+
${CMAKE_CURRENT_BINARY_DIR}/strings.cpp
52+
OUTPUT_JSON
53+
${CMAKE_CURRENT_BINARY_DIR}/strings.json
54+
OUTPUT_XML
55+
${CMAKE_CURRENT_BINARY_DIR}/strings.xml
56+
INPUT_LIBS
57+
${binary_custom_lib}
58+
OUTPUT_LIB
59+
${binary_custom_strings_lib})
60+
61+
# link a stub executable with the "main" library and the strings library
62+
add_executable(${binary_custom} main.cpp)
63+
target_link_libraries(${binary_custom} ${binary_custom_lib}
64+
${binary_custom_strings_lib})

‎examples/log/binary_custom/lib.cpp‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#include "logger.hpp"
2+
3+
namespace lib {
4+
5+
// Provide an environment for this scope that uses our builder.
6+
CIB_LOG_ENV(logging::binary::get_builder, custom::builder{});
7+
8+
auto lib_func() -> void { CIB_INFO("Hello"); }
9+
} // namespace lib

‎examples/log/binary_custom/logger.hpp‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
// include the binary logger and message machinery
2+
#include <log/catalog/encoder.hpp>
3+
#include <msg/message.hpp>
4+
5+
#include <stdx/span.hpp>
6+
7+
#include <cstddef>
8+
#include <cstdint>
9+
#include <iostream>
10+
11+
namespace custom {
12+
namespace defn {
13+
using msg::at;
14+
using msg::dword_index_t;
15+
using msg::field;
16+
using msg::message;
17+
using msg::operator""_msb;
18+
using msg::operator""_lsb;
19+
20+
// Define a message type for the custom binary format.
21+
// For simplicity, this message is just the 32-bit string ID.
22+
using id_f =
23+
field<"id", std::uint32_t>::located<at{dword_index_t{0}, 31_msb, 0_lsb}>;
24+
using id_msg_t = message<"id", id_f>;
25+
} // namespace defn
26+
27+
// Provide a builder: a structure with a build function that takes
28+
// various arguments and returns an (owning) message.
29+
struct builder : logging::mipi::default_builder<> {
30+
template <auto Level, logging::packable... Ts>
31+
static auto build(string_id, module_id, logging::mipi::unit_t, Ts...) {
32+
using namespace msg;
33+
return owning<defn::id_msg_t>{"id"_field = 42};
34+
}
35+
};
36+
37+
// Provide a destination: a structure with a call operator that takes a
38+
// stdx::span.
39+
struct log_destination {
40+
template <std::size_t N>
41+
auto operator()(stdx::span<std::uint32_t const, N> packet) const {
42+
// write the binary log packet somewhere...
43+
std::cout << "Got a binary log packet, string ID: " << packet[0]
44+
<< '\n';
45+
;
46+
}
47+
};
48+
} // namespace custom
49+
50+
// Specialize the logging config variable template to use the binary logger with
51+
// a destination.
52+
// Remember: each translation unit that logs must see this same specialization!
53+
template <>
54+
inline auto logging::config<> =
55+
logging::binary::config{custom::log_destination{}};

‎examples/log/binary_custom/main.cpp‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
// the "main" application is a stub that calls into the library code
2+
3+
namespace lib {
4+
auto lib_func() -> void;
5+
}
6+
7+
auto main() -> int { lib::lib_func(); }

‎examples/log/binary_fixed_id/CMakeLists.txt‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
cmake_minimum_required(VERSION 3.25)
2+
3+
project(binary_fixed_id LANGUAGES CXX)
4+
5+
if(NOT TARGET cib)
6+
# to fetch cib, either use CPM (https://github.com/cpm-cmake/CPM.cmake) or
7+
# use plain old CMake functionality
8+
set(USE_CPM 1)
9+
10+
set(CIB_VERSION "c388a4d") # update this to a more recent commit ID (or tag)
11+
# for your project
12+
13+
if(USE_CPM)
14+
file(
15+
DOWNLOAD
16+
https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.42.0/CPM.cmake
17+
${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake
18+
EXPECTED_HASH
19+
SHA256=2020b4fc42dba44817983e06342e682ecfc3d2f484a581f11cc5731fbe4dce8a
20+
)
21+
include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)
22+
23+
cpmaddpackage("gh:intel/compile-time-init-build#${CIB_VERSION}")
24+
else()
25+
include(FetchContent)
26+
FetchContent_Declare(
27+
cib
28+
GIT_REPOSITORY https://github.com/intel/compile-time-init-build.git
29+
GIT_TAG ${CIB_VERSION})
30+
FetchContent_MakeAvailable(cib)
31+
endif()
32+
endif()
33+
34+
if(COMMAND add_example)
35+
transform_to_example(binary_fixed_id_lib binary_fixed_id_lib)
36+
transform_to_example(binary_fixed_id_strings_lib
37+
binary_fixed_id_strings_lib)
38+
transform_to_example(binary_fixed_id binary_fixed_id)
39+
else()
40+
set(binary_fixed_id_lib binary_fixed_id_lib)
41+
set(binary_fixed_id_strings_lib binary_fixed_id_strings_lib)
42+
set(binary_fixed_id binary_fixed_id)
43+
endif()
44+
45+
# build the bulk of the code as a library
46+
add_library(${binary_fixed_id_lib} lib.cpp)
47+
target_link_libraries(${binary_fixed_id_lib} PRIVATE cib_log_binary)
48+
49+
# generate the strings from that library
50+
gen_str_catalog(
51+
OUTPUT_CPP
52+
${CMAKE_CURRENT_BINARY_DIR}/strings.cpp
53+
OUTPUT_JSON
54+
${CMAKE_CURRENT_BINARY_DIR}/strings.json
55+
OUTPUT_XML
56+
${CMAKE_CURRENT_BINARY_DIR}/strings.xml
57+
INPUT_LIBS
58+
${binary_fixed_id_lib}
59+
OUTPUT_LIB
60+
${binary_fixed_id_strings_lib})
61+
62+
# link a stub executable with the "main" library and the strings library
63+
add_executable(${binary_fixed_id} main.cpp)
64+
target_link_libraries(${binary_fixed_id} ${binary_fixed_id_lib}
65+
${binary_fixed_id_strings_lib})

0 commit comments

Comments
 (0)