diff --git a/docs/handbook/tooling/clog.md b/docs/handbook/tooling/clog.md new file mode 100644 index 00000000..460ec5e7 --- /dev/null +++ b/docs/handbook/tooling/clog.md @@ -0,0 +1,40 @@ +# C/C++ Logging Library (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 + +- `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)