doc/guides/prog_guide/build-sdk-meson.rst

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