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

["Parthasarathy, JananeeX M" <jananeex.m.parthasarathy@intel.com>]

Hi,

>-----Original Message-----
>From: Michael Santana Francisco [mailto:msantana@redhat.com]
>Sent: Wednesday, July 10, 2019 12:28 AM
>To: Aaron Conole <aconole@redhat.com>
>Cc: Thomas Monjalon <thomas@monjalon.net>; Hari Kumar Vemula
><hari.kumarx.vemula@intel.com>; dev <dev@dpdk.org>; Pattan, Reshma
><reshma.pattan@intel.com>; Mcnamara, John <john.mcnamara@intel.com>;
>Kovacevic, Marko <marko.kovacevic@intel.com>; Parthasarathy, JananeeX M
><jananeex.m.parthasarathy@intel.com>; Richardson, Bruce
><bruce.richardson@intel.com>; David Marchand
><david.marchand@redhat.com>
>Subject: Re: [dpdk-dev] [PATCH v6] doc: add meson ut info in prog guide
>
>On Mon, Jul 8, 2019 at 4:18 PM Aaron Conole <aconole@redhat.com> wrote:
>>
>> Thomas Monjalon <thomas@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.

Will correct it.

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

Will change accordingly.

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

This doc helps to run UT, having basic steps in same page will help user to go through together and execute the same.
Just for few lines moving back and forth to different pages might be bit confusing.
Anyway still if you would prefer to remove these then only 2 sections will be available in this doc.
Please let us know if it is ok.

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

OK
>> >> +
>> >> +
>> >> +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.
	
Thanks for the info. We observed that fast parallel test group is removed. 
Now we have four groups - fast, perf, driver, debug - all in non-parallel mode We will update the same.

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

Will update the same and remove multiple lines.

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

Is <build_dir>  meant here?

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

CFLAGS given in meson command works and  also CFLAGS can be exported.
LIBRARY_PATH  cannot be prepended to meson command. We tried but it is not reflecting the required values.
Environment variables set using export is considered and not as command line args of meson command.


Will send the next version patch addressing these comments.

Thanks
M.P.Jananee