X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=CONTRIBUTING.adoc;h=81e964f04311c335a4887d9a0f35f17e4040ccc4;hp=416c4bfe42a6f23fc23b5686aaf1f0e8764676f5;hb=15b4e74c9d44271d73a58a1783dd13ecd19c6ef6;hpb=dd22a91fdf79ad39dedb83449b905e7659212b45 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 416c4bfe..81e964f0 100644 --- 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: @@ -619,59 +631,63 @@ The available format specifiers are: |`F` |Trace IR field class -|`+struct bt_field_class *+` +|`+const struct bt_field_class *+` |`f` |Trace IR field -|`+struct bt_field *+` +|`+const struct bt_field *+` |`P` |Trace IR field path -|`+struct bt_field_path *+` +|`+const struct bt_field_path *+` |`E` |Trace IR event class -|`+struct bt_event_class *+` +|`+const struct bt_event_class *+` |`e` |Trace IR event -|`+struct bt_event *+` +|`+const struct bt_event *+` |`S` |Trace IR stream class. -|`+struct bt_stream_class *+` +|`+const struct bt_stream_class *+` |`s` |Trace IR stream -|`+struct bt_stream *+` +|`+const struct bt_stream *+` |`a` |Trace IR packet -|`+struct bt_packet *+` +|`+const struct bt_packet *+` |`T` |Trace IR trace class -|`+struct bt_trace_class *+` +|`+const struct bt_trace_class *+` |`t` |Trace IR trace -|`+struct bt_trace *+` +|`+const struct bt_trace *+` |`K` |Trace IR clock class -|`+struct bt_clock_class *+` +|`+const struct bt_clock_class *+` |`k` |Trace IR clock snapshot -|`+struct bt_clock_snapshot *+` +|`+const struct bt_clock_snapshot *+` |`v` |Value object -|`+struct bt_value *+` +|`+const struct bt_value *+` + +|`R` +|Integer range set +|`const struct bt_integer_range_set *` |`n` |Message -|`+struct bt_message *+` +|`+const struct bt_message *+` |`i` |Message iterator @@ -683,31 +699,35 @@ The available format specifiers are: |`c` |Component -|`+struct bt_component *+` +|`+const struct bt_component *+` |`p` |Port -|`+struct bt_port *+` +|`+const struct bt_port *+` |`x` |Connection -|`+struct bt_connection *+` +|`+const struct bt_connection *+` |`g` |Graph -|`+struct bt_graph *+` +|`+const struct bt_graph *+` |`l` |Plugin -|`const struct bt_plugin *` +|`+const struct bt_plugin *+` + +|`r` +|Error cause +|`+const struct bt_error_cause *+` |`o` |Object pool -|`+struct bt_object_pool *+` +|`+const struct bt_object_pool *+` |`O` |Object -|`+struct bt_object *+` +|`+const struct bt_object *+` |=== Conversion specifier examples: @@ -863,7 +883,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 +905,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 +1272,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 +1297,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 +1371,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 +1460,7 @@ name and line number, and the <>. 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 +1497,136 @@ 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 + +[[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 <> 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 +----