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

[Aaron Conole]

Thomas Monjalon <thomas at monjalon.net> writes:

> Hi please find some comments below:
>
> 06/06/2019 13:59, Hari Kumar Vemula:
>> +++ b/doc/guides/prog_guide/meson_ut.rst
>> @@ -0,0 +1,151 @@
>> +..  SPDX-License-Identifier: BSD-3-Clause
>> +
>
> Useless blank line.
>
>> +    Copyright(c) 2018-2019 Intel Corporation.
>> +
>> +.. _meson_unit_tests:
>
> Useless anchor. The doc can be referenced with :doc: links.
>
>> +
>> +Running DPDK Unit Tests with Meson
>> +==================================
>> +
>> +This section describes how to run testcases with the DPDK meson build system.
>
> Here and below, "testcases" should be split in two words.
>
>> +
>> +
>> +Building and running the unit tests
>> +-----------------------------------
>> +
>> +* Create the meson build output folder using the following command::
>> +
>> +      $ meson <build_dir>
>> +
>> +* Enter into build output folder, which was created by above command::
>> +
>> +      $ cd build
>
> Should be the same as above: <build_dir>
>
>> +
>> +* Compile DPDK using command::
>> +
>> +      $ ninja
>
> Do we really need to repeat above basic steps?
> Would be easier to just reference another guide about meson.
> I think doc/build-sdk-meson.txt should be moved to .rst.

+1

>> +
>> +The output file of the build will be available in meson build folder. After
>> +a successful ninja command, the binary ``dpdk-test`` is created in
>> +``build/test/test/``.
>
> Again, "build" is an example directory.
>
>> +
>> +* Run the unit testcases::
>> +
>> +      $ ninja test
>> +      # or
>> +      $ meson test
>> +
>> +* To run specific test case via meson::
>> +
>> +      $ meson test <test case>
>> +      # or
>> +      $ ninja test <test case>
>
> Would be worth to mention why meson or ninja can be used.
>
>> +
>> +
>> +Grouping of testcases
>> +---------------------
>> +
>> +Testcases have been grouped into four different groups based on conditions
>> +of time duration and performance of the individual testcase.
>
> Grouping has changed recently.
> This part should be updated please.
>
>> +
>> +* 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``.
>> +
>> +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
>> +
>> +
>> +Running different test suites
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +The following commands are some examples of how to run testcases using option
>> +``--suite``:

The following section is a bit misleading.  The limitation on run time
is per-test.  So 600 seconds in perf-tests is 600 seconds PER TEST.  IE:
if there are 10 tests, you'll be waiting up to 50 minutes.

>> +* Fast Tests should take less than 10 seconds. The meson command to run them
>> +  is::
>> +
>> +      $ meson test --suite DPDK:fast-tests
>> +
>> +* Performance Tests should take less than 600 seconds. The meson command to
>> +  run them is::
>> +
>> +      $ meson test --suite DPDK:perf-tests
>> +
>> +* Driver Tests should take less than 600 seconds. The meson command to run
>> +  them is::
>> +
>> +      $ meson test --suite DPDK:driver-tests
>> +
>> +* The meson command to run Dump Tests is::
>> +
>> +      $ meson test --suite DPDK:dump-tests
>
> Would be simpler to just list the suites.

Even better would be to provide a 1-liner that would dump the suites so
that new test suites wouldn't need to update the documentation.

>> +
>> +
>> +Dealing with 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 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.
>> +
>> +To help find missing libraries, the user can specify addition search paths
>
> addition -> additional ?
>
>> +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
>
> Some quotes are missing to set multiple paths.
>
>> +
>> +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
>
> Why export is used for LIBRARY_PATH and not CFLAGS?
> I think both variables can be exported or prepend the meson command?