From: Bruce Richardson <bruce.richardson@intel.com>
To: dev@dpdk.org
Cc: bluca@debian.org, john.mcnamara@intel.com,
harry.van.haaren@intel.com, marko.kovacevic@intel.com,
thomas@monjalon.net, shreyansh.jain@nxp.com,
Bruce Richardson <bruce.richardson@intel.com>
Subject: [dpdk-dev] [PATCH v2] doc: add instructions on build using meson
Date: Tue, 9 Jan 2018 15:47:48 +0000 [thread overview]
Message-ID: <20180109154748.238958-1-bruce.richardson@intel.com> (raw)
In-Reply-To: <20171221161226.198837-1-bruce.richardson@intel.com>
Add a document describing how to configure, build and install DPDK using
meson and ninja. Document includes references to official installation docs
using make, and points out the experimental nature of the build.
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
V2:
* moved new document to the "doc/" directory
* minor updates following review comments from Shreyansh Jain
---
doc/build-sdk-meson.txt | 175 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 175 insertions(+)
create mode 100644 doc/build-sdk-meson.txt
diff --git a/doc/build-sdk-meson.txt b/doc/build-sdk-meson.txt
new file mode 100644
index 000000000..48798e191
--- /dev/null
+++ b/doc/build-sdk-meson.txt
@@ -0,0 +1,175 @@
+INSTALLING DPDK USING THE MESON BUILD SYSTEM
+---------------------------------------------
+
+NOTE: Compiling and installing DPDK using ``meson`` and ``ninja``, rather
+than using ``make`` (GNU make) is EXPERIMENTAL. Official builds of DPDK
+should always be done using ``make``, as described in the ``Getting Started
+Guide`` documentation, and at "http://dpdk.org/doc/quick-start".
+
+Summary
+--------
+For many platforms, compiling and installing DPDK should work using the
+following set of commands:
+
+ meson build
+ cd build
+ ninja
+ ninja install
+
+This will compile DPDK in the ``build`` subdirectory, and then install the
+resulting libraries, drivers and header files onto the system - generally
+in /usr/local. A package-config file, ``libdpdk.pc``, for DPDK will also
+be installed to allow ease of compiling and linking with applications.
+
+After installation, to use DPDK, the necessary CFLAG and LDFLAG variables
+can be got from pkg-config.
+ pkg-config --cflags libdpdk
+ pkg-config --libs libdpdk
+
+More detail on each of these steps can be got from the following sections.
+
+
+Getting the Tools
+------------------
+
+The ``meson`` tool is used to configure a DPDK build. On most Linux
+distributions this can be got using the local package management system,
+e.g. ``dnf install meson`` or ``apt-get install meson``. If meson is not
+available as a suitable package, it can also be installed using the Python
+3 ``pip`` tool, e.g. ``pip3 install meson``. Version 0.42 of meson is
+recommended - if the version packaged is too old, the latest version is
+generally available from "pip".
+
+The other dependency for building is the ``ninja`` tool, which acts similar
+to make and performs the actual build using information provided by meson.
+Installing meson will, in many cases, also install ninja, but, if not
+already installed, it too is generally packaged by most Linux distributions.
+If not available as a package, it can be downloaded as source or binary from
+https://ninja-build.org/
+
+
+Configuring the Build
+----------------------
+
+To configure a build, run the meson tool, passing the path to the directory
+to be used for the build e.g. ``meson build``, as shown above. If calling
+meson from somewhere other than the root directory of the DPDK project the
+path to the root directory should be passed as the first parameter, and the
+build path as the second. For example, to build DPDK in /tmp/dpdk-build:
+
+ user@host:/tmp$ meson ~user/dpdk dpdk-build
+
+Meson will then configure the build based on settings in the project's
+meson.build files, and by checking the build environment for e.g. compiler
+properties or the presence of dependencies, such as libpcap, or openssl
+libcrypto libraries. Once done, meson writes a ``build.ninja`` file in the
+build directory to be used to do the build itself when ninja is called.
+
+Tuning of the build is possible, both as part of the original meson call,
+or subsequently using ``meson configure`` command (``mesonconf`` in some
+older versions). Some options, such as ``buildtype``, or ``werror`` are
+built into meson, while others, such as ``max_lcores``, or the list of
+examples to build, are DPDK-specific. To have a list of all options
+available run ``meson configure`` in the build directory.
+
+Examples of adjusting the defaults when doing initial meson configuration.
+Project-specific options are passed used -Doption=value.
+
+ meson --werror werrorbuild # build with warnings as errors
+
+ meson --buildtype=debug debugbuild # build for debugging
+
+ meson -Dexamples=l3fwd,l2fwd fwdbuild # build some examples as
+ # part of the normal DPDK build
+
+ meson -Dmax_lcores=8 smallbuild # scale build for smaller systems
+
+Examples of setting the same options using meson configure
+
+ meson configure -Dwerror=true
+
+ meson configure -Dbuildtype=debug
+
+ meson configure -Dexamples=l3fwd,l2fwd
+
+ meson configure -Dmax_lcores=8
+
+NOTE: once meson has been run to configure a build in a directory, it
+cannot be run again on the same directory. Instead ``meson configure``
+should be used to change the build settings within the directory, and when
+``ninja`` is called to do the build itself, it will trigger the necessary
+re-scan from meson.
+
+As well as those settings taken from ``meson configure``, other options
+such as the compiler to use can be passed via environment variables. For
+example:
+
+ CC=clang meson clang-build
+
+NOTE: for more comprehensive overriding of compilers or other environment
+settings, the tools for cross-compilation may be considered. However, for
+basic overriding of the compiler etc., the above form works as expected.
+
+
+Performing the Build
+---------------------
+
+Use ``ninja`` to perform the actual build inside the build folder
+previously configured. In most cases no arguments are necessary.
+
+Ninja accepts a number of flags which are similar to make. For example, to
+call ninja from outside the build folder, you can use ``ninja -C build``.
+Ninja also runs parallel builds by default, but you can limit this using
+the ``-j`` flag, e.g. ``ninja -j1 -v`` to do the build one step at a time,
+printing each command on a new line as it runs.
+
+
+Installing the Compiled Files
+------------------------------
+
+Use ``ninja install`` to install the required DPDK files onto the system.
+The install prefix defaults to ``/usr/local`` but can be used as with other
+options above. The environment variable ``DEST_DIR`` can be used to adjust
+the root directory for the install, for example when packaging.
+
+With the base install directory, the individual directories for libraries
+and headers are configurable. By default, the following will be the
+installed layout:
+
+ headers -> /usr/local/include
+ libraries -> /usr/local/lib64
+ drivers -> /usr/local/lib64/dpdk/drivers
+ libdpdk.pc -> /usr/local/lib64/pkgconfig
+
+For the drivers, these will also be symbolically linked into the library
+install directory, so that ld.so can find them in cases where one driver may
+depend on another, e.g. a NIC PMD depending upon the PCI bus driver. Within
+the EAL, the default search path for drivers will be set to the configured
+driver install path, so dynamically-linked applications can be run without
+having to pass in ``-d /path/to/driver`` options for standard drivers.
+
+
+Using the DPDK within an Application
+-------------------------------------
+
+To compile and link against DPDK within an application, pkg-config should
+be used to query the correct parameters. Examples of this are given in the
+makefiles for the example applications included with DPDK. They demonstrate
+how to link either against the DPDK shared libraries, or against the static
+versions of the same.
+
+From examples/helloworld/Makefile:
+
+ PC_FILE := $(shell pkg-config --path libdpdk)
+ CFLAGS += -O3 $(shell pkg-config --cflags libdpdk)
+ LDFLAGS_SHARED = $(shell pkg-config --libs libdpdk)
+ LDFLAGS_STATIC = -Wl,-Bstatic $(shell pkg-config --static --libs libdpdk)
+
+ build/$(APP)-shared: $(SRCS-y) Makefile $(PC_FILE) | build
+ $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_SHARED)
+
+ build/$(APP)-static: $(SRCS-y) Makefile $(PC_FILE) | build
+ $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_STATIC)
+
+ build:
+ @mkdir -p $@
--
2.14.3
next prev parent reply other threads:[~2018-01-09 15:48 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-12-21 16:12 [dpdk-dev] [PATCH] " Bruce Richardson
2017-12-22 5:16 ` Shreyansh Jain
2018-01-09 15:40 ` Bruce Richardson
2018-01-09 15:47 ` Bruce Richardson [this message]
2018-01-10 12:02 ` [dpdk-dev] [PATCH v2] " Kovacevic, Marko
2018-01-10 13:24 ` Luca Boccassi
2018-01-10 15:24 ` [dpdk-dev] [PATCH v3] " Bruce Richardson
2018-01-10 15:57 ` Bruce Richardson
Reply instructions:
You may reply publicly 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=20180109154748.238958-1-bruce.richardson@intel.com \
--to=bruce.richardson@intel.com \
--cc=bluca@debian.org \
--cc=dev@dpdk.org \
--cc=harry.van.haaren@intel.com \
--cc=john.mcnamara@intel.com \
--cc=marko.kovacevic@intel.com \
--cc=shreyansh.jain@nxp.com \
--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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).