On Mon, Jul 8, 2019 at 4:18 PM Aaron Conole <acon...@redhat.com> wrote:
>
> Thomas Monjalon <tho...@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?
