lib: rename `bt_*_labels_by_value` -> `bt_*_labels_for_value`

[babeltrace.git] / CONTRIBUTING.adoc

diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index f821e7c8631d16a819a98b3315a1c7b5d4eda4f6..066382a480d2f8addc5160eb68a76d016770bb3a 100644 (file)
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -330,10 +330,10 @@ order of severity:
 |`BT_LOG_INFO`
 |`BT_LOGGING_LEVEL_INFO`
 
 |`BT_LOG_INFO`
 |`BT_LOGGING_LEVEL_INFO`
 

-|_WARN_
+|_WARNING_

 |`W`
 |`W`

-|`BT_LOG_WARN`
-|`BT_LOGGING_LEVEL_WARN`
+|`BT_LOG_WARNING`
+|`BT_LOGGING_LEVEL_WARNING`

 
 |_ERROR_
 |`E`
 
 |_ERROR_
 |`E`


@@ -374,13 +374,16 @@ You can set this level at configuration time with the
 +
 --
 ----
 +
 --
 ----

-$ BABELTRACE_MINIMAL_LOG_LEVEL=WARN ./configure
+$ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./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 `WARNING`, `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.


@@ -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 *+`


@@ -860,7 +879,7 @@ The available definitions for build-time conditions are:
 * `BT_LOG_ENABLED_TRACE`
 * `BT_LOG_ENABLED_DEBUG`
 * `BT_LOG_ENABLED_INFO`
 * `BT_LOG_ENABLED_TRACE`
 * `BT_LOG_ENABLED_DEBUG`
 * `BT_LOG_ENABLED_INFO`

-* `BT_LOG_ENABLED_WARN`
+* `BT_LOG_ENABLED_WARNING`

 * `BT_LOG_ENABLED_ERROR`
 * `BT_LOG_ENABLED_FATAL`
 
 * `BT_LOG_ENABLED_ERROR`
 * `BT_LOG_ENABLED_FATAL`
 


@@ -882,7 +901,7 @@ The available definitions for run-time conditions are:
 * `BT_LOG_ON_TRACE`
 * `BT_LOG_ON_DEBUG`
 * `BT_LOG_ON_INFO`
 * `BT_LOG_ON_TRACE`
 * `BT_LOG_ON_DEBUG`
 * `BT_LOG_ON_INFO`

-* `BT_LOG_ON_WARN`
+* `BT_LOG_ON_WARNING`

 * `BT_LOG_ON_ERROR`
 * `BT_LOG_ON_FATAL`
 
 * `BT_LOG_ON_ERROR`
 * `BT_LOG_ON_FATAL`
 


@@ -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,23 +1289,24 @@ 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_
+|_WARNING_

 |
 An error which still allows the execution to continue, but you judge
 that it should be reported to the user.
 
 |
 An error which still allows the execution to continue, but you judge
 that it should be reported to the user.
 

-_WARN_-level logging statements are for any error or weird action that
-is directly or indirectly caused by the user, often through some bad
-input data. For example, not having enough memory is considered beyond
-the user's control, so we always log memory errors with an _ERROR_ level
-(not _FATAL_ because we usually don't abort in this condition).
+_WARNING_-level logging statements are for any error or weird action
+that is directly or indirectly caused by the user, often through some
+bad input data. For example, not having enough memory is considered
+beyond the user's control, so we always log memory errors with an
+_ERROR_ level (not _FATAL_ because we usually don't abort in this
+condition).

 |
 * 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 +1326,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_
 |


@@ -1345,7 +1365,7 @@ other log levels). More appropriate for tracing in general.
 
 [IMPORTANT]
 --
 
 [IMPORTANT]
 --

-Make sure not to use a _WARN_ (or higher) log level when the
+Make sure not to use a _WARNING_ (or higher) log level when the

 condition leading to the logging statement can occur under normal
 circumstances.
 
 condition leading to the logging statement can occur under normal
 circumstances.
 


@@ -1434,7 +1454,7 @@ name and line number, and the <<message,message>>.
 When Babeltrace supports terminal color codes (depends on the
 `BABELTRACE_TERM_COLOR` environment variable's value and what the
 standard output and error streams are plugged into), _INFO_-level lines
 When Babeltrace supports terminal color codes (depends on the
 `BABELTRACE_TERM_COLOR` environment variable's value and what the
 standard output and error streams are plugged into), _INFO_-level lines

-are blue, _WARN_-level lines are yellow, and _ERROR_-level and
+are blue, _WARNING_-level lines are yellow, and _ERROR_-level and

 _FATAL_-level lines are red.
 
 Log line example:
 _FATAL_-level lines are red.
 
 Log line example:


@@ -1459,7 +1479,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 +1488,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/
+----