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 setup build 13 cd build 14 ninja 15 meson 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.57 or later 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 49It is best advised to go over the following links for the complete dependencies: 50 51* :doc:`Linux <../linux_gsg/sys_reqs>` 52* :doc:`FreeBSD <../freebsd_gsg/build_dpdk>` 53* :doc:`Windows <../windows_gsg/build_dpdk>` 54 55 56Configuring the Build 57---------------------- 58 59To configure a build, run the meson tool, passing the path to the directory 60to be used for the build e.g. ``meson setup build``, as shown above. If calling 61meson from somewhere other than the root directory of the DPDK project the 62path to the root directory should be passed as the first parameter, and the 63build path as the second. For example, to build DPDK in /tmp/dpdk-build:: 64 65 user@host:/tmp$ meson setup ~user/dpdk dpdk-build 66 67Meson will then configure the build based on settings in the project's 68meson.build files, and by checking the build environment for e.g. compiler 69properties or the presence of dependencies, such as libpcap, or openssl 70libcrypto libraries. Once done, meson writes a ``build.ninja`` file in the 71build directory to be used to do the build itself when ninja is called. 72 73Tuning of the build is possible, both as part of the original meson call, 74or subsequently using ``meson configure`` command (``mesonconf`` in some 75older versions). Some options, such as ``buildtype``, or ``werror`` are 76built into meson, while others, such as ``max_lcores``, or the list of 77examples to build, are DPDK-specific. To have a list of all options 78available run ``meson configure`` in the build directory. 79 80Examples of adjusting the defaults when doing initial meson configuration. 81Project-specific options are passed used -Doption=value:: 82 83 # build with warnings as errors 84 meson setup --werror werrorbuild 85 86 # build for debugging 87 meson setup --buildtype=debug debugbuild 88 89 # build some examples as part of the normal DPDK build 90 meson setup -Dexamples=l3fwd,l2fwd fwdbuild 91 92 # scale build for smaller systems 93 meson setup -Dmax_lcores=8 smallbuild 94 95 # build and install docs 96 meson setup -Denable_docs=true fullbuild 97 98 # use builder-independent baseline -march 99 meson setup -Dcpu_instruction_set=generic 100 101 # disable tap driver and all eventdev PMDs for a smaller build 102 meson setup -Ddisable_drivers=event/*,net/tap 103 104 # build with fast path traces enabled 105 meson setup -Denable_trace_fp=true tracebuild 106 107Examples of setting some of the same options using meson configure:: 108 109 meson configure -Dwerror=true 110 111 meson configure -Dbuildtype=debug 112 113 meson configure -Dexamples=l3fwd,l2fwd 114 115 meson configure -Dmax_lcores=8 116 117 meson configure -Denable_trace_fp=true 118 119.. note:: 120 121 once meson has been run to configure a build in a directory, it 122 cannot be run again on the same directory. Instead ``meson configure`` 123 should be used to change the build settings within the directory, and when 124 ``ninja`` is called to do the build itself, it will trigger the necessary 125 re-scan from meson. 126 127.. note:: 128 129 cpu_instruction_set=generic uses an instruction set that works on 130 all supported architectures regardless of the capabilities of the machine 131 where the build is happening. 132 133.. note:: 134 135 cpu_instruction_set is not used in Arm builds, as setting the instruction set 136 without other parameters leads to inferior builds. 137 The way to tailor Arm builds is to build for a SoC using -Dplatform=<SoC>. 138 139As well as those settings taken from ``meson configure``, other options 140such as the compiler to use can be passed via environment variables. For 141example:: 142 143 CC=clang meson setup clang-build 144 145.. note:: 146 147 for more comprehensive overriding of compilers or other environment 148 settings, the tools for cross-compilation may be considered. However, for 149 basic overriding of the compiler etc., the above form works as expected. 150 151 152Performing the Build 153--------------------- 154 155Use ``ninja`` to perform the actual build inside the build folder 156previously configured. In most cases no arguments are necessary. 157 158Ninja accepts a number of flags which are similar to make. For example, to 159call ninja from outside the build folder, you can use ``ninja -C build``. 160Ninja also runs parallel builds by default, but you can limit this using 161the ``-j`` flag, e.g. ``ninja -j1 -v`` to do the build one step at a time, 162printing each command on a new line as it runs. 163 164 165Installing the Compiled Files 166------------------------------ 167 168Use ``meson install`` to install the required DPDK files onto the system. 169The install prefix defaults to ``/usr/local`` but can be used as with other 170options above. The environment variable ``DESTDIR`` can be used to adjust 171the root directory for the install, for example when packaging. 172 173With the base install directory, the individual directories for libraries 174and headers are configurable. By default, the following will be the 175installed layout:: 176 177 headers -> /usr/local/include 178 libraries -> /usr/local/lib64 179 drivers -> /usr/local/lib64/dpdk/drivers 180 libdpdk.pc -> /usr/local/lib64/pkgconfig 181 182For the drivers, these will also be symbolically linked into the library 183install directory, so that ld.so can find them in cases where one driver may 184depend on another, e.g. a NIC PMD depending upon the PCI bus driver. Within 185the EAL, the default search path for drivers will be set to the configured 186driver install path, so dynamically-linked applications can be run without 187having to pass in ``-d /path/to/driver`` options for standard drivers. 188 189 190Cross Compiling DPDK 191-------------------- 192 193To cross-compile DPDK on a desired target machine we can use the following 194command:: 195 196 meson setup cross-build --cross-file <target_machine_configuration> 197 198For example if the target machine is arm64 we can use the following 199command:: 200 201 meson setup arm-build --cross-file config/arm/arm64_armv8_linux_gcc 202 203where config/arm/arm64_armv8_linux_gcc contains settings for the compilers 204and other build tools to be used, as well as characteristics of the target 205machine. 206 207Using the DPDK within an Application 208------------------------------------- 209 210To compile and link against DPDK within an application, pkg-config should 211be used to query the correct parameters. Examples of this are given in the 212makefiles for the example applications included with DPDK. They demonstrate 213how to link either against the DPDK shared libraries, or against the static 214versions of the same. 215 216From examples/helloworld/Makefile:: 217 218 PC_FILE := $(shell pkg-config --path libdpdk) 219 CFLAGS += -O3 $(shell pkg-config --cflags libdpdk) 220 LDFLAGS_SHARED = $(shell pkg-config --libs libdpdk) 221 LDFLAGS_STATIC = $(shell pkg-config --static --libs libdpdk) 222 223 build/$(APP)-shared: $(SRCS-y) Makefile $(PC_FILE) | build 224 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_SHARED) 225 226 build/$(APP)-static: $(SRCS-y) Makefile $(PC_FILE) | build 227 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_STATIC) 228 229 build: 230 @mkdir -p $@ 231