Re: [dpdk-dev] [PATCH v2] doc: add meson ut info in prog guide

[Bruce Richardson <bruce.richardson@intel.com>]

On Wed, Jan 23, 2019 at 06:37:07AM +0000, Hari Kumar Vemula wrote:
> Add a programmer's guide section for meson ut
> 
> Signed-off-by: Hari Kumar Vemula <hari.kumarx.vemula@intel.com>
> ---
> 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 <build_dir>``

Here and with the commands below, leave a space between the '$' and the
command to show that it's the prompt and not the variable '$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``
> +

This should not be necesary. If you make any changes to meson.build then
ninja will automatically detect that and call meson to reconfigure itself
automatically.

Also, I don't think the rebuilding of the software is within the scope of
the section of the document. I'd omit the whole bullet point.

> +*   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
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Unless specified the meson will run all unit tests as parallel by default.

"meson" rather than "the meson" sounds better. Comma needed after
"specified". I'd also look to shorten the next sentence and merge it with
the one above, which sounds incomplete.

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

"any other test should not be run" -> "no other tests 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: ``suite ???DPDK:fast-tests???``

Watch out for the use of smart-quotes in the text above. Regular single and
double quotes are recommended.

When passing a suite to the meson to run, you use "--suite", so please
include the "--" prefix to avoid confusion.

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

Break the sentence after "run".

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

Please be consistent with use of "export" or not. Also, consistently (or
not) using "$" for prompt would be good too.

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

I'd suggest adding "Summary" into the title here - "Summary of Commands ..."

> +*   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
>
Regards,
/Bruce