X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=CONTRIBUTING.adoc;h=32fd796343b5b669aadf69ca9bd37686cd1f89f4;hb=3fadfbc0c91f82c46bd36e6e0657ea93570c9db1;hp=e81d42b7cb76d50ad1f61bc71cf7c78986903a70;hpb=f9ded0e0b7cec670982963369284612ec1a251c7;p=babeltrace.git diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index e81d42b7..32fd7963 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -69,9 +69,9 @@ node of the graph keeps all other reachable nodes alive. The scheme employed in Babeltrace to break this cycle consists in the "children" holding *reverse component references* to their parents. That -is, in the context of CTF IR, that event classes hold a reference to -their parent stream class and stream classes hold a reference to their -parent trace. +is, in the context of the trace IR, that event classes hold a reference +to their parent stream class and stream classes hold a reference to +their parent trace. On the other hand, parents hold *claiming aggregation references* to their children. A claiming aggregation reference means that the object @@ -225,7 +225,7 @@ image::doc/contributing-images/bt-ref13.png[] == Valgrind To use Valgrind on an application (for example, the CLI or a test) which -loads libbabeltrace, use: +loads libbabeltrace2, use: $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \ BABELTRACE_NO_DLCLOSE=1 valgrind --leak-check=full \ @@ -236,7 +236,7 @@ loads libbabeltrace, use: the Python plugin provider (Valgrind will probably show a lot of errors which originate from Python interpreter anyway). -`BABELTRACE_NO_DLCLOSE=1` makes libbabeltrace not close the shared +`BABELTRACE_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared libraries (plugins) which it loads. This is needed to see the appropriate backtrace when Valgrind shows errors. @@ -280,22 +280,22 @@ library (`logging` directory). The logging API headers are: -``:: +``:: Public header which a library user can use to control and read - libbabeltrace's current log level. + libbabeltrace2's current log level. -``:: +``:: Internal, generic logging API which you can use in any Babeltrace subproject. This is the translation of `zf_log.h`. -``:: +``:: Specific internal header to use within the library. This header defines `BT_LOG_OUTPUT_LEVEL` to a custom, library-wide hidden symbol which is the library's current log level before including - ``. + ``. -Do not include `` or -`` in a header which contains logging +Do not include `` or +`` in a header which contains logging statements: this header could be included in source files which define a different <>, for example. See <>. @@ -355,14 +355,14 @@ get the configured minimal log level. `_bt_log_global_output_lvl` symbol. In practice, we never use this symbol, and always make sure that `BT_LOG_OUTPUT_LEVEL` is defined to a module-wise or subproject-wise hidden symbol before including -``. In the library, -`` does this job: just include this +``. In the library, +`` does this job: just include this header which defines `BT_LOG_OUTPUT_LEVEL` to the appropriate symbol -before it includes ``. In plugins, for +before it includes ``. In plugins, for example, there is one log level per component class, which makes log filtering easier during execution. + -In libbabeltrace, the user can set the current run-time log level with +In libbabeltrace2, the user can set the current run-time log level with the `bt_logging_set_global_level()` function, for example: + -- @@ -431,6 +431,24 @@ contain their log level in their name: `BT_LOGF_MEM(data_ptr, data_size, "format string", ...)`:: Memory fatal logging statement. +`BT_LOGV_ERRNO("initial message", "format string", ...)`:: + `errno` string verbose logging statement. + +`BT_LOGD_ERRNO("initial message", "format string", ...)`:: + `errno` string debug logging statement. + +`BT_LOGI_ERRNO("initial message", "format string", ...)`:: + `errno` string info logging statement. + +`BT_LOGW_ERRNO("initial message", "format string", ...)`:: + `errno` string warning logging statement. + +`BT_LOGE_ERRNO("initial message", "format string", ...)`:: + `errno` string error logging statement. + +`BT_LOGF_ERRNO("initial message", "format string", ...)`:: + `errno` string fatal logging statement. + `BT_LOGV_STR("preformatted string")`:: Preformatted string verbose logging statement. @@ -575,7 +593,7 @@ Follow those steps to make your module loggable: */ #define BT_LOG_OUTPUT_LEVEL my_module_log_level -#include +#include BT_LOG_INIT_LOG_LEVEL(my_module_log_level, "BABELTRACE_MY_MODULE_LOG_LEVEL"); ---- @@ -595,8 +613,8 @@ the environment variable and sets the log level symbol accordingly. -- [source,c] ---- -#ifndef MY_MODULE_LOGGING_H -#define MY_MODULE_LOGGING_H +#ifndef BABELTRACE_MY_MODULE_LOGGING_H +#define BABELTRACE_MY_MODULE_LOGGING_H /* * Copyright (c) 2017 EfficiOS Inc. @@ -621,11 +639,11 @@ the environment variable and sets the log level symbol accordingly. */ #define BT_LOG_OUTPUT_LEVEL my_module_log_level -#include +#include BT_LOG_LEVEL_EXTERN_SYMBOL(my_module_log_level); -#endif /* MY_MODULE_LOGGING_H */ +#endif /* BABELTRACE_MY_MODULE_LOGGING_H */ ---- -- + @@ -635,6 +653,9 @@ log level symbol. . Include the `logging.c` and `logging.h` in the `_SOURCES` variable of your module's object in your module's root `Makefile.am`. +. Add the log level initializing environment variable name to the + `log_level_env_var_names` array in `cli/babeltrace2.c`. + [[logging-instrument-source]] ==== Instrument a C source file