[v8] doc: add meson ut info in prog guide
Checks
Commit Message
From: Hari Kumar Vemula <hari.kumarx.vemula@intel.com>
Add a programmer's guide section for meson ut
Signed-off-by: Hari Kumar Vemula <hari.kumarx.vemula@intel.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Michael Santana <msantana@redhat.com>
---
v8: Addressed v7 patch comments
v7: Updated v6 patch comments
v6: Updated comments
v5: Modified
v4: Typos corrected
v3: Modified
v2: Removed enhancement details
---
.../prog_guide/build-sdk-meson.rst} | 7 +-
doc/guides/prog_guide/index.rst | 2 +
doc/guides/prog_guide/meson_ut.rst | 104 ++++++++++++++++++
3 files changed, 110 insertions(+), 3 deletions(-)
rename doc/{build-sdk-meson.txt => guides/prog_guide/build-sdk-meson.rst} (97%)
create mode 100644 doc/guides/prog_guide/meson_ut.rst
Comments
12/08/2019 14:40, Jananee Parthasarathy:
> From: Hari Kumar Vemula <hari.kumarx.vemula@intel.com>
>
> Add a programmer's guide section for meson ut
>
> Signed-off-by: Hari Kumar Vemula <hari.kumarx.vemula@intel.com>
> Acked-by: Bruce Richardson <bruce.richardson@intel.com>
> Acked-by: Michael Santana <msantana@redhat.com>
The last part about enabling some skipped test case is not correct.
Because this patch is very old, I apply it without this last part:
> +To help find missing libraries, the user can specify additional 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 additional 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 are some examples that show how to export libraries and their header
> +paths.
> +
> +To specify a 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=/path/zuc/:/path/libsso_kasumi/build/
> + $ CFLAGS=-I/path/zuc/include \
> + -I/path/libsso_kasumi/include \
> + meson build
similarity index 97%
rename from doc/build-sdk-meson.txt
rename to doc/guides/prog_guide/build-sdk-meson.rst
@@ -1,5 +1,5 @@
-INSTALLING DPDK USING THE MESON BUILD SYSTEM
----------------------------------------------
+Installing DPDK Using the meson build system
+============================================
Summary
--------
@@ -162,7 +162,8 @@ command::
For example if the target machine is arm64 we can use the following
command::
- meson arm-build --cross-file config/arm/arm64_armv8_linux_gcc
+
+ meson arm-build --cross-file config/arm/arm64_armv8_linux_gcc
where config/arm/arm64_armv8_linux_gcc contains settings for the compilers
and other build tools to be used, as well as characteristics of the target
@@ -60,6 +60,8 @@ Programmer's Guide
source_org
dev_kit_build_system
dev_kit_root_make_help
+ build-sdk-meson
+ meson_ut
extend_dpdk
build_app
ext_app_lib_make_help
new file mode 100644
@@ -0,0 +1,104 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2018-2019 Intel Corporation.
+
+Running DPDK Unit Tests with Meson
+==================================
+
+This section describes how to run test cases with the DPDK meson build system.
+
+Steps to build and install DPDK using meson can be referred
+in :doc:`build-sdk-meson`
+
+Grouping of test cases
+----------------------
+
+Test cases have been classified into four different groups.
+
+* Fast tests.
+* Performance tests.
+* Driver tests.
+* Tests which produce lists of objects as output, and therefore that need
+ manual checking.
+
+These tests can be run using the argument to ``meson test`` as
+``--suite project_name:label``.
+
+For example::
+
+ $ meson test -C <build path> --suite DPDK:fast-tests
+
+If the ``<build path>`` is current working directory,
+the ``-C <build path>`` option can be skipped as below::
+
+ $ meson test --suite DPDK:fast-tests
+
+The project name is optional so the following is equivalent to the previous
+command::
+
+ $ meson test --suite fast-tests
+
+The meson command to list all available tests::
+
+ $ meson test --list
+
+Test cases are run serially by default for better stability.
+
+Arguments of ``test()`` that can be provided in meson.build are as below:
+
+* ``is_parallel`` is used to run test case either in parallel or non-parallel mode.
+* ``timeout`` is used to specify the timeout of test case.
+* ``args`` is used to specify test specific parameters.
+* ``env`` is used to specify test specific environment parameters.
+
+
+Dealing with skipped test cases
+-------------------------------
+
+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 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:
+
+#. Optional external libraries are not found.
+#. Config flags for the dependent library are not enabled.
+#. Dependent driver modules are not installed on the system.
+#. Not enough processing cores. Some tests are skipped on machines with 2 or 4 cores.
+
+To help find missing libraries, the user can specify additional 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 additional 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 are some examples that show how to export libraries and their header
+paths.
+
+To specify a 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=/path/zuc/:/path/libsso_kasumi/build/
+ $ CFLAGS=-I/path/zuc/include \
+ -I/path/libsso_kasumi/include \
+ meson build