-.. BSD LICENSE
- Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of Intel Corporation nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2015 Intel Corporation.
.. _linux_gsg_compiling_dpdk:
Compiling the DPDK Target from Source
=====================================
-.. note::
-
- Parts of this process can also be done using the setup script described in
- the :ref:`linux_setup_script` section of this document.
-
-Install the DPDK and Browse Sources
------------------------------------
+Uncompress DPDK and Browse Sources
+----------------------------------
First, uncompress the archive and move to the uncompressed DPDK source directory:
* examples: Source code of DPDK application examples
-* config, buildtools, mk: Framework-related makefiles, scripts and configuration
+* config, buildtools: Framework-related scripts and configuration
+
+Compiling and Installing DPDK System-wide
+-----------------------------------------
+
+DPDK can be configured, built and installed on your system using the tools
+``meson`` and ``ninja``.
-Installation of DPDK Target Environments
-----------------------------------------
-The format of a DPDK target is::
+DPDK Configuration
+~~~~~~~~~~~~~~~~~~
- ARCH-MACHINE-EXECENV-TOOLCHAIN
+To configure a DPDK build use:
-where:
+.. code-block:: console
+
+ meson <options> build
-* ``ARCH`` can be: ``i686``, ``x86_64``, ``ppc_64``, ``arm64``
+where "build" is the desired output build directory, and "<options>" can be
+empty or one of a number of meson or DPDK-specific build options, described
+later in this section. The configuration process will finish with a summary
+of what DPDK libraries and drivers are to be built and installed, and for
+each item disabled, a reason why that is the case. This information can be
+used, for example, to identify any missing required packages for a driver.
-* ``MACHINE`` can be: ``native``, ``power8``, ``armv8a``
+Once configured, to build and then install DPDK system-wide use:
-* ``EXECENV`` can be: ``linuxapp``, ``bsdapp``
+.. code-block:: console
-* ``TOOLCHAIN`` can be: ``gcc``, ``icc``
+ cd build
+ ninja
+ ninja install
+ ldconfig
-The targets to be installed depend on the 32-bit and/or 64-bit packages and compilers installed on the host.
-Available targets can be found in the DPDK/config directory.
-The defconfig\_ prefix should not be used.
+The last two commands above generally need to be run as root,
+with the `ninja install` step copying the built objects to their final system-wide locations,
+and the last step causing the dynamic loader `ld.so` to update its cache to take account of the new objects.
.. note::
- Configuration files are provided with the ``RTE_MACHINE`` optimization level set.
- Within the configuration files, the ``RTE_MACHINE`` configuration value is set to native,
- which means that the compiled software is tuned for the platform on which it is built.
- For more information on this setting, and its possible values, see the *DPDK Programmers Guide*.
+ On some linux distributions, such as Fedora or Redhat, paths in `/usr/local` are
+ not in the default paths for the loader. Therefore, on these
+ distributions, `/usr/local/lib` and `/usr/local/lib64` should be added
+ to a file in `/etc/ld.so.conf.d/` before running `ldconfig`.
-When using the Intel® C++ Compiler (icc), one of the following commands should be invoked for 64-bit or 32-bit use respectively.
-Notice that the shell scripts update the ``$PATH`` variable and therefore should not be performed in the same session.
-Also, verify the compiler's installation directory since the path may be different:
+.. _adjusting_build_options:
-.. code-block:: console
+Adjusting Build Options
+~~~~~~~~~~~~~~~~~~~~~~~
- source /opt/intel/bin/iccvars.sh intel64
- source /opt/intel/bin/iccvars.sh ia32
+DPDK has a number of options that can be adjusted as part of the build configuration process.
+These options can be listed by running ``meson configure`` inside a configured build folder.
+Many of these options come from the "meson" tool itself and can be seen documented on the
+`Meson Website <https://mesonbuild.com/Builtin-options.html>`_.
-To install and make targets, use the ``make install T=<target>`` command in the top-level DPDK directory.
+For example, to change the build-type from the default, "debugoptimized",
+to a regular "debug" build, you can either:
-For example, to compile a 64-bit target using icc, run:
+* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially
-.. code-block:: console
+* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
- make install T=x86_64-native-linuxapp-icc
+Other options are specific to the DPDK project but can be adjusted similarly.
+The "platform" option specifies a set a configuration parameters that will be used.
+The valid values are:
-To compile a 32-bit build using gcc, the make command should be:
+* ``-Dplatform=native`` will tailor the configuration to the build machine.
-.. code-block:: console
+* ``-Dplatform=generic`` will use configuration that works on all machines
+ of the same architecture as the build machine.
- make install T=i686-native-linuxapp-gcc
+* ``-Dplatform=<SoC>`` will use configuration optimized for a particular SoC.
+ Consult the "socs" dictionary in ``config/arm/meson.build`` to see which
+ SoCs are supported.
-To prepare a target without building it, for example, if the configuration changes need to be made before compilation,
-use the ``make config T=<target>`` command:
+The instruction set will be set automatically by default according to these rules:
-.. code-block:: console
+* ``-Dplatform=native`` sets ``cpu_instruction_set`` to ``native``,
+ which configures ``-march`` (x86_64), ``-mcpu`` (ppc), ``-mtune`` (ppc) to ``native``.
- make config T=x86_64-native-linuxapp-gcc
+* ``-Dplatform=generic`` sets ``cpu_instruction_set`` to ``generic``,
+ which configures ``-march`` (x86_64), ``-mcpu`` (ppc), ``-mtune`` (ppc) to
+ a common minimal baseline needed for DPDK.
-.. warning::
+To override what instruction set will be used, set the ``cpu_instruction_set``
+parameter to the instruction set of your choice (such as ``corei7``, ``power8``, etc.).
- Any kernel modules to be used, e.g. ``igb_uio``, ``kni``, must be compiled with the
- same kernel as the one running on the target.
- If the DPDK is not being built on the target machine,
- 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.
+``cpu_instruction_set`` is not used in Arm builds, as setting the instruction set
+without other parameters leads to inferior builds. The way to tailor Arm builds
+is to build for a SoC using ``-Dplatform=<SoC>`` mentioned above.
-Once the target environment is created, the user may move to the target environment directory and continue to make code changes and re-compile.
-The user may also make modifications to the compile-time DPDK configuration by editing the .config file in the build directory.
-(This is a build-local copy of the defconfig file from the top- level config directory).
+The values determined by the ``platform`` parameter may be overwritten.
+For example, to set the ``max_lcores`` value to 256, you can either:
-.. code-block:: console
+* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially
+
+* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
+
+Some of the DPDK sample applications in the `examples` directory can be
+automatically built as part of a meson build too.
+To do so, pass a comma-separated list of the examples to build to the
+`-Dexamples` meson option as below::
+
+ meson -Dexamples=l2fwd,l3fwd build
+
+As with other meson options, this can also be set post-initial-config using `meson configure` in the build directory.
+There is also a special value "all" to request that all example applications whose
+dependencies are met on the current system are built.
+When `-Dexamples=all` is set as a meson option, meson will check each example application to see if it can be built,
+and add all which can be built to the list of tasks in the ninja build configuration file.
+
+
+Building 32-bit DPDK on 64-bit Systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To build a 32-bit copy of DPDK on a 64-bit OS,
+the ``-m32`` flag should be passed to the compiler and linker
+to force the generation of 32-bit objects and binaries.
+This can be done either by setting ``CFLAGS`` and ``LDFLAGS`` in the environment,
+or by passing the value to meson using ``-Dc_args=-m32`` and ``-Dc_link_args=-m32``.
+For correctly identifying and using any dependency packages,
+the ``pkg-config`` tool must also be configured
+to look in the appropriate directory for .pc files for 32-bit libraries.
+This is done by setting ``PKG_CONFIG_LIBDIR`` to the appropriate path.
+
+The following meson command can be used on RHEL/Fedora systems to configure a 32-bit build,
+assuming the relevant 32-bit development packages, such as a 32-bit libc, are installed::
+
+ PKG_CONFIG_LIBDIR=/usr/lib/pkgconfig \
+ meson -Dc_args='-m32' -Dc_link_args='-m32' build
+
+For Debian/Ubuntu systems, the equivalent command is::
+
+ PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig \
+ meson -Dc_args='-m32' -Dc_link_args='-m32' build
+
+Once the build directory has been configured,
+DPDK can be compiled using ``ninja`` as described above.
+
+
+.. _building_app_using_installed_dpdk:
+
+Building Applications Using Installed DPDK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
+It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
+for DPDK into the application build process.
+
+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.
+A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
+and the sources for that build are stored in ``$(SRCS-y)``.
+
+.. code-block:: makefile
+
+ PKGCONF = pkg-config
+
+ CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
+ LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
+
+ $(APP): $(SRCS-y) Makefile
+ $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
+
+.. note::
+
+ Unlike with the make build system present in older DPDK releases,
+ the meson system is not
+ designed to be used directly from a build directory. Instead it is
+ recommended that it be installed either system-wide or to a known
+ location in the user's home directory. The install location can be set
+ using the `--prefix` meson option (default: `/usr/local`).
- cd x86_64-native-linuxapp-gcc
- vi .config
- make
+an equivalent build recipe for a simple DPDK application using meson as a
+build system is shown below:
-In addition, the make clean command can be used to remove any existing compiled files for a subsequent full, clean rebuild of the code.
+.. code-block:: python
-Browsing the Installed DPDK Environment Target
-----------------------------------------------
+ project('dpdk-app', 'c')
-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.
-In addition, the test and testpmd applications are built under the build/app directory, which may be used for testing.
-A kmod directory is also present that contains kernel modules which may be loaded if needed.
+ dpdk = dependency('libdpdk')
+ sources = files('main.c')
+ executable('dpdk-app', sources, dependencies: dpdk)
git.droids-corp.org / dpdk.git / blobdiff