|`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`
+
--
----
-$ 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.
+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.
`+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:
|Plugin
|`const struct bt_plugin *`
+|`r`
+|Error cause
+|`const struct bt_error_cause *`
+
|`o`
|Object pool
|`+struct bt_object_pool *+`
* `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_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`
* 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()`).
-|Almost none: should be executed in production.
+* 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_
|
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.
-_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.
-|Almost none: can be executed in production.
+|Almost none: always enabled.
|_INFO_
|
* 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_
|
[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.
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:
----
$ 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
----
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.
+
+== Testing
+
+[[test-env]]
+=== Environment
+
+`tests/utils/utils.sh` sets the environment variables for any Babeltrace
+test script.
+
+`utils.sh` only needs to know the path to the `tests` directory within
+the source and the build directories. By default, `utils.sh` assumes the
+build is in tree, that is, you ran `./configure` from the source's root
+directory, and sets the `BT_TESTS_SRCDIR` and `BT_TESTS_BUILDDIR`
+environment variables accordingly. You can override those variables, for
+example if you build out of tree.
+
+All test scripts eventually do something like this to source `utils.sh`,
+according to where they are located relative to the `tests` directory:
+
+[source,bash]
+----
+if [ "x${BT_TESTS_SRCDIR:-}" != "x" ]; then
+ UTILSSH="$BT_TESTS_SRCDIR/utils/utils.sh"
+else
+ UTILSSH="$(dirname "$0")/../utils/utils.sh"
+fi
+----
+
+==== Python
+
+You can use the `tests/utils/run_python_bt2` script to run any command
+within an environment making the build's `bt2` Python package available.
+
+`run_python_bt2` uses <<test-env,`utils.sh`>> which needs to know the
+build directory, so make sure you set the `BT_TESTS_BUILDDIR`
+environment variable correctly _if you build out of tree_, for example:
+
+----
+$ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests
+----
+
+You can run any command which needs the `bt2` Python package through
+`run_python_bt2`, for example:
+
+----
+$ ./tests/utils/run_python_bt2 ipython3
+----
+
+=== Report format
+
+All test scripts output the test results following the
+https://testanything.org/[Test Anything Protocol] (TAP) format.
+
+The TAP format has two mechanisms to print additional information about
+a test:
+
+* Print a line starting with `#` to the standard output.
++
+This is usually done with the `diag()` C function or the `diag` shell
+function.
+
+* Print to the standard error.
+
+
+=== Python bindings
+
+The `bt2` Python package tests are located in
+`tests/bindings/python/bt2`.
+
+
+==== Python test runner
+
+`tests/utils/python/testrunner.py` is Babeltrace's Python test runner
+which loads Python files containing unit tests, finds all the test
+cases, and runs the tests, producing a TAP report.
+
+You can see the test runner command's help with:
+
+----
+$ python3 ./tests/utils/python/testrunner.py --help
+----
+
+By default, the test runner reports failing tests (TAP's `not{nbsp}ok`
+line), but continues to run other tests. You can use the `--failfast`
+option to make the test runner fail as soon as a test fails.
+
+
+==== Guides
+
+To run all the `bt2` Python package tests:
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 ./tests/bindings/python/bt2/test_python_bt2
+----
++
+or:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2/ -p '*.py'
+----
+
+To run **all the tests** in a test module (for example,
+`test_value.py`):
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2 -t test_value
+----
+
+To run a **specific test case** (for example, `RealValueTestCase` within
+`test_value.py`):
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase
+----
+
+To run a **specific test** (for example,
+`RealValueTestCase.test_assign_pos_int` within `test_value.py`):
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int
+----