Add a programmer's guide section for meson ut Signed-off-by: Hari Kumar Vemula --- v2: Removed enhancement details --- doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/meson_ut.rst | 164 +++++++++++++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 doc/guides/prog_guide/meson_ut.rst diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 6726b1e8d..f4274573f 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -58,6 +58,7 @@ Programmer's Guide source_org dev_kit_build_system dev_kit_root_make_help + meson_ut extend_dpdk build_app ext_app_lib_make_help diff --git a/doc/guides/prog_guide/meson_ut.rst b/doc/guides/prog_guide/meson_ut.rst new file mode 100644 index 000000000..ab4adbbe8 --- /dev/null +++ b/doc/guides/prog_guide/meson_ut.rst @@ -0,0 +1,164 @@ +.. SPDX-License-Identifier: BSD-3-Clause + + Copyright(c) 2014-2018 Intel Corporation. + +.. _Meson: + +Meson_UT +======== + +The meson build for unit tests under different categories is supported using 'test/test/meson.build'. + +This document describes the below list in detail. + +* 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 command, 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 on 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