lib: make BT_ASSERT_{PRE,POST}() always on; add BT_ASSERT_{PRE,POST}_DEV()

[babeltrace.git] / CONTRIBUTING.adoc

diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index 416c4bfe42a6f23fc23b5686aaf1f0e8764676f5..c5fb796862a5b799181c3402cff889cfb2bc52d3 100644 (file)
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -330,10 +330,10 @@ order of severity:
 |`BT_LOG_INFO`
 |`BT_LOGGING_LEVEL_INFO`
 
-|_WARN_
+|_WARNING_
 |`W`
-|`BT_LOG_WARN`
-|`BT_LOGGING_LEVEL_WARN`
+|`BT_LOG_WARNING`
+|`BT_LOGGING_LEVEL_WARNING`
 
 |_ERROR_
 |`E`
@@ -374,13 +374,13 @@ 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
-all the Babeltrace modules. You can't set it to `WARN`, `ERROR`,
+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.
@@ -583,6 +583,18 @@ of `+BT_LOG*()+`:
 `+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:
 
@@ -701,6 +713,10 @@ The available format specifiers are:
 |Plugin
 |`const struct bt_plugin *`
 
+|`r`
+|Error cause
+|`const struct bt_error_cause *`
+
 |`o`
 |Object pool
 |`+struct bt_object_pool *+`
@@ -863,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_WARN`
+* `BT_LOG_ENABLED_WARNING`
 * `BT_LOG_ENABLED_ERROR`
 * `BT_LOG_ENABLED_FATAL`
 
@@ -885,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_WARN`
+* `BT_LOG_ON_WARNING`
 * `BT_LOG_ON_ERROR`
 * `BT_LOG_ON_FATAL`
 
@@ -1252,8 +1268,10 @@ A _FATAL_-level logging statement should always be followed by
 * Logic error in internal code, for example an unexpected value in a
   `switch` statement.
 * Failed assertion (within `BT_ASSERT()`).
-* Unsatisfied library precondition (within `BT_ASSERT_PRE()`).
-* Unsatisfied library postcondition (within `BT_ASSERT_POST()`).
+* Unsatisfied library precondition (within `BT_ASSERT_PRE()` or
+  `BT_ASSERT_PRE_DEV()`).
+* Unsatisfied library postcondition (within `BT_ASSERT_POST()` or
+  `BT_ASSERT_POST_DEV()`).
 |Almost none: always enabled.
 
 |_ERROR_
@@ -1275,16 +1293,17 @@ least exit cleanly.
 * Almost any error in terminal elements: CLI and plugins.
 |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.
 
-_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.
@@ -1348,7 +1367,7 @@ other log levels). More appropriate for tracing in general.
 
 [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.
 
@@ -1437,7 +1456,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
-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:
@@ -1474,3 +1493,33 @@ which originate from the Python interpreter anyway).
 `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.
+
+== 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/
+----