fix: test_trimmer on macOs and Solaris

[babeltrace.git] / CONTRIBUTING.adoc

diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index c800b70e21837bee74b3af45a5531f95e742610b..d9ddf815e4b858ec522e53fbf6d2aff46146d74c 100644 (file)
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -246,7 +246,7 @@ can find the cause of a bug faster.
 
 While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to
 _FATAL_ logging statements, you should liberally instrument your
 
 While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to
 _FATAL_ logging statements, you should liberally instrument your

-Babeltrace module with _VERBOSE_ logging statements to help future you
+Babeltrace module with _TRACE_ logging statements to help future you

 and other developers understand what's happening at run time.
 
 
 and other developers understand what's happening at run time.
 
 


@@ -315,10 +315,10 @@ order of severity:
 |Internal API enumerator
 |Public API enumerator
 
 |Internal API enumerator
 |Public API enumerator
 

-|_VERBOSE_
-|`V`
-|`BT_LOG_VERBOSE`
-|`BT_LOGGING_LEVEL_VERBOSE`
+|_TRACE_
+|`T`
+|`BT_LOG_TRACE`
+|`BT_LOGGING_LEVEL_TRACE`

 
 |_DEBUG_
 |`D`
 
 |_DEBUG_
 |`D`


@@ -380,7 +380,10 @@ $ BABELTRACE_MINIMAL_LOG_LEVEL=WARN ./configure
 +
 The default build-time log level is `DEBUG`. For optimal performance,
 set it to `INFO`, which effectively disables all fast path logging in
 +
 The default build-time log level is `DEBUG`. For optimal performance,
 set it to `INFO`, which effectively disables all fast path logging in

-all the Babeltrace modules.
+all the Babeltrace modules. You can't set it to `WARN`, `ERROR`,
+`FATAL`, or `NONE` because the impact on performance is minuscule
+starting from the _INFO_ log level anyway and we want any Babeltrace
+build to always be able to print _INFO_-level logs.

 +
 The library's public API provides `bt_logging_get_minimal_level()` to
 get the configured minimal log level.
 +
 The library's public API provides `bt_logging_get_minimal_level()` to
 get the configured minimal log level.


@@ -475,8 +478,8 @@ See <<logging-instrument-c-file-gen,Instrument a C source file
 (generic)>> and <<logging-instrument-h-file-gen,Instrument a C header
 file (generic)>> to learn how to be able to use the following macros.
 
 (generic)>> and <<logging-instrument-h-file-gen,Instrument a C header
 file (generic)>> to learn how to be able to use the following macros.
 

-`+BT_LOGV("format string", ...)+`::
-    Generic verbose logging statement.
+`+BT_LOGT("format string", ...)+`::
+    Generic trace logging statement.

 
 `+BT_LOGD("format string", ...)+`::
     Generic debug logging statement.
 
 `+BT_LOGD("format string", ...)+`::
     Generic debug logging statement.


@@ -493,8 +496,8 @@ file (generic)>> to learn how to be able to use the following macros.
 `+BT_LOGF("format string", ...)+`::
     Generic fatal logging statement.
 
 `+BT_LOGF("format string", ...)+`::
     Generic fatal logging statement.
 

-`+BT_LOGV_STR("preformatted string")+`::
-    Generic preformatted string verbose logging statement.
+`+BT_LOGT_STR("preformatted string")+`::
+    Generic preformatted string trace logging statement.

 
 `+BT_LOGD_STR("preformatted string")+`::
     Generic preformatted string debug logging statement.
 
 `+BT_LOGD_STR("preformatted string")+`::
     Generic preformatted string debug logging statement.


@@ -511,8 +514,8 @@ file (generic)>> to learn how to be able to use the following macros.
 `+BT_LOGF_STR("preformatted string")+`::
     Generic preformatted string fatal logging statement.
 
 `+BT_LOGF_STR("preformatted string")+`::
     Generic preformatted string fatal logging statement.
 

-`+BT_LOGV_MEM(data_ptr, data_size, "format string", ...)+`::
-    Generic memory verbose logging statement.
+`+BT_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
+    Generic memory trace logging statement.

 
 `+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
     Generic memory debug logging statement.
 
 `+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
     Generic memory debug logging statement.


@@ -529,8 +532,8 @@ file (generic)>> to learn how to be able to use the following macros.
 `+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
     Generic memory fatal logging statement.
 
 `+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
     Generic memory fatal logging statement.
 

-`+BT_LOGV_ERRNO("initial message", "format string", ...)+`::
-       Generic `errno` string verbose logging statement.
+`+BT_LOGT_ERRNO("initial message", "format string", ...)+`::
+       Generic `errno` string trace logging statement.

 
 `+BT_LOGD_ERRNO("initial message", "format string", ...)+`::
        Generic `errno` string debug logging statement.
 
 `+BT_LOGD_ERRNO("initial message", "format string", ...)+`::
        Generic `errno` string debug logging statement.


@@ -562,8 +565,8 @@ learn how to be able to use the following macros.
 The library logging statement macros are named `+BT_LIB_LOG*()+` instead
 of `+BT_LOG*()+`:
 
 The library logging statement macros are named `+BT_LIB_LOG*()+` instead
 of `+BT_LOG*()+`:
 

-`+BT_LIB_LOGV("format string", ...)+`::
-    Library verbose logging statement.
+`+BT_LIB_LOGT("format string", ...)+`::
+    Library trace logging statement.

 
 `+BT_LIB_LOGD("format string", ...)+`::
     Library debug logging statement.
 
 `+BT_LIB_LOGD("format string", ...)+`::
     Library debug logging statement.


@@ -580,6 +583,18 @@ of `+BT_LOG*()+`:
 `+BT_LIB_LOGF("format string", ...)+`::
     Library fatal logging statement.
 
 `+BT_LIB_LOGF("format string", ...)+`::
     Library fatal logging statement.
 

+`+BT_LIB_LOGW_APPEND_CAUSE("format string", ...)+`::
+    Library warning logging statement, and unconditional error cause
+    appending.
+
+`+BT_LIB_LOGE_APPEND_CAUSE("format string", ...)+`::
+    Library error logging statement, and unconditional error cause
+    appending.
+
+`+BT_LIB_LOGF_APPEND_CAUSE("format string", ...)+`::
+    Library fatal logging statement, and unconditional error cause
+    appending.
+

 The macros above accept the typical `printf()` conversion specifiers
 with the following limitations:
 
 The macros above accept the typical `printf()` conversion specifiers
 with the following limitations:
 


@@ -698,6 +713,10 @@ The available format specifiers are:
 |Plugin
 |`const struct bt_plugin *`
 
 |Plugin
 |`const struct bt_plugin *`
 

+|`r`
+|Error cause
+|`const struct bt_error_cause *`
+

 |`o`
 |Object pool
 |`+struct bt_object_pool *+`
 |`o`
 |Object pool
 |`+struct bt_object_pool *+`


@@ -753,8 +772,8 @@ following macros.
 The component logging statement macros are named `+BT_COMP_LOG*()+`
 instead of `+BT_LOG*()+`:
 
 The component logging statement macros are named `+BT_COMP_LOG*()+`
 instead of `+BT_LOG*()+`:
 

-`+BT_COMP_LOGV("format string", ...)+`::
-    Component verbose logging statement.
+`+BT_COMP_LOGT("format string", ...)+`::
+    Component trace logging statement.

 
 `+BT_COMP_LOGD("format string", ...)+`::
     Component debug logging statement.
 
 `+BT_COMP_LOGD("format string", ...)+`::
     Component debug logging statement.


@@ -771,8 +790,8 @@ instead of `+BT_LOG*()+`:
 `+BT_COMP_LOGF("format string", ...)+`::
     Component fatal logging statement.
 
 `+BT_COMP_LOGF("format string", ...)+`::
     Component fatal logging statement.
 

-`+BT_COMP_LOGV_STR("preformatted string")+`::
-    Component preformatted string verbose logging statement.
+`+BT_COMP_LOGT_STR("preformatted string")+`::
+    Component preformatted string trace logging statement.

 
 `+BT_COMP_LOGD_STR("preformatted string")+`::
     Component preformatted string debug logging statement.
 
 `+BT_COMP_LOGD_STR("preformatted string")+`::
     Component preformatted string debug logging statement.


@@ -789,8 +808,8 @@ instead of `+BT_LOG*()+`:
 `+BT_COMP_LOGF_STR("preformatted string")+`::
     Component preformatted string fatal logging statement.
 
 `+BT_COMP_LOGF_STR("preformatted string")+`::
     Component preformatted string fatal logging statement.
 

-`+BT_COMP_LOGV_ERRNO("initial message", "format string", ...)+`::
-    Component `errno` string verbose logging statement.
+`+BT_COMP_LOGT_ERRNO("initial message", "format string", ...)+`::
+    Component `errno` string trace logging statement.

 
 `+BT_COMP_LOGD_ERRNO("initial message", "format string", ...)+`::
     Component `errno` string debug logging statement.
 
 `+BT_COMP_LOGD_ERRNO("initial message", "format string", ...)+`::
     Component `errno` string debug logging statement.


@@ -807,8 +826,8 @@ instead of `+BT_LOG*()+`:
 `+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`::
     Component `errno` string fatal logging statement.
 
 `+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`::
     Component `errno` string fatal logging statement.
 

-`+BT_COMP_LOGV_MEM(data_ptr, data_size, "format string", ...)+`::
-    Component memory verbose logging statement.
+`+BT_COMP_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
+    Component memory trace logging statement.

 
 `+BT_COMP_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
     Component memory debug logging statement.
 
 `+BT_COMP_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
     Component memory debug logging statement.


@@ -857,7 +876,7 @@ block.
 
 The available definitions for build-time conditions are:
 
 
 The available definitions for build-time conditions are:
 

-* `BT_LOG_ENABLED_VERBOSE`
+* `BT_LOG_ENABLED_TRACE`

 * `BT_LOG_ENABLED_DEBUG`
 * `BT_LOG_ENABLED_INFO`
 * `BT_LOG_ENABLED_WARN`
 * `BT_LOG_ENABLED_DEBUG`
 * `BT_LOG_ENABLED_INFO`
 * `BT_LOG_ENABLED_WARN`


@@ -879,7 +898,7 @@ noticeable impact on performance.
 
 The available definitions for run-time conditions are:
 
 
 The available definitions for run-time conditions are:
 

-* `BT_LOG_ON_VERBOSE`
+* `BT_LOG_ON_TRACE`

 * `BT_LOG_ON_DEBUG`
 * `BT_LOG_ON_INFO`
 * `BT_LOG_ON_WARN`
 * `BT_LOG_ON_DEBUG`
 * `BT_LOG_ON_INFO`
 * `BT_LOG_ON_WARN`


@@ -991,8 +1010,8 @@ int some_function(int x)
 {
     /* ... */
 
 {
     /* ... */
 

-#ifdef BT_LOGV
-    BT_LOGV(...);
+#ifdef BT_LOGT
+    BT_LOGT(...);

 #endif
 
     /* ... */
 #endif
 
     /* ... */


@@ -1250,7 +1269,8 @@ A _FATAL_-level logging statement should always be followed by
   `switch` statement.
 * Failed assertion (within `BT_ASSERT()`).
 * Unsatisfied library precondition (within `BT_ASSERT_PRE()`).
   `switch` statement.
 * Failed assertion (within `BT_ASSERT()`).
 * Unsatisfied library precondition (within `BT_ASSERT_PRE()`).

-|Almost none: should be executed in production.
+* Unsatisfied library postcondition (within `BT_ASSERT_POST()`).
+|Almost none: always enabled.

 
 |_ERROR_
 |
 
 |_ERROR_
 |


@@ -1269,7 +1289,7 @@ least exit cleanly.
   failure to create an empty object (no parameters): most probably
   failed internally because of an allocation error.
 * Almost any error in terminal elements: CLI and plugins.
   failure to create an empty object (no parameters): most probably
   failed internally because of an allocation error.
 * Almost any error in terminal elements: CLI and plugins.

-|Almost none: should be executed in production.
+|Almost none: always enabled.

 
 |_WARN_
 |
 
 |_WARN_
 |


@@ -1285,7 +1305,7 @@ the user's control, so we always log memory errors with an _ERROR_ level
 * Missing data within something that is expected to have it, but there's
   an alternative.
 * Invalid file, but recoverable/fixable.
 * Missing data within something that is expected to have it, but there's
   an alternative.
 * Invalid file, but recoverable/fixable.

-|Almost none: can be executed in production.
+|Almost none: always enabled.

 
 |_INFO_
 |
 
 |_INFO_
 |


@@ -1305,8 +1325,7 @@ level is used for sporadic and one-shot events.
 * An _optional_ subsystem cannot be loaded.
 * An _optional_ field/datum cannot be found.
 |
 * An _optional_ subsystem cannot be loaded.
 * An _optional_ field/datum cannot be found.
 |

-Very little: can be executed in production if _INFO_ level information
-is desired.
+Very little: always enabled.

 
 |_DEBUG_
 |
 
 |_DEBUG_
 |


@@ -1327,11 +1346,11 @@ an _INFO_ build.
 * Calling user methods and logging the result.
 * Setting object properties (except fields and values).
 |
 * Calling user methods and logging the result.
 * Setting object properties (except fields and values).
 |

-Noticeable, but not as much as the _VERBOSE_ level: could be executed
+Noticeable, but not as much as the _TRACE_ level: could be executed

 in production if you're going to need a thorough log for support
 tickets without having to rebuild the project.
 
 in production if you're going to need a thorough log for support
 tickets without having to rebuild the project.
 

-|_VERBOSE_
+|_TRACE_

 |
 Low-level debugging context information (anything that does not fit the
 other log levels). More appropriate for tracing in general.
 |
 Low-level debugging context information (anything that does not fit the
 other log levels). More appropriate for tracing in general.


@@ -1353,7 +1372,7 @@ For example, a public function to get some object or
 property from an object by name or key that fails to find the value is
 not a warning scenario: the user could legitimately use this function to
 check if the name/key exists in the object. In this case, use the
 property from an object by name or key that fails to find the value is
 not a warning scenario: the user could legitimately use this function to
 check if the name/key exists in the object. In this case, use the

-_VERBOSE_ level (or do not log at all).
+_TRACE_ level (or do not log at all).

 --
 
 
 --
 
 


@@ -1459,7 +1478,7 @@ loads libbabeltrace2, use:
 
 ----
 $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \
 
 ----
 $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \

-  BABELTRACE_NO_DLCLOSE=1 valgrind --leak-check=full \
+  LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full \

   --suppressions=/path/to/babeltrace/extras/valgrind/popt.supp app
 ----
 
   --suppressions=/path/to/babeltrace/extras/valgrind/popt.supp app
 ----
 


@@ -1468,6 +1487,36 @@ $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \
 the Python plugin provider (Valgrind will probably show a lot of errors
 which originate from the Python interpreter anyway).
 
 the Python plugin provider (Valgrind will probably show a lot of errors
 which originate from the Python interpreter anyway).
 

-`BABELTRACE_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
+`LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared

 libraries (plugins) which it loads. You need this to see the appropriate
 backtrace when Valgrind shows errors.
 libraries (plugins) which it loads. You need this to see the appropriate
 backtrace when Valgrind shows errors.

+
+== Testing
+
+=== Python Bindings
+
+To run all the `bt2` Python package tests use:
+
+----
+$ BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests \
+       ./tests/bindings/python/bt2/test_python_bt2
+----
+
+To run all the tests in a test module (e.g. `test_event.py`) use:
+
+----
+$ BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests \
+       ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+       -t test_event \
+       ./tests/bindings/python/bt2/
+----
+
+To run a specific test (e.g. `EventTestCase.test_clock_value`) in a test module
+(e.g. `test_event.py`) use:
+
+----
+$ BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests \
+       ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+       -t test_event.EventTestCase.test_clock_value \
+       ./tests/bindings/python/bt2/
+----