From 98ce31bfaa82b547ba72cb04427ea00dc30da21c Mon Sep 17 00:00:00 2001 From: Julian Eisel Date: Tue, 16 Jul 2024 18:59:55 +0200 Subject: [PATCH 1/2] Move Clog documentation from source to developer handbook This is documentation that I would expect to find in the developer handbook. Was surprised to find nothing when typing "clog" in search. Here we can have a more elaborate (more description with good formatting). In the Clog header we can then have a brief description and a link to the documentation. --- docs/handbook/tooling/clog.md | 37 +++++++++++++++++++++++++++++ docs/handbook/tooling/navigation.md | 1 + 2 files changed, 38 insertions(+) create mode 100644 docs/handbook/tooling/clog.md diff --git a/docs/handbook/tooling/clog.md b/docs/handbook/tooling/clog.md new file mode 100644 index 00000000..d8636a9e --- /dev/null +++ b/docs/handbook/tooling/clog.md @@ -0,0 +1,37 @@ +# C/C++ Logging Library (Clog) + +Clog is Blender's own logging library, located under `intern/clog/`. + +## Usage + +- `CLG_LOGREF_DECLARE_GLOBAL` macro to declare `CLG_LogRef` pointers. +- `CLOG_` prefixed macros for logging. + +## Identifiers + +`CLG_LogRef` holds an identifier which defines the category of the logger. +You can define and use identifiers as needed, logging will lazily initialize them. +By convention lower case dot separated identifiers are used, eg: +`module.sub_module`, this allows filtering by `module.*`, +see `CLG_type_filter_include`, `CLG_type_filter_exclude`. + +There is currently no functionality to remove a category once it's created. + +## Severity + +- `INFO`: Simply log events, uses verbosity levels to control how much information to show. +- `WARN`: General warnings (which aren't necessary to show to users). +- `ERROR`: An error we can recover from, should not happen. +- `FATAL`: Similar to assert. This logs the message, then a stack trace and abort. + +## Verbosity Level + +Usage: + +| Level | Description | +| ----- | ------------| +| 0 | Always show (used for warnings, errors). Should never get in the way or become annoying. | +| 1 | Top level module actions (eg: load a file, create a new window .. etc). | +| 2 | Actions within a module (steps which compose an action, but don't flood output). Running a tool, full data recalculation. | +| 3 | Detailed actions which may be of interest when debugging internal logic of a module. These *may* flood the log with details. | +| 4+ | May be used for more details than 3, should be avoided but not prevented. | diff --git a/docs/handbook/tooling/navigation.md b/docs/handbook/tooling/navigation.md index f63761c2..35fd5ddd 100644 --- a/docs/handbook/tooling/navigation.md +++ b/docs/handbook/tooling/navigation.md @@ -3,6 +3,7 @@ - [Address Sanitizer](asan.md) - [Valgrind](valgrind.md) - [GDB](gdb.md) + - [Clog: C/C++ Logging Library](clog.md) - [Doxygen](doxygen.md) - Python - [Profiling](python_profile.md) -- 2.30.2 From 898caa1ef04cb8c7500a6362494e2a987e5e1ab2 Mon Sep 17 00:00:00 2001 From: Julian Eisel Date: Tue, 16 Jul 2024 19:20:00 +0200 Subject: [PATCH 2/2] Improve introduction paragraph --- docs/handbook/tooling/clog.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/handbook/tooling/clog.md b/docs/handbook/tooling/clog.md index d8636a9e..460ec5e7 100644 --- a/docs/handbook/tooling/clog.md +++ b/docs/handbook/tooling/clog.md @@ -1,6 +1,9 @@ # C/C++ Logging Library (Clog) -Clog is Blender's own logging library, located under `intern/clog/`. +Clog is Blender's own logging library, located in `intern/clog/`. Logging can be enabled by +starting Blender with the `--log` command line options. Refer to the [User +Manual](https://docs.blender.org/manual/en/dev/advanced/command_line/arguments.html#command-line-args-logging-options) +for more options to control the logging via command line arguments. ## Usage -- 2.30.2