1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2018 Intel Corporation. 3 4Installing DPDK Using the meson build system 5============================================ 6 7Summary 8-------- 9For many platforms, compiling and installing DPDK should work using the 10following set of commands:: 11 12 meson build 13 cd build 14 ninja 15 ninja install 16 17This will compile DPDK in the ``build`` subdirectory, and then install the 18resulting libraries, drivers and header files onto the system - generally 19in /usr/local. A package-config file, ``libdpdk.pc``, for DPDK will also 20be installed to allow ease of compiling and linking with applications. 21 22After installation, to use DPDK, the necessary CFLAG and LDFLAG variables 23can be got from pkg-config:: 24 25 pkg-config --cflags libdpdk 26 pkg-config --libs libdpdk 27 28More detail on each of these steps can be got from the following sections. 29 30 31Getting the Tools 32------------------ 33 34The ``meson`` tool is used to configure a DPDK build. On most Linux 35distributions this can be got using the local package management system, 36e.g. ``dnf install meson`` or ``apt-get install meson``. If meson is not 37available as a suitable package, it can also be installed using the Python 383 ``pip`` tool, e.g. ``pip3 install meson``. Version 0.47.1 of meson is 39required - if the version packaged is too old, the latest version is 40generally available from "pip". 41 42The other dependency for building is the ``ninja`` tool, which acts similar 43to make and performs the actual build using information provided by meson. 44Installing meson will, in many cases, also install ninja, but, if not 45already installed, it too is generally packaged by most Linux distributions. 46If not available as a package, it can be downloaded as source or binary from 47https://ninja-build.org/ 48 49 50Configuring the Build 51---------------------- 52 53To configure a build, run the meson tool, passing the path to the directory 54to be used for the build e.g. ``meson build``, as shown above. If calling 55meson from somewhere other than the root directory of the DPDK project the 56path to the root directory should be passed as the first parameter, and the 57build path as the second. For example, to build DPDK in /tmp/dpdk-build:: 58 59 user@host:/tmp$ meson ~user/dpdk dpdk-build 60 61Meson will then configure the build based on settings in the project's 62meson.build files, and by checking the build environment for e.g. compiler 63properties or the presence of dependencies, such as libpcap, or openssl 64libcrypto libraries. Once done, meson writes a ``build.ninja`` file in the 65build directory to be used to do the build itself when ninja is called. 66 67Tuning of the build is possible, both as part of the original meson call, 68or subsequently using ``meson configure`` command (``mesonconf`` in some 69older versions). Some options, such as ``buildtype``, or ``werror`` are 70built into meson, while others, such as ``max_lcores``, or the list of 71examples to build, are DPDK-specific. To have a list of all options 72available run ``meson configure`` in the build directory. 73 74Examples of adjusting the defaults when doing initial meson configuration. 75Project-specific options are passed used -Doption=value:: 76 77 meson --werror werrorbuild # build with warnings as errors 78 79 meson --buildtype=debug debugbuild # build for debugging 80 81 meson -Dexamples=l3fwd,l2fwd fwdbuild # build some examples as 82 # part of the normal DPDK build 83 84 meson -Dmax_lcores=8 smallbuild # scale build for smaller systems 85 86 meson -Denable_docs=true fullbuild # build and install docs 87 88 meson -Dmachine=default # use builder-independent baseline -march 89 90 meson -Ddisable_drivers=event/*,net/tap # disable tap driver and all 91 # eventdev PMDs for a smaller build 92 93 meson -Denable_trace_fp=true tracebuild # build with fast path traces 94 # enabled 95 96Examples of setting some of the same options using meson configure:: 97 98 meson configure -Dwerror=true 99 100 meson configure -Dbuildtype=debug 101 102 meson configure -Dexamples=l3fwd,l2fwd 103 104 meson configure -Dmax_lcores=8 105 106 meson configure -Denable_trace_fp=true 107 108.. note:: 109 110 once meson has been run to configure a build in a directory, it 111 cannot be run again on the same directory. Instead ``meson configure`` 112 should be used to change the build settings within the directory, and when 113 ``ninja`` is called to do the build itself, it will trigger the necessary 114 re-scan from meson. 115 116.. note:: 117 machine=default uses a config that works on all supported architectures 118 regardless of the capabilities of the machine where the build is happening. 119 120As well as those settings taken from ``meson configure``, other options 121such as the compiler to use can be passed via environment variables. For 122example:: 123 124 CC=clang meson clang-build 125 126.. note:: 127 128 for more comprehensive overriding of compilers or other environment 129 settings, the tools for cross-compilation may be considered. However, for 130 basic overriding of the compiler etc., the above form works as expected. 131 132 133Performing the Build 134--------------------- 135 136Use ``ninja`` to perform the actual build inside the build folder 137previously configured. In most cases no arguments are necessary. 138 139Ninja accepts a number of flags which are similar to make. For example, to 140call ninja from outside the build folder, you can use ``ninja -C build``. 141Ninja also runs parallel builds by default, but you can limit this using 142the ``-j`` flag, e.g. ``ninja -j1 -v`` to do the build one step at a time, 143printing each command on a new line as it runs. 144 145 146Installing the Compiled Files 147------------------------------ 148 149Use ``ninja install`` to install the required DPDK files onto the system. 150The install prefix defaults to ``/usr/local`` but can be used as with other 151options above. The environment variable ``DESTDIR`` can be used to adjust 152the root directory for the install, for example when packaging. 153 154With the base install directory, the individual directories for libraries 155and headers are configurable. By default, the following will be the 156installed layout:: 157 158 headers -> /usr/local/include 159 libraries -> /usr/local/lib64 160 drivers -> /usr/local/lib64/dpdk/drivers 161 libdpdk.pc -> /usr/local/lib64/pkgconfig 162 163For the drivers, these will also be symbolically linked into the library 164install directory, so that ld.so can find them in cases where one driver may 165depend on another, e.g. a NIC PMD depending upon the PCI bus driver. Within 166the EAL, the default search path for drivers will be set to the configured 167driver install path, so dynamically-linked applications can be run without 168having to pass in ``-d /path/to/driver`` options for standard drivers. 169 170 171Cross Compiling DPDK 172-------------------- 173 174To cross-compile DPDK on a desired target machine we can use the following 175command:: 176 177 meson cross-build --cross-file <target_machine_configuration> 178 179For example if the target machine is arm64 we can use the following 180command:: 181 182 meson arm-build --cross-file config/arm/arm64_armv8_linux_gcc 183 184where config/arm/arm64_armv8_linux_gcc contains settings for the compilers 185and other build tools to be used, as well as characteristics of the target 186machine. 187 188Using the DPDK within an Application 189------------------------------------- 190 191To compile and link against DPDK within an application, pkg-config should 192be used to query the correct parameters. Examples of this are given in the 193makefiles for the example applications included with DPDK. They demonstrate 194how to link either against the DPDK shared libraries, or against the static 195versions of the same. 196 197From examples/helloworld/Makefile:: 198 199 PC_FILE := $(shell pkg-config --path libdpdk) 200 CFLAGS += -O3 $(shell pkg-config --cflags libdpdk) 201 LDFLAGS_SHARED = $(shell pkg-config --libs libdpdk) 202 LDFLAGS_STATIC = $(shell pkg-config --static --libs libdpdk) 203 204 build/$(APP)-shared: $(SRCS-y) Makefile $(PC_FILE) | build 205 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_SHARED) 206 207 build/$(APP)-static: $(SRCS-y) Makefile $(PC_FILE) | build 208 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_STATIC) 209 210 build: 211 @mkdir -p $@ 212