From: Hari Kumar Vemula Date: Mon, 12 Aug 2019 12:40:25 +0000 (+0100) Subject: doc: add a guide to run unit tests with meson X-Git-Url: http://git.droids-corp.org/?a=commitdiff_plain;h=adbeba3639c1f3c2c98e49cfe7ca7939e2166f8a;p=dpdk.git doc: add a guide to run unit tests with meson Add a programmer's guide section for meson ut Signed-off-by: Hari Kumar Vemula Acked-by: Bruce Richardson Acked-by: Michael Santana --- diff --git a/doc/build-sdk-meson.txt b/doc/build-sdk-meson.txt deleted file mode 100644 index 319a19ef6b..0000000000 --- a/doc/build-sdk-meson.txt +++ /dev/null @@ -1,197 +0,0 @@ -INSTALLING DPDK USING THE MESON BUILD SYSTEM ---------------------------------------------- - -Summary --------- -For many platforms, compiling and installing DPDK should work using the -following set of commands:: - - meson build - cd build - ninja - ninja install - -This will compile DPDK in the ``build`` subdirectory, and then install the -resulting libraries, drivers and header files onto the system - generally -in /usr/local. A package-config file, ``libdpdk.pc``, for DPDK will also -be installed to allow ease of compiling and linking with applications. - -After installation, to use DPDK, the necessary CFLAG and LDFLAG variables -can be got from pkg-config:: - - pkg-config --cflags libdpdk - pkg-config --libs libdpdk - -More detail on each of these steps can be got from the following sections. - - -Getting the Tools ------------------- - -The ``meson`` tool is used to configure a DPDK build. On most Linux -distributions this can be got using the local package management system, -e.g. ``dnf install meson`` or ``apt-get install meson``. If meson is not -available as a suitable package, it can also be installed using the Python -3 ``pip`` tool, e.g. ``pip3 install meson``. Version 0.47.1 of meson is -required - if the version packaged is too old, the latest version is -generally available from "pip". - -The other dependency for building is the ``ninja`` tool, which acts similar -to make and performs the actual build using information provided by meson. -Installing meson will, in many cases, also install ninja, but, if not -already installed, it too is generally packaged by most Linux distributions. -If not available as a package, it can be downloaded as source or binary from -https://ninja-build.org/ - - -Configuring the Build ----------------------- - -To configure a build, run the meson tool, passing the path to the directory -to be used for the build e.g. ``meson build``, as shown above. If calling -meson from somewhere other than the root directory of the DPDK project the -path to the root directory should be passed as the first parameter, and the -build path as the second. For example, to build DPDK in /tmp/dpdk-build:: - - user@host:/tmp$ meson ~user/dpdk dpdk-build - -Meson will then configure the build based on settings in the project's -meson.build files, and by checking the build environment for e.g. compiler -properties or the presence of dependencies, such as libpcap, or openssl -libcrypto libraries. Once done, meson writes a ``build.ninja`` file in the -build directory to be used to do the build itself when ninja is called. - -Tuning of the build is possible, both as part of the original meson call, -or subsequently using ``meson configure`` command (``mesonconf`` in some -older versions). Some options, such as ``buildtype``, or ``werror`` are -built into meson, while others, such as ``max_lcores``, or the list of -examples to build, are DPDK-specific. To have a list of all options -available run ``meson configure`` in the build directory. - -Examples of adjusting the defaults when doing initial meson configuration. -Project-specific options are passed used -Doption=value:: - - meson --werror werrorbuild # build with warnings as errors - - meson --buildtype=debug debugbuild # build for debugging - - meson -Dexamples=l3fwd,l2fwd fwdbuild # build some examples as - # part of the normal DPDK build - - meson -Dmax_lcores=8 smallbuild # scale build for smaller systems - - meson -Denable_docs=true fullbuild # build and install docs - - meson -Dmachine=default # use builder-independent baseline -march - - meson -Ddisable_drivers=event/*,net/tap # disable tap driver and all - # eventdev PMDs for a smaller build - -Examples of setting some of the same options using meson configure:: - - meson configure -Dwerror=true - - meson configure -Dbuildtype=debug - - meson configure -Dexamples=l3fwd,l2fwd - - meson configure -Dmax_lcores=8 - -NOTE: once meson has been run to configure a build in a directory, it -cannot be run again on the same directory. Instead ``meson configure`` -should be used to change the build settings within the directory, and when -``ninja`` is called to do the build itself, it will trigger the necessary -re-scan from meson. - -NOTE: machine=default uses a config that works on all supported architectures -regardless of the capabilities of the machine where the build is happening. - -As well as those settings taken from ``meson configure``, other options -such as the compiler to use can be passed via environment variables. For -example:: - - CC=clang meson clang-build - -NOTE: for more comprehensive overriding of compilers or other environment -settings, the tools for cross-compilation may be considered. However, for -basic overriding of the compiler etc., the above form works as expected. - - -Performing the Build ---------------------- - -Use ``ninja`` to perform the actual build inside the build folder -previously configured. In most cases no arguments are necessary. - -Ninja accepts a number of flags which are similar to make. For example, to -call ninja from outside the build folder, you can use ``ninja -C build``. -Ninja also runs parallel builds by default, but you can limit this using -the ``-j`` flag, e.g. ``ninja -j1 -v`` to do the build one step at a time, -printing each command on a new line as it runs. - - -Installing the Compiled Files ------------------------------- - -Use ``ninja install`` to install the required DPDK files onto the system. -The install prefix defaults to ``/usr/local`` but can be used as with other -options above. The environment variable ``DESTDIR`` can be used to adjust -the root directory for the install, for example when packaging. - -With the base install directory, the individual directories for libraries -and headers are configurable. By default, the following will be the -installed layout:: - - headers -> /usr/local/include - libraries -> /usr/local/lib64 - drivers -> /usr/local/lib64/dpdk/drivers - libdpdk.pc -> /usr/local/lib64/pkgconfig - -For the drivers, these will also be symbolically linked into the library -install directory, so that ld.so can find them in cases where one driver may -depend on another, e.g. a NIC PMD depending upon the PCI bus driver. Within -the EAL, the default search path for drivers will be set to the configured -driver install path, so dynamically-linked applications can be run without -having to pass in ``-d /path/to/driver`` options for standard drivers. - - -Cross Compiling DPDK --------------------- - -To cross-compile DPDK on a desired target machine we can use the following -command:: - - meson cross-build --cross-file - -For example if the target machine is arm64 we can use the following -command:: - meson arm-build --cross-file config/arm/arm64_armv8_linux_gcc - -where config/arm/arm64_armv8_linux_gcc contains settings for the compilers -and other build tools to be used, as well as characteristics of the target -machine. - -Using the DPDK within an Application -------------------------------------- - -To compile and link against DPDK within an application, pkg-config should -be used to query the correct parameters. Examples of this are given in the -makefiles for the example applications included with DPDK. They demonstrate -how to link either against the DPDK shared libraries, or against the static -versions of the same. - -From examples/helloworld/Makefile:: - - PC_FILE := $(shell pkg-config --path libdpdk) - CFLAGS += -O3 $(shell pkg-config --cflags libdpdk) - LDFLAGS_SHARED = $(shell pkg-config --libs libdpdk) - LDFLAGS_STATIC = -Wl,-Bstatic $(shell pkg-config --static --libs libdpdk) - - build/$(APP)-shared: $(SRCS-y) Makefile $(PC_FILE) | build - $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_SHARED) - - build/$(APP)-static: $(SRCS-y) Makefile $(PC_FILE) | build - $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_STATIC) - - build: - @mkdir -p $@ diff --git a/doc/guides/prog_guide/build-sdk-meson.rst b/doc/guides/prog_guide/build-sdk-meson.rst new file mode 100644 index 0000000000..e34daab91b --- /dev/null +++ b/doc/guides/prog_guide/build-sdk-meson.rst @@ -0,0 +1,198 @@ +Installing DPDK Using the meson build system +============================================ + +Summary +-------- +For many platforms, compiling and installing DPDK should work using the +following set of commands:: + + meson build + cd build + ninja + ninja install + +This will compile DPDK in the ``build`` subdirectory, and then install the +resulting libraries, drivers and header files onto the system - generally +in /usr/local. A package-config file, ``libdpdk.pc``, for DPDK will also +be installed to allow ease of compiling and linking with applications. + +After installation, to use DPDK, the necessary CFLAG and LDFLAG variables +can be got from pkg-config:: + + pkg-config --cflags libdpdk + pkg-config --libs libdpdk + +More detail on each of these steps can be got from the following sections. + + +Getting the Tools +------------------ + +The ``meson`` tool is used to configure a DPDK build. On most Linux +distributions this can be got using the local package management system, +e.g. ``dnf install meson`` or ``apt-get install meson``. If meson is not +available as a suitable package, it can also be installed using the Python +3 ``pip`` tool, e.g. ``pip3 install meson``. Version 0.47.1 of meson is +required - if the version packaged is too old, the latest version is +generally available from "pip". + +The other dependency for building is the ``ninja`` tool, which acts similar +to make and performs the actual build using information provided by meson. +Installing meson will, in many cases, also install ninja, but, if not +already installed, it too is generally packaged by most Linux distributions. +If not available as a package, it can be downloaded as source or binary from +https://ninja-build.org/ + + +Configuring the Build +---------------------- + +To configure a build, run the meson tool, passing the path to the directory +to be used for the build e.g. ``meson build``, as shown above. If calling +meson from somewhere other than the root directory of the DPDK project the +path to the root directory should be passed as the first parameter, and the +build path as the second. For example, to build DPDK in /tmp/dpdk-build:: + + user@host:/tmp$ meson ~user/dpdk dpdk-build + +Meson will then configure the build based on settings in the project's +meson.build files, and by checking the build environment for e.g. compiler +properties or the presence of dependencies, such as libpcap, or openssl +libcrypto libraries. Once done, meson writes a ``build.ninja`` file in the +build directory to be used to do the build itself when ninja is called. + +Tuning of the build is possible, both as part of the original meson call, +or subsequently using ``meson configure`` command (``mesonconf`` in some +older versions). Some options, such as ``buildtype``, or ``werror`` are +built into meson, while others, such as ``max_lcores``, or the list of +examples to build, are DPDK-specific. To have a list of all options +available run ``meson configure`` in the build directory. + +Examples of adjusting the defaults when doing initial meson configuration. +Project-specific options are passed used -Doption=value:: + + meson --werror werrorbuild # build with warnings as errors + + meson --buildtype=debug debugbuild # build for debugging + + meson -Dexamples=l3fwd,l2fwd fwdbuild # build some examples as + # part of the normal DPDK build + + meson -Dmax_lcores=8 smallbuild # scale build for smaller systems + + meson -Denable_docs=true fullbuild # build and install docs + + meson -Dmachine=default # use builder-independent baseline -march + + meson -Ddisable_drivers=event/*,net/tap # disable tap driver and all + # eventdev PMDs for a smaller build + +Examples of setting some of the same options using meson configure:: + + meson configure -Dwerror=true + + meson configure -Dbuildtype=debug + + meson configure -Dexamples=l3fwd,l2fwd + + meson configure -Dmax_lcores=8 + +NOTE: once meson has been run to configure a build in a directory, it +cannot be run again on the same directory. Instead ``meson configure`` +should be used to change the build settings within the directory, and when +``ninja`` is called to do the build itself, it will trigger the necessary +re-scan from meson. + +NOTE: machine=default uses a config that works on all supported architectures +regardless of the capabilities of the machine where the build is happening. + +As well as those settings taken from ``meson configure``, other options +such as the compiler to use can be passed via environment variables. For +example:: + + CC=clang meson clang-build + +NOTE: for more comprehensive overriding of compilers or other environment +settings, the tools for cross-compilation may be considered. However, for +basic overriding of the compiler etc., the above form works as expected. + + +Performing the Build +--------------------- + +Use ``ninja`` to perform the actual build inside the build folder +previously configured. In most cases no arguments are necessary. + +Ninja accepts a number of flags which are similar to make. For example, to +call ninja from outside the build folder, you can use ``ninja -C build``. +Ninja also runs parallel builds by default, but you can limit this using +the ``-j`` flag, e.g. ``ninja -j1 -v`` to do the build one step at a time, +printing each command on a new line as it runs. + + +Installing the Compiled Files +------------------------------ + +Use ``ninja install`` to install the required DPDK files onto the system. +The install prefix defaults to ``/usr/local`` but can be used as with other +options above. The environment variable ``DESTDIR`` can be used to adjust +the root directory for the install, for example when packaging. + +With the base install directory, the individual directories for libraries +and headers are configurable. By default, the following will be the +installed layout:: + + headers -> /usr/local/include + libraries -> /usr/local/lib64 + drivers -> /usr/local/lib64/dpdk/drivers + libdpdk.pc -> /usr/local/lib64/pkgconfig + +For the drivers, these will also be symbolically linked into the library +install directory, so that ld.so can find them in cases where one driver may +depend on another, e.g. a NIC PMD depending upon the PCI bus driver. Within +the EAL, the default search path for drivers will be set to the configured +driver install path, so dynamically-linked applications can be run without +having to pass in ``-d /path/to/driver`` options for standard drivers. + + +Cross Compiling DPDK +-------------------- + +To cross-compile DPDK on a desired target machine we can use the following +command:: + + meson cross-build --cross-file + +For example if the target machine is arm64 we can use the following +command:: + + meson arm-build --cross-file config/arm/arm64_armv8_linux_gcc + +where config/arm/arm64_armv8_linux_gcc contains settings for the compilers +and other build tools to be used, as well as characteristics of the target +machine. + +Using the DPDK within an Application +------------------------------------- + +To compile and link against DPDK within an application, pkg-config should +be used to query the correct parameters. Examples of this are given in the +makefiles for the example applications included with DPDK. They demonstrate +how to link either against the DPDK shared libraries, or against the static +versions of the same. + +From examples/helloworld/Makefile:: + + PC_FILE := $(shell pkg-config --path libdpdk) + CFLAGS += -O3 $(shell pkg-config --cflags libdpdk) + LDFLAGS_SHARED = $(shell pkg-config --libs libdpdk) + LDFLAGS_STATIC = -Wl,-Bstatic $(shell pkg-config --static --libs libdpdk) + + build/$(APP)-shared: $(SRCS-y) Makefile $(PC_FILE) | build + $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_SHARED) + + build/$(APP)-static: $(SRCS-y) Makefile $(PC_FILE) | build + $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_STATIC) + + build: + @mkdir -p $@ diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index dc4851c57f..fb250abf51 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -60,6 +60,8 @@ Programmer's Guide source_org dev_kit_build_system dev_kit_root_make_help + build-sdk-meson + 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 0000000000..fff88655dd --- /dev/null +++ b/doc/guides/prog_guide/meson_ut.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018-2019 Intel Corporation. + +Running DPDK Unit Tests with Meson +================================== + +This section describes how to run test cases with the DPDK meson build system. + +Steps to build and install DPDK using meson can be referred +in :doc:`build-sdk-meson` + +Grouping of test cases +---------------------- + +Test cases have been classified into four different groups. + +* Fast tests. +* Performance tests. +* Driver tests. +* Tests which produce lists of objects as output, and therefore that need + manual checking. + +These tests can be run using the argument to ``meson test`` as +``--suite project_name:label``. + +For example:: + + $ meson test -C --suite DPDK:fast-tests + +If the ```` is current working directory, +the ``-C `` option can be skipped as below:: + + $ 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 + +The meson command to list all available tests:: + + $ meson test --list + +Test cases are run serially by default for better stability. + +Arguments of ``test()`` that can be provided in meson.build are as below: + +* ``is_parallel`` is used to run test case either in parallel or non-parallel mode. +* ``timeout`` is used to specify the timeout of test case. +* ``args`` is used to specify test specific parameters. +* ``env`` is used to specify test specific environment parameters. + + +Dealing with skipped test cases +------------------------------- + +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: + +#. Optional external libraries are not found. +#. Config flags for the dependent library are not enabled. +#. Dependent driver modules are not installed on the system. +#. Not enough processing cores. Some tests are skipped on machines with 2 or 4 cores.