Add a programmer's guide section for meson ut enhancements Signed-off-by: Hari Kumar Vemula --- doc/guides/prog_guide/index.rst | 1 + .../prog_guide/meson_ut_enhancements.rst | 158 ++++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 doc/guides/prog_guide/meson_ut_enhancements.rst diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index ba8c1f6ad..41971e1cf 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -57,6 +57,7 @@ Programmer's Guide source_org dev_kit_build_system dev_kit_root_make_help + meson_ut_enhancements extend_dpdk build_app ext_app_lib_make_help diff --git a/doc/guides/prog_guide/meson_ut_enhancements.rst b/doc/guides/prog_guide/meson_ut_enhancements.rst new file mode 100644 index 000000000..328adda28 --- /dev/null +++ b/doc/guides/prog_guide/meson_ut_enhancements.rst @@ -0,0 +1,158 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2014-2018 Intel Corporation. + +.. _Meson_UT_Enhancements: + +Meson_UT_Enhancements +===================== + +The meson build support for unit tests is now available and the more enhancements are done to the build system +to classify unit tests under different categories. The build `test/test/meson.build` file has been +modified for these enhancements. This document will further down describe the below list. + +* Building and Running the unit tests. +* Grouping of testcases. +* Parallel and non parallel tests. +* Test suites. +* How to run different test suites. +* Support for skipped tests. + + +Building and Running the unit tests +----------------------------------- + +* Create the meson build output folder using command. + + ``$meson `` + +* Enter into build output folder, which was created by above command. + + ``$cd build`` + +* Compile DPDK using `$ninja`. + The output file of the build will be available in meson build folder. + After successful ninja, binary `dpdk-test` is created in `build/test/test/`. + +* Run the unit testcases. + + ``$ninja test`` (or) ``$meson test`` + +* To rebuild the build directory, after any changes to meson.build. + + ``$meson configure`` + +* To run specific test case via meson command. + + ``$meson test `` (or) ``$ninja test `` + + +Grouping of testcases +--------------------- + +Testcases has been grouped into below four different groups based on conditions +of time duration and performance of the individual testcase. + +* fast_parallel_test_names +* fast_non_parallel_test_names +* perf_test_names +* driver_test_names +* dump_test_names + +Parallel and non parallel tests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unless specified the meson will run all unit tests as parallel by default. +So the test cases are categorized into parallel and non parallel tests purely +based test case functionality using `is_parallel` argument of `test()` +in meson.build. Test cases marked with `is_parallel : true` will run in +parallel and tests marked with `is_parallel : false` will run in non-parallel. +While non-parallel test is running, any other test should not be run. +Parallel and non parallel test cases are grouped under the +`fast_parallel_test_names` and `fast_non_parallel_test_names`. + +Test suites +~~~~~~~~~~~ + +Test groups are considered as "suite” in `meson.build` and can be provided +as argument to `test()` as `suite ‘project_name:label’` + + Ex: ``suite ‘DPDK:fast-tests’`` + +Running different test suites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Below are commands to run testcases using option `suite` + +* Test cases from the groups `fast_parallel_test_names` and `fast_non_parallel_test_names` + are run under 10seconds and below is the meson command to run them. + + ``$meson test --suite DPDK:fast-tests`` + +* Test cases from the group `perf_test_names` are run under 600 seconds + and below is the meson command to run them. + + ``$meson test --suite DPDK:perf-tests`` + +* Test cases from the group `driver_test_names` are run under 600 seconds + and below is the meson command to run them. + + ``$meson test --suite DPDK:driver-tests`` + +* Test cases from the group `dump_test_names` are run under 600 seconds + and below is the meson command to run them. + + ``$meson test --suite DPDK:dump-tests`` + + +Skipped testcases +----------------- + +Some unit test cases have dependency on external libraries, driver modules or +config flags, without which the test cases cannot be run, such test cases +should return TEST_SKIPPED when mentioned dependencies are not enabled. To make +test cases run user should enable relevant dependencies. Below are the few +current scenarios when test cases are skipped: + +#. External library dependency paths are not set. +#. Config flag for the dependent library is not enabled. +#. Dependent driver modules are not installed on the system. + +Dependent library paths can be set using below + +* Single path ``export LIBRARY_PATH=path`` + +* Multiple paths ``export LIBRARY_PATH=path1:path2:path3`` + +Dependent library headers path can be exported as below. + +* Single path ``$CFLAGS=-I/path meson build`` + +* Multiple paths ``$CFLAGS=-I/path1 -I/path2 meson build`` + +Below examples shows how to export libraries and their header paths. + +To export single library at a time. + + ``$export LIBRARY_PATH=/root/wireless_libs/zuc/`` + ``$CFLAGS=-I/root/wireless_libs/zuc/include meson build`` + +To export multiple libraries at a time. + + ``$export LIBRARY_PATH=/root/wireless_libs/zuc/:/root/wireless_libs/`` \ + ``libsso_kasumi/build/`` + ``$CFLAGS=-I/root/wireless_libs/zuc/include -I/root/wireless_libs/`` \ + ``libsso_kasumi/include meson build`` + + + +Commands to run meson UTs +------------------------- + +* To run all test cases + ``$meson test`` +* To run specific test + ``$meson test testcase_name`` + Ex:``$meson test acl_autotest`` +* To run specific test suite + ``$meson test --suite DPDK:suite_name`` + Ex:``$meson test --suite DPDK:fast-tests`` -- 2.17.2