doc/build-sdk-meson.txt

   1 INSTALLING DPDK USING THE MESON BUILD SYSTEM
   2 ---------------------------------------------
   3
   4 Summary
   5 --------
   6 For many platforms, compiling and installing DPDK should work using the
   7 following set of commands::
   8
   9         meson build
  10         cd build
  11         ninja
  12         ninja install
  13
  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.
  18
  19 After installation, to use DPDK, the necessary CFLAG and LDFLAG variables
  20 can be got from pkg-config::
  21
  22         pkg-config --cflags libdpdk
  23         pkg-config --libs libdpdk
  24
  25 More detail on each of these steps can be got from the following sections.
  26
  27
  28 Getting the Tools
  29 ------------------
  30
  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.47.1 of meson is
  36 required - if the version packaged is too old, the latest version is
  37 generally available from "pip".
  38
  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/
  45
  46
  47 Configuring the Build
  48 ----------------------
  49
  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::
  55
  56         user@host:/tmp$ meson ~user/dpdk dpdk-build
  57
  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.
  63
  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.
  70
  71 Examples of adjusting the defaults when doing initial meson configuration.
  72 Project-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 Examples of setting the same options using meson configure::
  88
  89         meson configure -Dwerror=true
  90
  91         meson configure -Dbuildtype=debug
  92
  93         meson configure -Dexamples=l3fwd,l2fwd
  94
  95         meson configure -Dmax_lcores=8
  96
  97 NOTE: once meson has been run to configure a build in a directory, it
  98 cannot be run again on the same directory. Instead ``meson configure``
  99 should be used to change the build settings within the directory, and when
 100 ``ninja`` is called to do the build itself, it will trigger the necessary
 101 re-scan from meson.
 102
 103 NOTE: machine=default uses a config that works on all supported architectures
 104 regardless of the capabilities of the machine where the build is happening.
 105
 106 As well as those settings taken from ``meson configure``, other options
 107 such as the compiler to use can be passed via environment variables. For
 108 example::
 109
 110         CC=clang meson clang-build
 111
 112 NOTE: for more comprehensive overriding of compilers or other environment
 113 settings, the tools for cross-compilation may be considered. However, for
 114 basic overriding of the compiler etc., the above form works as expected.
 115
 116
 117 Performing the Build
 118 ---------------------
 119
 120 Use ``ninja`` to perform the actual build inside the build folder
 121 previously configured. In most cases no arguments are necessary.
 122
 123 Ninja accepts a number of flags which are similar to make. For example, to
 124 call ninja from outside the build folder, you can use ``ninja -C build``.
 125 Ninja also runs parallel builds by default, but you can limit this using
 126 the ``-j`` flag, e.g. ``ninja -j1 -v`` to do the build one step at a time,
 127 printing each command on a new line as it runs.
 128
 129
 130 Installing the Compiled Files
 131 ------------------------------
 132
 133 Use ``ninja install`` to install the required DPDK files onto the system.
 134 The install prefix defaults to ``/usr/local`` but can be used as with other
 135 options above. The environment variable ``DESTDIR`` can be used to adjust
 136 the root directory for the install, for example when packaging.
 137
 138 With the base install directory, the individual directories for libraries
 139 and headers are configurable. By default, the following will be the
 140 installed layout::
 141
 142         headers -> /usr/local/include
 143         libraries -> /usr/local/lib64
 144         drivers -> /usr/local/lib64/dpdk/drivers
 145         libdpdk.pc -> /usr/local/lib64/pkgconfig
 146
 147 For the drivers, these will also be symbolically linked into the library
 148 install directory, so that ld.so can find them in cases where one driver may
 149 depend on another, e.g. a NIC PMD depending upon the PCI bus driver. Within
 150 the EAL, the default search path for drivers will be set to the configured
 151 driver install path, so dynamically-linked applications can be run without
 152 having to pass in ``-d /path/to/driver`` options for standard drivers.
 153
 154
 155 Cross Compiling DPDK
 156 --------------------
 157
 158 To cross-compile DPDK on a desired target machine we can use the following
 159 command::
 160
 161         meson cross-build --cross-file <target_machine_configuration>
 162
 163 For example if the target machine is arm64 we can use the following
 164 command::
 165         meson arm-build --cross-file config/arm/arm64_armv8_linux_gcc
 166
 167 where config/arm/arm64_armv8_linux_gcc contains settings for the compilers
 168 and other build tools to be used, as well as characteristics of the target
 169 machine.
 170
 171 Using the DPDK within an Application
 172 -------------------------------------
 173
 174 To compile and link against DPDK within an application, pkg-config should
 175 be used to query the correct parameters. Examples of this are given in the
 176 makefiles for the example applications included with DPDK. They demonstrate
 177 how to link either against the DPDK shared libraries, or against the static
 178 versions of the same.
 179
 180 From examples/helloworld/Makefile::
 181
 182         PC_FILE := $(shell pkg-config --path libdpdk)
 183         CFLAGS += -O3 $(shell pkg-config --cflags libdpdk)
 184         LDFLAGS_SHARED = $(shell pkg-config --libs libdpdk)
 185         LDFLAGS_STATIC = -Wl,-Bstatic $(shell pkg-config --static --libs libdpdk)
 186
 187         build/$(APP)-shared: $(SRCS-y) Makefile $(PC_FILE) | build
 188                 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_SHARED)
 189
 190         build/$(APP)-static: $(SRCS-y) Makefile $(PC_FILE) | build
 191                 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_STATIC)
 192
 193         build:
 194                 @mkdir -p $@