doc/guides/linux_gsg/build_dpdk.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2015 Intel Corporation.
   3
   4 .. _linux_gsg_compiling_dpdk:
   5
   6 Compiling the DPDK Target from Source
   7 =====================================
   8
   9 .. note::
  10
  11     Parts of this process can also be done using the setup script described in
  12     the :ref:`linux_setup_script` section of this document.
  13
  14 Uncompress DPDK and Browse Sources
  15 ----------------------------------
  16
  17 First, uncompress the archive and move to the uncompressed DPDK source directory:
  18
  19 .. code-block:: console
  20
  21     tar xJf dpdk-<version>.tar.xz
  22     cd dpdk-<version>
  23
  24 The DPDK is composed of several directories:
  25
  26 *   lib: Source code of DPDK libraries
  27
  28 *   drivers: Source code of DPDK poll-mode drivers
  29
  30 *   app: Source code of DPDK applications (automatic tests)
  31
  32 *   examples: Source code of DPDK application examples
  33
  34 *   config, buildtools, mk: Framework-related makefiles, scripts and configuration
  35
  36 Compiling and Installing DPDK System-wide
  37 -----------------------------------------
  38
  39 DPDK can be configured, built and installed on your system using the tools
  40 ``meson`` and ``ninja``.
  41
  42 .. note::
  43
  44   The older makefile-based build system used in older DPDK releases is
  45   still present and its use is described in section
  46   `Installation of DPDK Target Environment using Make`_.
  47
  48 DPDK Configuration
  49 ~~~~~~~~~~~~~~~~~~
  50
  51 To configure a DPDK build use:
  52
  53 .. code-block:: console
  54
  55      meson <options> build
  56
  57 where "build" is the desired output build directory, and "<options>" can be
  58 empty or one of a number of meson or DPDK-specific build options, described
  59 later in this section. The configuration process will finish with a summary
  60 of what DPDK libraries and drivers are to be built and installed, and for
  61 each item disabled, a reason why that is the case. This information can be
  62 used, for example, to identify any missing required packages for a driver.
  63
  64 Once configured, to build and then install DPDK system-wide use:
  65
  66 .. code-block:: console
  67
  68         cd build
  69         ninja
  70         ninja install
  71         ldconfig
  72
  73 The last two commands above generally need to be run as root,
  74 with the `ninja install` step copying the built objects to their final system-wide locations,
  75 and the last step causing the dynamic loader `ld.so` to update its cache to take account of the new objects.
  76
  77 .. note::
  78
  79    On some linux distributions, such as Fedora or Redhat, paths in `/usr/local` are
  80    not in the default paths for the loader. Therefore, on these
  81    distributions, `/usr/local/lib` and `/usr/local/lib64` should be added
  82    to a file in `/etc/ld.so.conf.d/` before running `ldconfig`.
  83
  84
  85 Adjusting Build Options
  86 ~~~~~~~~~~~~~~~~~~~~~~~
  87
  88 DPDK has a number of options that can be adjusted as part of the build configuration process.
  89 These options can be listed by running ``meson configure`` inside a configured build folder.
  90 Many of these options come from the "meson" tool itself and can be seen documented on the
  91 `Meson Website <https://mesonbuild.com/Builtin-options.html>`_.
  92
  93 For example, to change the build-type from the default, "debugoptimized",
  94 to a regular "debug" build, you can either:
  95
  96 * pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially
  97
  98 * run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
  99
 100 Other options are specific to the DPDK project but can be adjusted similarly.
 101 To set the "max_lcores" value to 256, for example, you can either:
 102
 103 * pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially
 104
 105 * run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
 106
 107 Some of the DPDK sample applications in the `examples` directory can be
 108 automatically built as part of a meson build too.
 109 To do so, pass a comma-separated list of the examples to build to the
 110 `-Dexamples` meson option as below::
 111
 112   meson -Dexamples=l2fwd,l3fwd build
 113
 114 As with other meson options, this can also be set post-initial-config using `meson configure` in the build directory.
 115 There is also a special value "all" to request that all example applications whose
 116 dependencies are met on the current system are built.
 117 When `-Dexamples=all` is set as a meson option, meson will check each example application to see if it can be built,
 118 and add all which can be built to the list of tasks in the ninja build configuration file.
 119
 120 Building Applications Using Installed DPDK
 121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 122
 123 When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
 124 It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
 125 for DPDK into the application build process.
 126
 127 An example of how to query and use the pkg-config file can be found in the ``Makefile`` of each of the example applications included with DPDK.
 128 A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
 129 and the sources for that build are stored in ``$(SRCS-y)``.
 130
 131 .. code-block:: makefile
 132
 133         PKGCONF = pkg-config
 134
 135         CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
 136         LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
 137
 138         $(APP): $(SRCS-y) Makefile
 139                 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
 140
 141 .. note::
 142
 143    Unlike with the older make build system, the meson system is not
 144    designed to be used directly from a build directory. Instead it is
 145    recommended that it be installed either system-wide or to a known
 146    location in the user's home directory. The install location can be set
 147    using the `--prefix` meson option (default: `/usr/local`).
 148
 149 an equivalent build recipe for a simple DPDK application using meson as a
 150 build system is shown below:
 151
 152 .. code-block:: python
 153
 154    project('dpdk-app', 'c')
 155
 156    dpdk = dependency('libdpdk')
 157    sources = files('main.c')
 158    executable('dpdk-app', sources, dependencies: dpdk)
 159
 160
 161 Installation of DPDK Target Environment using Make
 162 --------------------------------------------------
 163
 164 .. note::
 165
 166    The building of DPDK using make will be deprecated in a future release. It
 167    is therefore recommended that DPDK installation is done using meson and
 168    ninja as described above.
 169
 170 Get a native target environment automatically::
 171
 172    make defconfig O=mybuild
 173
 174 .. note::
 175
 176     Within the configuration files, the ``RTE_MACHINE`` configuration value is set to native,
 177     which means that the compiled software is tuned for the platform on which it is built.
 178
 179 Or get a specific target environment::
 180
 181    make config T=x86_64-native-linux-gcc O=mybuild
 182
 183 The format of a DPDK target is "ARCH-MACHINE-EXECENV-TOOLCHAIN".
 184 Available targets can be found with::
 185
 186    make help
 187
 188 Customize the target configuration in the generated ``.config`` file.
 189 Example for enabling the pcap PMD::
 190
 191    sed -ri 's,(PMD_PCAP=).*,\1y,' mybuild/.config
 192
 193 Compile the target::
 194
 195    make -j4 O=mybuild
 196
 197 .. warning::
 198
 199     Any kernel modules to be used, e.g. ``igb_uio``, ``kni``, must be compiled with the
 200     same kernel as the one running on the target.
 201     If the DPDK is not being built on the target machine,
 202     the ``RTE_KERNELDIR`` environment variable should be used to point the compilation at a copy of the kernel version to be used on the target machine.
 203
 204 Install the target in a separate directory::
 205
 206    make install O=mybuild DESTDIR=myinstall prefix=
 207
 208 The environment is ready to build a DPDK application::
 209
 210    RTE_SDK=$(pwd)/myinstall/share/dpdk RTE_TARGET=x86_64-native-linux-gcc make -C myapp
 211
 212 In addition, the make clean command can be used to remove any existing compiled files for a subsequent full, clean rebuild of the code.
 213
 214 Browsing the Installed DPDK Environment Target
 215 ----------------------------------------------
 216
 217 Once a target is created it contains all libraries, including poll-mode drivers, and header files for the DPDK environment that are required to build customer applications.
 218 In addition, the test applications are built under the app directory, which may be used for testing.
 219 A kmod  directory is also present that contains kernel modules which may be loaded if needed.