X-Git-Url: https://git.efficios.com/?a=blobdiff_plain;f=CONTRIBUTING.adoc;h=c31f9a89f403e3a4548599ff564ead11ad78f3c8;hb=230ec73afe8bf139f205562225932611d0e4e256;hp=b9f26eb11bb5c626cbb40e5b3dfe380156fad028;hpb=fb7ff115d1c09334777a2cca347555765f3ce172;p=babeltrace.git diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index b9f26eb1..c31f9a89 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -439,7 +439,6 @@ level, for example: + [source,c] ---- -BT_HIDDEN char *bt_common_get_home_plugin_path(int log_level); ---- + @@ -585,10 +584,6 @@ of `+BT_LOG*()+`: 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: @@ -1152,7 +1147,6 @@ struct my_comp { /* ... */ }; -BT_HIDDEN bt_self_component_status my_comp_init( bt_self_component_source *self_comp_src, bt_value *params, void *init_method_data) @@ -1490,34 +1484,32 @@ backtrace when Valgrind shows errors. [[test-env]] === Environment -`tests/utils/utils.sh` sets the environment variables for any {bt2} -test script. +Running `make check` in the build directory (regardless of whether the build is +in-tree or out-of-tree) automatically sets up the appropriate environment for +tests to run in, so nothing more is needed. + +If building in-tree, you can run single tests from the tree directly: -`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. +---- +$ ./tests/plugins/sink.text.pretty/test-enum.sh +---- -All test scripts eventually do something like this to source `utils.sh`, -according to where they are located relative to the `tests` directory: +If building out-of-tree, you can get the appropriate environment by sourcing +the `tests/utils/env.sh` file residing in the build directory against which you +want to run tests. -[source,bash] ---- -if [ "x${BT_TESTS_SRCDIR:-}" != "x" ]; then - UTILSSH="$BT_TESTS_SRCDIR/utils/utils.sh" -else - UTILSSH="$(dirname "$0")/../utils/utils.sh" -fi +$ source /path/to/my/build/tests/utils/env.sh +$ ./tests/plugins/sink.text.pretty/test-enum.sh ---- ==== 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. +You can use the `tests/utils/run-in-py-env.sh` script to run any command +within an environment making the build's `bt2` Python package available, +as well as the testing utility Python modules. -`run_python_bt2` uses <> which needs to know the +`run-in-py-env.sh` 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: @@ -1526,10 +1518,10 @@ $ 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: +`run-in-py-env.sh`, for example: ---- -$ ./tests/utils/run_python_bt2 ipython3 +$ ./tests/utils/run-in-py-env.sh ipython3 ---- === Report format @@ -1575,13 +1567,13 @@ To run all the `bt2` Python package tests: * Run: + ---- -$ ./tests/utils/run_python_bt2 ./tests/bindings/python/bt2/test_python_bt2 +$ ./tests/utils/run-in-py-env.sh ./tests/bindings/python/bt2/test-python-bt2.sh ---- + or: + ---- -$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \ +$ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ ./tests/bindings/python/bt2/ -p '*.py' ---- @@ -1591,7 +1583,7 @@ To run **all the tests** in a test module (for example, * Run: + ---- -$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \ +$ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ ./tests/bindings/python/bt2 -t test_value ---- @@ -1601,7 +1593,7 @@ To run a **specific test case** (for example, `RealValueTestCase` within * Run: + ---- -$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \ +$ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase ---- @@ -1611,7 +1603,7 @@ To run a **specific test** (for example, * Run: + ---- -$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \ +$ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int ---- @@ -1683,13 +1675,25 @@ https://clang.llvm.org/docs/ClangFormatStyleOptions.html[style] of the You _must_ format modified and new {cpp} files with clang-format before you create a contribution patch. -You need clang-format{nbsp}≥{nbsp}10 to use the project's `.clang-format` -file. +You need clang-format{nbsp}15 to use the project's `.clang-format` file. To automatically format all the project's {cpp} files, run: ---- -$ find -iname '*.cpp' -o -iname '*.hpp' -exec clang-format -i '{}' ';' +$ ./tools/format-cpp.sh +---- + +Pass a directory path to only format the {cpp} files it contains: + +---- +$ ./tools/format-cpp.sh ./src/cli +---- + +Use the `FORMATTER` environment variable to override the default +formatter (`clang-format{nbsp}-i`): + +---- +$ FORMATTER='my-clang-format-15 -i' ./tools/format-cpp.sh ---- ==== Naming @@ -1951,3 +1955,13 @@ private: #endif // BABELTRACE_BABY_HPP ---- ==== + +== Python Usage + +=== Formatting + +All Python code must be formatted using the version of +https://github.com/psf/black[Black] specified in `dev-requirements.txt`. + +All Python imports must be sorted using the version of +https://pycqa.github.io/isort/[isort] indicated in `dev-requirements.txt`.