From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 79612A04C2; Mon, 25 Nov 2019 15:56:33 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 063FA5681; Mon, 25 Nov 2019 15:56:27 +0100 (CET) Received: from mga05.intel.com (mga05.intel.com [192.55.52.43]) by dpdk.org (Postfix) with ESMTP id 9AEB02BCE for ; Mon, 25 Nov 2019 15:56:25 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by fmsmga105.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 25 Nov 2019 06:56:24 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.69,241,1571727600"; d="scan'208";a="239560831" Received: from silpixa00399126.ir.intel.com (HELO silpixa00399126.ger.corp.intel.com) ([10.237.223.2]) by fmsmga002.fm.intel.com with ESMTP; 25 Nov 2019 06:56:23 -0800 From: Bruce Richardson To: john.mcnamara@intel.com Cc: dev@dpdk.org, anatoly.burakov@intel.com, Bruce Richardson Date: Mon, 25 Nov 2019 14:55:53 +0000 Message-Id: <20191125145559.29251-3-bruce.richardson@intel.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191125145559.29251-1-bruce.richardson@intel.com> References: <20191122160359.11625-1-bruce.richardson@intel.com> <20191125145559.29251-1-bruce.richardson@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v2 2/8] doc: add building with meson to linux GSG X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Add instructions on building DPDK and using the pkg-config file to the linux GSG. Signed-off-by: Bruce Richardson --- V2: Changes following Anatoly's review: * minor grammar fix * added ldconfig call to instructions and note about needing to add /usr/local/lib* to loader paths on RHEL/Fedora * added description of -Dexamples option * added example of using libdpdk from an app meson.build file --- doc/guides/linux_gsg/build_dpdk.rst | 139 +++++++++++++++++++++++++++- 1 file changed, 135 insertions(+), 4 deletions(-) diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst index 7c0329fcc..4aeb4697d 100644 --- a/doc/guides/linux_gsg/build_dpdk.rst +++ b/doc/guides/linux_gsg/build_dpdk.rst @@ -11,8 +11,8 @@ Compiling the DPDK Target from Source 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: @@ -33,8 +33,139 @@ The DPDK is composed of several directories: * config, buildtools, mk: Framework-related makefiles, scripts and configuration -Installation of DPDK Target Environments ----------------------------------------- +Compiling and Installing DPDK System-wide +----------------------------------------- + +DPDK can be configured, built and installed on your system using the tools +``meson`` and ``ninja``. + +.. note:: + + The older makefile-based build system used in older DPDK releases is + still present and its use is described in section + `Installation of DPDK Target Environment using Make`_. + +DPDK Configuration +~~~~~~~~~~~~~~~~~~ + +To configure a DPDK build use: + +.. code-block:: console + + meson build + +where "build" is the desired output build directory, and "" 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. + +Once configured, to build and then install DPDK system-wide use: + +.. code-block:: console + + cd build + ninja + ninja install + ldconfig + +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:: + + 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`. + + +Adjusting Build Options +~~~~~~~~~~~~~~~~~~~~~~~ + +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 `_. + +For example, to change the build-type from the default, "debugoptimized", +to a regular "debug" build, you can either: + +* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially + +* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run. + +Other options are specific to the DPDK project but can be adjusted similarly. +To set the "max_lcores" value to 256, for example, you can either: + +* 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 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 older make build system, 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`). + +an equivalent build recipe for a simple DPDK application using meson as a +build system is shown below: + +.. code-block:: python + + project('dpdk-app', 'c') + + dpdk = dependency('libdpdk') + sources = files('main.c') + executable('dpdk-app', sources, dependencies: dpdk) + + +Installation of DPDK Target Environment using Make +-------------------------------------------------- + +.. note:: + + The building of DPDK using make will be deprecated in a future release. It + is therefore recommended that DPDK installation is done using meson and + ninja as described above. The format of a DPDK target is:: -- 2.21.0