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