1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2015 Intel Corporation. 3 4.. _linux_gsg_compiling_dpdk: 5 6Compiling the DPDK Target from Source 7===================================== 8 9Uncompress DPDK and Browse Sources 10---------------------------------- 11 12First, uncompress the archive and move to the uncompressed DPDK source directory: 13 14.. code-block:: console 15 16 tar xJf dpdk-<version>.tar.xz 17 cd dpdk-<version> 18 19The DPDK is composed of several directories, including: 20 21* doc: DPDK Documentation 22 23* license: DPDK license information 24 25* lib: Source code of DPDK libraries 26 27* drivers: Source code of DPDK poll-mode drivers 28 29* app: Source code of DPDK applications (automatic tests) 30 31* examples: Source code of DPDK application examples 32 33* config, buildtools: Framework-related scripts and configuration 34 35* usertools: Utility scripts for end-users of DPDK applications 36 37* devtools: Scripts for use by DPDK developers 38 39* kernel: Kernel modules needed for some operating systems 40 41 42Compiling and Installing DPDK System-wide 43----------------------------------------- 44 45DPDK can be configured, built and installed on your system using the tools 46``meson`` and ``ninja``. 47 48 49DPDK Configuration 50~~~~~~~~~~~~~~~~~~ 51 52To configure a DPDK build use: 53 54.. code-block:: console 55 56 meson setup <options> build 57 58where "build" is the desired output build directory, and "<options>" can be 59empty or one of a number of meson or DPDK-specific build options, described 60later in this section. The configuration process will finish with a summary 61of what DPDK libraries and drivers are to be built and installed, and for 62each item disabled, a reason why that is the case. This information can be 63used, for example, to identify any missing required packages for a driver. 64 65Once configured, to build and then install DPDK system-wide use: 66 67.. code-block:: console 68 69 cd build 70 ninja 71 meson install 72 ldconfig 73 74The last two commands above generally need to be run as root, 75with the `meson install` step copying the built objects to their final system-wide locations, 76and the last step causing the dynamic loader `ld.so` to update its cache to take account of the new objects. 77 78.. note:: 79 80 On some linux distributions, such as Fedora or Redhat, paths in `/usr/local` are 81 not in the default paths for the loader. Therefore, on these 82 distributions, `/usr/local/lib` and `/usr/local/lib64` should be added 83 to a file in `/etc/ld.so.conf.d/` before running `ldconfig`. 84 85.. _adjusting_build_options: 86 87Adjusting Build Options 88~~~~~~~~~~~~~~~~~~~~~~~ 89 90DPDK has a number of options that can be adjusted as part of the build configuration process. 91These options can be listed by running ``meson configure`` inside a configured build folder. 92Many of these options come from the "meson" tool itself and can be seen documented on the 93`Meson Website <https://mesonbuild.com/Builtin-options.html>`_. 94 95For example, to change the build-type from the default, "debugoptimized", 96to a regular "debug" build, you can either: 97 98* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially 99 100* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run. 101 102Other options are specific to the DPDK project but can be adjusted similarly. 103The "platform" option specifies a set a configuration parameters that will be used. 104The valid values are: 105 106* ``-Dplatform=native`` will tailor the configuration to the build machine. 107 108* ``-Dplatform=generic`` will use configuration that works on all machines 109 of the same architecture as the build machine. 110 111* ``-Dplatform=<SoC>`` will use configuration optimized for a particular SoC. 112 Consult the "socs" dictionary in ``config/arm/meson.build`` to see which 113 SoCs are supported. 114 115The instruction set will be set automatically by default according to these rules: 116 117* ``-Dplatform=native`` sets ``cpu_instruction_set`` to ``native``, 118 which configures ``-march`` (x86_64), ``-mcpu`` (ppc), ``-mtune`` (ppc) to ``native``. 119 120* ``-Dplatform=generic`` sets ``cpu_instruction_set`` to ``generic``, 121 which configures ``-march`` (x86_64), ``-mcpu`` (ppc), ``-mtune`` (ppc) to 122 a common minimal baseline needed for DPDK. 123 124To override what instruction set will be used, set the ``cpu_instruction_set`` 125parameter to the instruction set of your choice (such as ``corei7``, ``power8``, etc.). 126 127``cpu_instruction_set`` is not used in Arm builds, as setting the instruction set 128without other parameters leads to inferior builds. The way to tailor Arm builds 129is to build for a SoC using ``-Dplatform=<SoC>`` mentioned above. 130 131The values determined by the ``platform`` parameter may be overwritten. 132For example, to set the ``max_lcores`` value to 256, you can either: 133 134* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially 135 136* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run. 137 138Some of the DPDK sample applications in the `examples` directory can be 139automatically built as part of a meson build too. 140To do so, pass a comma-separated list of the examples to build to the 141`-Dexamples` meson option as below:: 142 143 meson setup -Dexamples=l2fwd,l3fwd build 144 145As with other meson options, this can also be set post-initial-config using `meson configure` in the build directory. 146There is also a special value "all" to request that all example applications whose 147dependencies are met on the current system are built. 148When `-Dexamples=all` is set as a meson option, meson will check each example application to see if it can be built, 149and add all which can be built to the list of tasks in the ninja build configuration file. 150 151 152Building 32-bit DPDK on 64-bit Systems 153~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 154 155To build a 32-bit copy of DPDK on a 64-bit OS, 156the ``-m32`` flag should be passed to the compiler and linker 157to force the generation of 32-bit objects and binaries. 158This can be done either by setting ``CFLAGS`` and ``LDFLAGS`` in the environment, 159or by passing the value to meson using ``-Dc_args=-m32`` and ``-Dc_link_args=-m32``. 160For correctly identifying and using any dependency packages, 161the ``pkg-config`` tool must also be configured 162to look in the appropriate directory for .pc files for 32-bit libraries. 163This is done by setting ``PKG_CONFIG_LIBDIR`` to the appropriate path. 164 165The following meson command can be used on RHEL/Fedora systems to configure a 32-bit build, 166assuming the relevant 32-bit development packages, such as a 32-bit libc, are installed:: 167 168 PKG_CONFIG_LIBDIR=/usr/lib/pkgconfig \ 169 meson setup -Dc_args='-m32' -Dc_link_args='-m32' build 170 171For Debian/Ubuntu systems, the equivalent command is:: 172 173 PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig \ 174 meson setup -Dc_args='-m32' -Dc_link_args='-m32' build 175 176Once the build directory has been configured, 177DPDK can be compiled using ``ninja`` as described above. 178 179 180.. _building_app_using_installed_dpdk: 181 182Building Applications Using Installed DPDK 183~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 184 185When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build. 186It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags) 187for DPDK into the application build process. 188 189An 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. 190A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)`` 191and the sources for that build are stored in ``$(SRCS-y)``. 192 193.. code-block:: makefile 194 195 PKGCONF = pkg-config 196 197 CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk) 198 LDFLAGS += $(shell $(PKGCONF) --libs libdpdk) 199 200 $(APP): $(SRCS-y) Makefile 201 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) 202 203.. note:: 204 205 Unlike with the make build system present in older DPDK releases, 206 the meson system is not 207 designed to be used directly from a build directory. Instead it is 208 recommended that it be installed either system-wide or to a known 209 location in the user's home directory. The install location can be set 210 using the `--prefix` meson option (default: `/usr/local`). 211 212an equivalent build recipe for a simple DPDK application using meson as a 213build system is shown below: 214 215.. code-block:: python 216 217 project('dpdk-app', 'c') 218 219 dpdk = dependency('libdpdk') 220 sources = files('main.c') 221 executable('dpdk-app', sources, dependencies: dpdk) 222