Add a programmer's guide section for meson ut Signed-off-by: Hari Kumar Vemula --- v5: Modified v4: Typos corrected v3: Modified v2: Removed enhancement details --- doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/meson_ut.rst | 143 +++++++++++++++++++++++++++++ 2 files changed, 144 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..e4b449049 --- /dev/null +++ b/doc/guides/prog_guide/meson_ut.rst @@ -0,0 +1,143 @@ +.. SPDX-License-Identifier: BSD-3-Clause + + Copyright(c) 2018-2019 Intel Corporation. + +.. _Meson: + +Meson_UT +======== + +This document describes the below list in detail. + +* Building and Running the unit tests. +* Grouping of testcases. +* 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 command. + + ``$ 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 run specific test case via meson command. + + ``$ meson test `` (or) ``$ ninja test `` + + + +Grouping of testcases +--------------------- + +Testcases have been grouped into four different groups based on conditions +of time duration and performance of the individual testcase. + +* fast tests which can be run in parallel +* fast tests which must run serially +* performance tests +* driver tests +* tests which produce lists of objects as output, and therefore that need manual checking + +Testcases can be run in parallel or non-parallel mode using the `is_parallel` argument +of `test()` in meson.build + +These tests can be run using the argument to `meson test` as +`--suite ‘project_name:label’`. + + Ex: ``$ meson test --suite ‘DPDK:fast-tests’`` + +Running different test suites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Commands to run testcases using option `--suite` + +* Fast Tests should take less than 10 seconds and below is the meson command to run them. + + ``$ meson test --suite DPDK:fast-tests`` + +* Performance Tests should take less than 600 seconds and below is the meson command to run them. + + ``$ meson test --suite DPDK:perf-tests`` + +* Driver Tests should take less than 600 seconds and below is the meson command to run them. + + ``$ meson test --suite DPDK:driver-tests`` + +* Below is the meson command to run Dump Tests + + ``$ meson test --suite DPDK:dump-tests`` + + + +Skipped testcases +----------------- + +Some unit test cases have a dependency on external libraries, driver modules or +config flags, without which the test cases cannot be run. Such test cases will be reported +out as skipped if they cannot run. To enable those test cases, +the user should ensure the required dependencies are met. +Below are a few possible causes why tests may be skipped and how they may be resolved: + +#. External library is not found. +#. Config flag for the dependent library is not enabled. +#. Dependent driver modules are not installed on the system. + +To help find missing libraries, the user can specify addition search paths +for those libraries as below: + +* Single path ``$ export LIBRARY_PATH=path`` + +* Multiple paths ``$ export LIBRARY_PATH=path1:path2:path3`` + +Some functionality may be disabled due to library headers being missed as part of the build. +To specify an addition search path for headers at configuration time, use one of the commands 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 specify single library at a time. + + ``$ export LIBRARY_PATH=/root/wireless_libs/zuc/`` + ``$ CFLAGS=-I/root/wireless_libs/zuc/include meson build`` + +To specify 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`` + + + +Summary +-------- + +* 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