1 INSTALLING DPDK USING THE MESON BUILD SYSTEM
2 ---------------------------------------------
6 For many platforms, compiling and installing DPDK should work using the
7 following set of commands::
14 This will compile DPDK in the ``build`` subdirectory, and then install the
15 resulting libraries, drivers and header files onto the system - generally
16 in /usr/local. A package-config file, ``libdpdk.pc``, for DPDK will also
17 be installed to allow ease of compiling and linking with applications.
19 After installation, to use DPDK, the necessary CFLAG and LDFLAG variables
20 can be got from pkg-config::
22 pkg-config --cflags libdpdk
23 pkg-config --libs libdpdk
25 More detail on each of these steps can be got from the following sections.
31 The ``meson`` tool is used to configure a DPDK build. On most Linux
32 distributions this can be got using the local package management system,
33 e.g. ``dnf install meson`` or ``apt-get install meson``. If meson is not
34 available as a suitable package, it can also be installed using the Python
35 3 ``pip`` tool, e.g. ``pip3 install meson``. Version 0.42 of meson is
36 recommended - if the version packaged is too old, the latest version is
37 generally available from "pip".
39 The other dependency for building is the ``ninja`` tool, which acts similar
40 to make and performs the actual build using information provided by meson.
41 Installing meson will, in many cases, also install ninja, but, if not
42 already installed, it too is generally packaged by most Linux distributions.
43 If not available as a package, it can be downloaded as source or binary from
44 https://ninja-build.org/
48 ----------------------
50 To configure a build, run the meson tool, passing the path to the directory
51 to be used for the build e.g. ``meson build``, as shown above. If calling
52 meson from somewhere other than the root directory of the DPDK project the
53 path to the root directory should be passed as the first parameter, and the
54 build path as the second. For example, to build DPDK in /tmp/dpdk-build::
56 user@host:/tmp$ meson ~user/dpdk dpdk-build
58 Meson will then configure the build based on settings in the project's
59 meson.build files, and by checking the build environment for e.g. compiler
60 properties or the presence of dependencies, such as libpcap, or openssl
61 libcrypto libraries. Once done, meson writes a ``build.ninja`` file in the
62 build directory to be used to do the build itself when ninja is called.
64 Tuning of the build is possible, both as part of the original meson call,
65 or subsequently using ``meson configure`` command (``mesonconf`` in some
66 older versions). Some options, such as ``buildtype``, or ``werror`` are
67 built into meson, while others, such as ``max_lcores``, or the list of
68 examples to build, are DPDK-specific. To have a list of all options
69 available run ``meson configure`` in the build directory.
71 Examples of adjusting the defaults when doing initial meson configuration.
72 Project-specific options are passed used -Doption=value::
74 meson --werror werrorbuild # build with warnings as errors
76 meson --buildtype=debug debugbuild # build for debugging
78 meson -Dexamples=l3fwd,l2fwd fwdbuild # build some examples as
79 # part of the normal DPDK build
81 meson -Dmax_lcores=8 smallbuild # scale build for smaller systems
83 meson -Denable_docs=true fullbuild # build and install docs
85 Examples of setting the same options using meson configure::
87 meson configure -Dwerror=true
89 meson configure -Dbuildtype=debug
91 meson configure -Dexamples=l3fwd,l2fwd
93 meson configure -Dmax_lcores=8
95 NOTE: once meson has been run to configure a build in a directory, it
96 cannot be run again on the same directory. Instead ``meson configure``
97 should be used to change the build settings within the directory, and when
98 ``ninja`` is called to do the build itself, it will trigger the necessary
101 As well as those settings taken from ``meson configure``, other options
102 such as the compiler to use can be passed via environment variables. For
105 CC=clang meson clang-build
107 NOTE: for more comprehensive overriding of compilers or other environment
108 settings, the tools for cross-compilation may be considered. However, for
109 basic overriding of the compiler etc., the above form works as expected.
113 ---------------------
115 Use ``ninja`` to perform the actual build inside the build folder
116 previously configured. In most cases no arguments are necessary.
118 Ninja accepts a number of flags which are similar to make. For example, to
119 call ninja from outside the build folder, you can use ``ninja -C build``.
120 Ninja also runs parallel builds by default, but you can limit this using
121 the ``-j`` flag, e.g. ``ninja -j1 -v`` to do the build one step at a time,
122 printing each command on a new line as it runs.
125 Installing the Compiled Files
126 ------------------------------
128 Use ``ninja install`` to install the required DPDK files onto the system.
129 The install prefix defaults to ``/usr/local`` but can be used as with other
130 options above. The environment variable ``DESTDIR`` can be used to adjust
131 the root directory for the install, for example when packaging.
133 With the base install directory, the individual directories for libraries
134 and headers are configurable. By default, the following will be the
137 headers -> /usr/local/include
138 libraries -> /usr/local/lib64
139 drivers -> /usr/local/lib64/dpdk/drivers
140 libdpdk.pc -> /usr/local/lib64/pkgconfig
142 For the drivers, these will also be symbolically linked into the library
143 install directory, so that ld.so can find them in cases where one driver may
144 depend on another, e.g. a NIC PMD depending upon the PCI bus driver. Within
145 the EAL, the default search path for drivers will be set to the configured
146 driver install path, so dynamically-linked applications can be run without
147 having to pass in ``-d /path/to/driver`` options for standard drivers.
153 To cross-compile DPDK on a desired target machine we can use the following
156 meson cross-build --cross-file <target_machine_configuration>
158 For example if the target machine is arm64 we can use the following
160 meson arm-build --cross-file config/arm/arm64_armv8_linux_gcc
162 where config/arm/arm64_armv8_linux_gcc contains the following
166 c = 'aarch64-linux-gnu-gcc'
167 cpp = 'aarch64-linux-gnu-cpp'
168 ar = 'aarch64-linux-gnu-ar'
172 cpu_family = 'aarch64'
177 Using the DPDK within an Application
178 -------------------------------------
180 To compile and link against DPDK within an application, pkg-config should
181 be used to query the correct parameters. Examples of this are given in the
182 makefiles for the example applications included with DPDK. They demonstrate
183 how to link either against the DPDK shared libraries, or against the static
184 versions of the same.
186 From examples/helloworld/Makefile::
188 PC_FILE := $(shell pkg-config --path libdpdk)
189 CFLAGS += -O3 $(shell pkg-config --cflags libdpdk)
190 LDFLAGS_SHARED = $(shell pkg-config --libs libdpdk)
191 LDFLAGS_STATIC = -Wl,-Bstatic $(shell pkg-config --static --libs libdpdk)
193 build/$(APP)-shared: $(SRCS-y) Makefile $(PC_FILE) | build
194 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_SHARED)
196 build/$(APP)-static: $(SRCS-y) Makefile $(PC_FILE) | build
197 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_STATIC)
202 NOTE: for --static builds, DPDK needs to be built with Meson >= 0.46 in order to
203 fully generate the list of private dependencies. If DPDK is built with an older
204 version of Meson, it might be necessary to manually specify dependencies of DPDK
205 PMDs/libraries, for example -lmlx5 -lmnl for librte-pmd-mlx5, or the static link