X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=CONTRIBUTING.adoc;h=268c4445ae4e8b3f33db45a8a2654e2c20edd17d;hb=0326ed809346c1e128674436d89c78ac43ddba4f;hp=32f5363432f613ab34f000aef8acebd8afb15a25;hpb=ff7ea753d4069f125953d690df066c5b8c83e4c2;p=babeltrace.git diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 32f53634..268c4445 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) @@ -1497,7 +1491,7 @@ tests to run in, so nothing more is needed. If building in-tree, you can run single tests from the tree directly: ---- -$ ./tests/plugins/sink.text.pretty/test_enum +$ ./tests/plugins/sink.text.pretty/test-enum.sh ---- If building out-of-tree, you can get the appropriate environment by sourcing @@ -1506,15 +1500,16 @@ want to run tests. ---- $ source /path/to/my/build/tests/utils/env.sh -$ ./tests/plugins/sink.text.pretty/test_enum +$ ./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-python-bt2.sh` 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 +`run-python-bt2.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: @@ -1523,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-python-bt2.sh`, for example: ---- -$ ./tests/utils/run_python_bt2 ipython3 +$ ./tests/utils/run-python-bt2.sh ipython3 ---- === Report format @@ -1572,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-python-bt2.sh ./tests/bindings/python/bt2/test-python-bt2.sh ---- + or: + ---- -$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \ +$ ./tests/utils/run-python-bt2.sh python3 ./tests/utils/python/testrunner.py \ ./tests/bindings/python/bt2/ -p '*.py' ---- @@ -1588,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-python-bt2.sh python3 ./tests/utils/python/testrunner.py \ ./tests/bindings/python/bt2 -t test_value ---- @@ -1598,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-python-bt2.sh python3 ./tests/utils/python/testrunner.py \ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase ---- @@ -1608,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-python-bt2.sh python3 ./tests/utils/python/testrunner.py \ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int ---- @@ -1680,19 +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}13 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: ---- -$ ./tools/format-cpp +$ ./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='clang-format-10 -i' ./tools/format-cpp +$ FORMATTER='my-clang-format-15 -i' ./tools/format-cpp.sh ---- ==== Naming @@ -1954,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`.