[v3] doc: add meson ut info in prog guide
Checks
Commit Message
Add a programmer's guide section for meson ut
Signed-off-by: Hari Kumar Vemula <hari.kumarx.vemula@intel.com>
---
v3: Modified
v2: Removed enhancement details
---
doc/guides/prog_guide/index.rst | 1 +
doc/guides/prog_guide/meson_ut.rst | 159 +++++++++++++++++++++++++++++
2 files changed, 160 insertions(+)
create mode 100644 doc/guides/prog_guide/meson_ut.rst
Comments
> -----Original Message-----
> From: Vemula, Hari KumarX
> Sent: Thursday, January 24, 2019 1:42 PM
> To: dev@dpdk.org
> Cc: Mcnamara, John <john.mcnamara@intel.com>; Pattan, Reshma
> <reshma.pattan@intel.com>; Richardson, Bruce <bruce.richardson@intel.com>;
> Kovacevic, Marko <marko.kovacevic@intel.com>; Parthasarathy, JananeeX M
> <jananeex.m.parthasarathy@intel.com>; Vemula, Hari KumarX
> <hari.kumarx.vemula@intel.com>
> Subject: [PATCH v3] doc: add meson ut info in prog guide
>
> Add a programmer's guide section for meson ut
>
> Signed-off-by: Hari Kumar Vemula <hari.kumarx.vemula@intel.com>
> ---
> v3: Modified
> v2: Removed enhancement details
> ---
Some typos and suggested reworking below.
/Bruce
<snip>
> +
> +
> +Test suites
> +~~~~~~~~~~~
> +
> +Test groups are considered as `--suite` in `meson.build` and can be
"Tests are grouped into test suites in meson.build and these suite names can be"
> +provided as argument to `test()` as `--suite ‘project_name:label’`.
"test()" => "meson test"
> +
> + Ex: ``$ mesin test --suite ‘DPDK:fast-tests’``
mesin => meson
<snip>
@@ -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
new file mode 100644
@@ -0,0 +1,159 @@
+.. 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 <build_dir>``
+
+* 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 run specific test case via meson command.
+
+ ``$ meson test <test case>`` (or) ``$ ninja test <test case>``
+
+
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, meson will run test cases in parallel. However `is_parallel` argument
+of `test()` in meson.build can be used to run tests in parallel or non-parallel
+mode based on its functionality. 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, no other test should 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: ``$ mesin test --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 stated as part of meson build command 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 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``
+
+
+
+Summery of 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``