DPDK patches and discussions
 help / color / Atom feed
From: Bruce Richardson <bruce.richardson@intel.com>
To: dev@dpdk.org
Cc: thomas@monjalon.net,
	Bruce Richardson <bruce.richardson@intel.com>,
	Anatoly Burakov <anatoly.burakov@intel.com>
Subject: [dpdk-dev] [PATCH v3 2/5] doc: add building with meson to linux GSG
Date: Thu, 28 Nov 2019 16:33:47 +0000
Message-ID: <20191128163350.24076-3-bruce.richardson@intel.com> (raw)
In-Reply-To: <20191128163350.24076-1-bruce.richardson@intel.com>

Add instructions on building DPDK and using the pkg-config file to the
linux GSG.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>
---
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 <options> build
+
+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.
+
+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 <https://mesonbuild.com/Builtin-options.html>`_.
+
+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


  parent reply index

Thread overview: 47+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-11-22 16:03 [dpdk-dev] [PATCH 0/8] GSG Documentation updates Bruce Richardson
2019-11-22 16:03 ` [dpdk-dev] [PATCH 1/8] doc: update Linux GSG system requirements section Bruce Richardson
2019-11-28 11:51   ` Thomas Monjalon
2019-11-28 14:11     ` Bruce Richardson
2019-11-28 14:22       ` Thomas Monjalon
2019-11-28 14:30         ` Bruce Richardson
2019-11-28 14:34           ` Thomas Monjalon
2019-11-28 14:59             ` Bruce Richardson
2019-11-22 16:03 ` [dpdk-dev] [PATCH 2/8] doc: add building with meson to linux GSG Bruce Richardson
2019-11-25 13:19   ` Burakov, Anatoly
2019-11-25 13:27     ` Bruce Richardson
2019-11-25 13:54       ` Burakov, Anatoly
2019-11-25 14:40         ` Richardson, Bruce
2019-11-25 13:22   ` Burakov, Anatoly
2019-11-25 14:38     ` Richardson, Bruce
2019-11-22 16:03 ` [dpdk-dev] [PATCH 3/8] doc: reorder meson and make build instructions for arm Bruce Richardson
2019-11-24 11:25   ` Gavin Hu (Arm Technology China)
2019-11-22 16:03 ` [dpdk-dev] [PATCH 4/8] doc: remove reference to old versions of FreeBSD Bruce Richardson
2019-11-22 16:03 ` [dpdk-dev] [PATCH 5/8] doc: update examples output in FreeBSD GSG Bruce Richardson
2019-11-22 16:03 ` [dpdk-dev] [PATCH 6/8] doc: add meson install instructions for FreeBSD Bruce Richardson
2019-11-22 16:03 ` [dpdk-dev] [PATCH 7/8] doc: update documentation on build and running FreeBSD apps Bruce Richardson
2019-11-22 16:03 ` [dpdk-dev] [PATCH 8/8] doc: drop EAL command-line reference from FreeBSD GSG Bruce Richardson
2019-11-25 14:55 ` [dpdk-dev] [PATCH v2 0/8] GSG Documentation updates Bruce Richardson
2019-11-25 14:55   ` [dpdk-dev] [PATCH v2 1/8] doc: update Linux GSG system requirements section Bruce Richardson
2019-11-25 14:55   ` [dpdk-dev] [PATCH v2 2/8] doc: add building with meson to linux GSG Bruce Richardson
2019-11-25 15:11     ` Burakov, Anatoly
2019-11-25 14:55   ` [dpdk-dev] [PATCH v2 3/8] doc: reorder meson and make build instructions for arm Bruce Richardson
2019-11-25 14:55   ` [dpdk-dev] [PATCH v2 4/8] doc: remove reference to old versions of FreeBSD Bruce Richardson
2019-11-27 12:10     ` Burakov, Anatoly
2019-11-25 14:55   ` [dpdk-dev] [PATCH v2 5/8] doc: update examples output in FreeBSD GSG Bruce Richardson
2019-11-27 12:11     ` Burakov, Anatoly
2019-11-27 12:23       ` Bruce Richardson
2019-11-25 14:55   ` [dpdk-dev] [PATCH v2 6/8] doc: add meson install instructions for FreeBSD Bruce Richardson
2019-11-27 12:23     ` Burakov, Anatoly
2019-11-25 14:55   ` [dpdk-dev] [PATCH v2 7/8] doc: update documentation on build and running FreeBSD apps Bruce Richardson
2019-11-27 12:29     ` Burakov, Anatoly
2019-11-25 14:55   ` [dpdk-dev] [PATCH v2 8/8] doc: drop EAL command-line reference from FreeBSD GSG Bruce Richardson
2019-11-27 12:31     ` Burakov, Anatoly
2019-11-27 13:46       ` Bruce Richardson
2019-11-28 16:33 ` [dpdk-dev] [PATCH v3 0/5] GSG Documentation updates Bruce Richardson
2019-11-28 16:33   ` [dpdk-dev] [PATCH v3 1/5] doc: update Linux GSG system requirements section Bruce Richardson
2019-11-28 16:33   ` Bruce Richardson [this message]
2019-11-28 16:33   ` [dpdk-dev] [PATCH v3 3/5] doc: reorder meson and make build instructions for arm Bruce Richardson
2019-11-28 16:33   ` [dpdk-dev] [PATCH v3 4/5] doc: remove reference to old versions of FreeBSD Bruce Richardson
2019-11-28 16:33   ` [dpdk-dev] [PATCH v3 5/5] doc: update examples output in FreeBSD GSG Bruce Richardson
2019-11-28 18:56   ` [dpdk-dev] [PATCH v3 0/5] GSG Documentation updates Thomas Monjalon
2020-01-03 15:37     ` Bruce Richardson

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191128163350.24076-3-bruce.richardson@intel.com \
    --to=bruce.richardson@intel.com \
    --cc=anatoly.burakov@intel.com \
    --cc=dev@dpdk.org \
    --cc=thomas@monjalon.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

DPDK patches and discussions

Archives are clonable:
	git clone --mirror http://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ http://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev


Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/ public-inbox