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

Message ID 1559822385-21684-1-git-send-email-hari.kumarx.vemula@intel.com
State Changes Requested, archived
Delegated to: Thomas Monjalon
Headers show
Series
  • [v6] doc: add meson ut info in prog guide
Related show

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK

Commit Message

Hari Kumar Vemula June 6, 2019, 11:59 a.m.
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>
---
v6: Updated comments
v5: Modified
v4: Typos corrected
v3: Modified
v2: Removed enhancement details
---
 doc/guides/prog_guide/index.rst    |   1 +
 doc/guides/prog_guide/meson_ut.rst | 151 +++++++++++++++++++++++++++++++++++++
 2 files changed, 152 insertions(+)
 create mode 100644 doc/guides/prog_guide/meson_ut.rst

Comments

Thomas Monjalon July 8, 2019, 7:40 p.m. | #1
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.

> +
> +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``:
> +
> +* 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.

> +
> +
> +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?
Aaron Conole July 8, 2019, 8:18 p.m. | #2
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.
>
>> +
>> +
>> +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?
Michael Santana July 9, 2019, 6:57 p.m. | #3
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.
> >
> >> +
> >> +
> >> +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?
Jananee Parthasarathy July 22, 2019, 12:39 p.m. | #4
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
Thomas Monjalon July 22, 2019, 12:53 p.m. | #5
22/07/2019 14:39, Parthasarathy, JananeeX M:
>From: Michael Santana Francisco [mailto:msantana@redhat.com]
> >On Mon, Jul 8, 2019 at 4:18 PM Aaron Conole <aconole@redhat.com> wrote:
> >> Thomas Monjalon <thomas@monjalon.net> writes:
> >> >> +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.

I think it is better to avoid repetition.


> >> >> +*  Multiple paths::
> >> >> +
> >> >> +       $ CFLAGS=-I/path1 -I/path2 meson build
> >> >
> >> > Some quotes are missing to set multiple paths.
> 
> Is <build_dir>  meant here?

I am just saying that space-separated value require some quotes.

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

Please we need to understand why LIBRARY_PATH is not working
when preprended in the meson command.
Do you have more informations?
Bruce Richardson July 22, 2019, 1:53 p.m. | #6
On Mon, Jul 22, 2019 at 02:53:34PM +0200, Thomas Monjalon wrote:
> 22/07/2019 14:39, Parthasarathy, JananeeX M:
> >From: Michael Santana Francisco [mailto:msantana@redhat.com]
> > >On Mon, Jul 8, 2019 at 4:18 PM Aaron Conole <aconole@redhat.com> wrote:
> > >> Thomas Monjalon <thomas@monjalon.net> writes:
> > >> >> +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.
> 
> I think it is better to avoid repetition.
> 
> 
> > >> >> +*  Multiple paths::
> > >> >> +
> > >> >> +       $ CFLAGS=-I/path1 -I/path2 meson build
> > >> >
> > >> > Some quotes are missing to set multiple paths.
> > 
> > Is <build_dir>  meant here?
> 
> I am just saying that space-separated value require some quotes.
> 
> > >> >> +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.
> 
> Please we need to understand why LIBRARY_PATH is not working
> when preprended in the meson command.
> Do you have more informations?
>

Rather than using the environment, one can also use "-Dc_args='...'
-Dc_link_args='...'" when calling meson.

Otherwise, I agree with Thomas, we should find out why the LIBRARY_PATH
doesn't work when passed in directly. I'm not aware of any reason it
shouldn't work.

/Bruce
Jananee Parthasarathy July 23, 2019, 11:34 a.m. | #7
Hi,

>-----Original Message-----
>From: Bruce Richardson [mailto:bruce.richardson@intel.com]
>Sent: Monday, July 22, 2019 7:23 PM
>To: Thomas Monjalon <thomas@monjalon.net>
>Cc: Parthasarathy, JananeeX M <jananeex.m.parthasarathy@intel.com>;
>dev@dpdk.org; Michael Santana Francisco <msantana@redhat.com>; Aaron
>Conole <aconole@redhat.com>; Hari Kumar Vemula
><hari.kumarx.vemula@intel.com>; Pattan, Reshma
><reshma.pattan@intel.com>; Mcnamara, John <john.mcnamara@intel.com>;
>Kovacevic, Marko <marko.kovacevic@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 22, 2019 at 02:53:34PM +0200, Thomas Monjalon wrote:
>> 22/07/2019 14:39, Parthasarathy, JananeeX M:
>> >From: Michael Santana Francisco [mailto:msantana@redhat.com]
>> > >On Mon, Jul 8, 2019 at 4:18 PM Aaron Conole <aconole@redhat.com>
>wrote:
>> > >> Thomas Monjalon <thomas@monjalon.net> writes:
>> > >> >> +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.
>>
>> I think it is better to avoid repetition.
>>
>>
>> > >> >> +*  Multiple paths::
>> > >> >> +
>> > >> >> +       $ CFLAGS=-I/path1 -I/path2 meson build
>> > >> >
>> > >> > Some quotes are missing to set multiple paths.
>> >
>> > Is <build_dir>  meant here?
>>
>> I am just saying that space-separated value require some quotes.
>>
>> > >> >> +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.
>>
>> Please we need to understand why LIBRARY_PATH is not working when
>> preprended in the meson command.
>> Do you have more informations?
>>
>
>Rather than using the environment, one can also use "-Dc_args='...'
>-Dc_link_args='...'" when calling meson.
>
>Otherwise, I agree with Thomas, we should find out why the LIBRARY_PATH
>doesn't work when passed in directly. I'm not aware of any reason it shouldn't
>work.
>
>/Bruce

As per our earlier analysis,  

LDFLAGS was not supported earlier in meson command.

find_library() is used to check whether the external dependency library exists or not in order to configure the build.
This function uses the standard system path to check existence of library, or else LIBRARY_PATH can be used as environment variable for custom paths.
LIBRARY_PATH is not supported directly (not a build configure option).

Only recently we can observe that LDFLAGS support is included in meson and linker options can be provided using LDFLAGS.
$ CFLAGS=-fsomething LDFLAGS=-Wl,--linker-flag meson <options>

Although LDFLAGS can be used and build configuration gets updated in LINK_ARGS,

'dependencies' option of static_library and shared_library() should be an object which is return value from dependency()/find_library().
Due to use of find_library() currently, we need to set the environment variable.

Regards
M.P.Jananee

Patch

diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index 692409af8..9465bc8e6 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -60,6 +60,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..e0aa15389
--- /dev/null
+++ b/doc/guides/prog_guide/meson_ut.rst
@@ -0,0 +1,151 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+
+    Copyright(c) 2018-2019 Intel Corporation.
+
+.. _meson_unit_tests:
+
+Running DPDK Unit Tests with Meson
+==================================
+
+This section describes how to run testcases with the DPDK meson build system.
+
+
+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
+
+* Compile DPDK using command::
+
+      $ ninja
+
+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/``.
+
+* 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>
+
+
+Grouping of testcases
+---------------------
+
+Testcases have been grouped into four different groups based on conditions
+of time duration and performance of the individual testcase.
+
+* 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``:
+
+* 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
+
+
+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
+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