fix: Add missing glib include on MINGW

[babeltrace.git] / CONTRIBUTING.adoc

diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index e81d42b7cb76d50ad1f61bc71cf7c78986903a70..3489e0e1f5b32e472a3b9e24ce6e4792b2a5a573 100644 (file)
--- 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
 
 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
 
 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
 == 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 \
 
     $ 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).
 
 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.
 
 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:
 
 
 The logging API headers are:
 

-`<babeltrace/logging.h>`::
+`<babeltrace2/logging.h>`::

     Public header which a library user can use to control and read
     Public header which a library user can use to control and read

-    libbabeltrace's current log level.
+    libbabeltrace2's current log level.

 
 

-`<babeltrace/logging-internal.h>`::
+`<logging/log.h>`::

     Internal, generic logging API which you can use in any Babeltrace
     subproject. This is the translation of `zf_log.h`.
 
     Internal, generic logging API which you can use in any Babeltrace
     subproject. This is the translation of `zf_log.h`.
 

-`<babeltrace/lib-logging-internal.h>`::
+`<lib/lib-logging.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
     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

-    `<babeltrace/logging-internal.h>`.
+    `<logging/log.h>`.

 
 

-Do not include `<babeltrace/logging-internal.h>` or
-`<babeltrace/lib-logging-internal.h>` in a header which contains logging
+Do not include `<logging/log.h>` or
+`<lib/lib-logging.h>` in a header which contains logging

 statements: this header could be included in source files which define a
 different <<choose-a-tag,tag>>, for example. See
 <<logging-instrument-header, Instrument a C header file>>.
 statements: this header could be included in source files which define a
 different <<choose-a-tag,tag>>, for example. See
 <<logging-instrument-header, Instrument a C header file>>.


@@ -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
 `_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

-`<babeltrace/logging-internal.h>`. In the library,
-`<babeltrace/lib-logging-internal.h>` does this job: just include this
+`<logging/log.h>`. In the library,
+`<lib/lib-logging.h>` does this job: just include this

 header which defines `BT_LOG_OUTPUT_LEVEL` to the appropriate symbol
 header which defines `BT_LOG_OUTPUT_LEVEL` to the appropriate symbol

-before it includes `<babeltrace/logging-internal.h>`. In plugins, for
+before it includes `<logging/log.h>`. In plugins, for

 example, there is one log level per component class, which makes log
 filtering easier during execution.
 +
 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:
 +
 --
 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_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.
 
 `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
  */
 
 #define BT_LOG_OUTPUT_LEVEL my_module_log_level

-#include <babeltrace/logging-internal.h>
+#include "logging/log.h"

 
 BT_LOG_INIT_LOG_LEVEL(my_module_log_level, "BABELTRACE_MY_MODULE_LOG_LEVEL");
 ----
 
 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]
 ----
 --
 [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. <http://efficios.com/>
 
 /*
  * Copyright (c) 2017 EfficiOS Inc. <http://efficios.com/>


@@ -621,11 +639,11 @@ the environment variable and sets the log level symbol accordingly.
  */
 
 #define BT_LOG_OUTPUT_LEVEL my_module_log_level
  */
 
 #define BT_LOG_OUTPUT_LEVEL my_module_log_level

-#include <babeltrace/logging-internal.h>
+#include "logging/log.h"

 
 BT_LOG_LEVEL_EXTERN_SYMBOL(my_module_log_level);
 
 
 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`.
 
 . 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
 
 [[logging-instrument-source]]
 ==== Instrument a C source file