[v7] doc: add meson ut info in prog guide

  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>
---
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            | 92 +++++++++++++++++++
 3 files changed, 98 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
  

> -----Original Message-----
> From: dev <dev-bounces@dpdk.org> On Behalf Of Agalya Babu
> RadhaKrishnan
> Sent: Wednesday, August 7, 2019 7:26 PM
> To: dev@dpdk.org
> Cc: reshma.pattan@intel.com; john.mcnamara@intel.com;
> marko.kovacevic@intel.com; bruce.richardson@intel.com;
> jananeex.m.parthasarathy@intel.com; Hari Kumar Vemula
> <hari.kumarx.vemula@intel.com>
> Subject: [dpdk-dev] [PATCH v7] doc: add meson ut info in prog guide
> 
> 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>
> ---
> v7: Updated v6 patch comments
> v6: Updated comments
> v5: Modified
> v4: Typos corrected
> v3: Modified
> v2: Removed enhancement details
> ---
> +
> +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``.
> +
> +For example::
> +
> +    $ 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

I think, It is good mention about the timeout and/or other valid(if any) UT parameter as well.
  

On 8/7/19 9:56 AM, Agalya Babu RadhaKrishnan wrote:
> 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>
> ---
> 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            | 92 +++++++++++++++++++
>   3 files changed, 98 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
>
> diff --git a/doc/build-sdk-meson.txt b/doc/guides/prog_guide/build-sdk-meson.rst
> similarity index 97%
> rename from doc/build-sdk-meson.txt
> rename to doc/guides/prog_guide/build-sdk-meson.rst
> index fc7fe37b5..34c363694 100644
> --- a/doc/build-sdk-meson.txt
> +++ b/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
> diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
> index 692409af8..0bab96c58 100644
> --- a/doc/guides/prog_guide/index.rst
> +++ b/doc/guides/prog_guide/index.rst
> @@ -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
> diff --git a/doc/guides/prog_guide/meson_ut.rst b/doc/guides/prog_guide/meson_ut.rst
> new file mode 100644
> index 000000000..18392ce04
> --- /dev/null
> +++ b/doc/guides/prog_guide/meson_ut.rst
> @@ -0,0 +1,92 @@
> +..  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 run unit test cases using meson can be referred
> +in :doc:`build-sdk-meson`
I think this is misleading. As far as I can see build-sdk-meson doesn't 
provide any details as to how to "run" test cases. I think you meant to 
say build-sdk-meson has the steps to build dpdk, or something among 
those lines
> +
> +Grouping of test cases
> +----------------------
> +
> +Testcases have been grouped into four different groups.

space between Test and cases.

I prefer not having to use the word 'group' twice in the same sentence, 
it just sounds awkward to me. I would do s/different groups/different 
test suites/

> +
> +* Fast tests.
> +* 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

space between Test and cases.

I would also mention that by default all tests run serially for better 
stability

> +of ``test()`` in meson.build
> +
> +These tests can be run using the argument to ``meson test`` as
> +``--suite project_name:label``.
> +
> +For example::
> +
> +    $ meson test --suite DPDK:fast-tests

I would also somehow mention that these examples only work when your 
current working directory is the build directory. If you are not in the 
build directory you need to pass the -C flag, so like:

$ meson test -C <build path> --suite DPDK:fast-tests

the build path can either be a relative path or an absolute path, but I 
would skip this detail

> +
> +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
> +
> +
> +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.

#. Note enough processing cores. Some tests are skipped on machines with 
2 or 4 cores


The rest lgtm

Acked-by: Michael Santana <msantana@redhat.com <mailto:msantana@redhat.com>>

> +
> +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