X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=CONTRIBUTING.adoc;h=d166238501f96a65f532fcc9d6bcc34afa93beed;hb=776a2a252c9875caa1e8b4f41cb8cc12c79611c3;hp=62dd8a9d890d0b2e8685bebedd62e1881cc4d88a;hpb=c637d72958fca8c04ca99f5655d11f4b3f77cbf6;p=babeltrace.git diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 62dd8a9d..d1662385 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -8,7 +8,7 @@ v0.2, 19 June 2019 This is a partial contributor's guide for the -http://diamon.org/babeltrace[Babeltrace] project. If you have any +https://babeltrace.org[Babeltrace] project. If you have any questions that are not answered by this guide, please post them on https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[Babeltrace's mailing list]. @@ -295,7 +295,7 @@ hidden symbol which is the library's current log level before including This header offers the <>. -`"plugins/comp-logging.h"`:: +`"logging/comp-logging.h"`:: Specific internal header to use within a component class. + This header offers the <self_comp) ---- -. Include `"plugins/comp-logging.h"`: +. Include `"logging/comp-logging.h"`: + [source,c] ---- -#include "plugins/comp-logging.h" +#include "logging/comp-logging.h" ---- . In the component initialization method, make sure to set the @@ -1165,7 +1193,7 @@ bt_self_component_status my_comp_init( To instrument a component class C header file (`.h`), if you have `static inline` functions in it: -. Do not include `"plugins/comp-logging.h"`! +. Do not include `"logging/comp-logging.h"`! . Require that component logging be enabled: + @@ -1173,7 +1201,7 @@ To instrument a component class C header file (`.h`), if you have ---- /* Protection: this file uses BT_COMP_LOG*() macros directly */ #ifndef BT_COMP_LOG_SUPPORTED -# error Please include "plugins/comp-logging.h" before including this file. +# error Please include "logging/comp-logging.h" before including this file. #endif ---- @@ -1252,8 +1280,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 +1305,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. @@ -1326,7 +1357,7 @@ an _INFO_ build. * Object copying (except fields and values). * Object freezing (whatever the type, as freezing only occurs in developer mode). -* Object cancellation. +* Object interruption. * Calling user methods and logging the result. * Setting object properties (except fields and values). | @@ -1348,7 +1379,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 +1468,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: @@ -1462,8 +1493,7 @@ loads libbabeltrace2, use: ---- $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \ - LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full \ - --suppressions=/path/to/babeltrace/extras/valgrind/popt.supp app + LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full app ---- `G_SLICE=always-malloc` and `G_DEBUG=gc-friendly` is for GLib and @@ -1477,30 +1507,133 @@ backtrace when Valgrind shows errors. == Testing -=== Python Bindings +[[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. -To run all the `bt2` Python package tests use: +`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: ---- -$ BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests \ - ./tests/bindings/python/bt2/test_python_bt2 +$ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests ---- -To run all the tests in a test module (e.g. `test_event.py`) use: +You can run any command which needs the `bt2` Python package through +`run_python_bt2`, for example: ---- -$ 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/ +$ ./tests/utils/run_python_bt2 ipython3 ---- -To run a specific test (e.g. `EventTestCase.test_clock_value`) in a test module -(e.g. `test_event.py`) use: +=== 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: ---- -$ 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/ +$ 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 ----