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

[Michael Santana Francisco]

On Mon, Jul 8, 2019 at 4:18 PM Aaron Conole <aconole at redhat.com> wrote:
>
> 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.
Worth mentioning that you can run `meson test --list` to see a list of
all available tests
>
> >> +
> >> +
> >> +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?