examples/ip_pipeline: add table entry commands
[dpdk.git] / doc / build-sdk-meson.txt
1 INSTALLING DPDK USING THE MESON BUILD SYSTEM
2 ---------------------------------------------
3
4 NOTE: Compiling and installing DPDK using ``meson`` and ``ninja``, rather
5 than using ``make`` (GNU make) is EXPERIMENTAL. Official builds of DPDK
6 should always be done using ``make``, as described in the ``Getting Started
7 Guide`` documentation, and at "http://dpdk.org/doc/quick-start".
8
9 Summary
10 --------
11 For many platforms, compiling and installing DPDK should work using the
12 following set of commands::
13
14         meson build
15         cd build
16         ninja
17         ninja install
18
19 This will compile DPDK in the ``build`` subdirectory, and then install the
20 resulting libraries, drivers and header files onto the system - generally
21 in /usr/local. A package-config file, ``libdpdk.pc``,  for DPDK will also
22 be installed to allow ease of compiling and linking with applications.
23
24 After installation, to use DPDK, the necessary CFLAG and LDFLAG variables
25 can be got from pkg-config::
26
27         pkg-config --cflags libdpdk
28         pkg-config --libs libdpdk
29
30 More detail on each of these steps can be got from the following sections.
31
32
33 Getting the Tools
34 ------------------
35
36 The ``meson`` tool is used to configure a DPDK build. On most Linux
37 distributions this can be got using the local package management system,
38 e.g. ``dnf install meson`` or ``apt-get install meson``. If meson is not
39 available as a suitable package, it can also be installed using the Python
40 3 ``pip`` tool, e.g. ``pip3 install meson``. Version 0.42 of meson is
41 recommended - if the version packaged is too old, the latest version is
42 generally available from "pip".
43
44 The other dependency for building is the ``ninja`` tool, which acts similar
45 to make and performs the actual build using information provided by meson.
46 Installing meson will, in many cases, also install ninja, but, if not
47 already installed, it too is generally packaged by most Linux distributions.
48 If not available as a package, it can be downloaded as source or binary from
49 https://ninja-build.org/
50
51
52 Configuring the Build
53 ----------------------
54
55 To configure a build, run the meson tool, passing the path to the directory
56 to be used for the build e.g. ``meson build``, as shown above. If calling
57 meson from somewhere other than the root directory of the DPDK project the
58 path to the root directory should be passed as the first parameter, and the
59 build path as the second. For example, to build DPDK in /tmp/dpdk-build::
60
61         user@host:/tmp$ meson ~user/dpdk dpdk-build
62
63 Meson will then configure the build based on settings in the project's
64 meson.build files, and by checking the build environment for e.g. compiler
65 properties or the presence of dependencies, such as libpcap, or openssl
66 libcrypto libraries. Once done, meson writes a ``build.ninja`` file in the
67 build directory to be used to do the build itself when ninja is called.
68
69 Tuning of the build is possible, both as part of the original meson call,
70 or subsequently using ``meson configure`` command (``mesonconf`` in some
71 older versions). Some options, such as ``buildtype``, or ``werror`` are
72 built into meson, while others, such as ``max_lcores``, or the list of
73 examples to build, are DPDK-specific. To have a list of all options
74 available run ``meson configure`` in the build directory.
75
76 Examples of adjusting the defaults when doing initial meson configuration.
77 Project-specific options are passed used -Doption=value::
78
79         meson --werror werrorbuild  # build with warnings as errors
80
81         meson --buildtype=debug debugbuild  # build for debugging
82
83         meson -Dexamples=l3fwd,l2fwd fwdbuild  # build some examples as
84                                         # part of the normal DPDK build
85
86         meson -Dmax_lcores=8 smallbuild  # scale build for smaller systems
87
88 Examples of setting the same options using meson configure::
89
90         meson configure -Dwerror=true
91
92         meson configure -Dbuildtype=debug
93
94         meson configure -Dexamples=l3fwd,l2fwd
95
96         meson configure -Dmax_lcores=8
97
98 NOTE: once meson has been run to configure a build in a directory, it
99 cannot be run again on the same directory. Instead ``meson configure``
100 should be used to change the build settings within the directory, and when
101 ``ninja`` is called to do the build itself, it will trigger the necessary
102 re-scan from meson.
103
104 As well as those settings taken from ``meson configure``, other options
105 such as the compiler to use can be passed via environment variables. For
106 example::
107
108         CC=clang meson clang-build
109
110 NOTE: for more comprehensive overriding of compilers or other environment
111 settings, the tools for cross-compilation may be considered. However, for
112 basic overriding of the compiler etc., the above form works as expected.
113
114
115 Performing the Build
116 ---------------------
117
118 Use ``ninja`` to perform the actual build inside the build folder
119 previously configured. In most cases no arguments are necessary.
120
121 Ninja accepts a number of flags which are similar to make. For example, to
122 call ninja from outside the build folder, you can use ``ninja -C build``.
123 Ninja also runs parallel builds by default, but you can limit this using
124 the ``-j`` flag, e.g. ``ninja -j1 -v`` to do the build one step at a time,
125 printing each command on a new line as it runs.
126
127
128 Installing the Compiled Files
129 ------------------------------
130
131 Use ``ninja install`` to install the required DPDK files onto the system.
132 The install prefix defaults to ``/usr/local`` but can be used as with other
133 options above. The environment variable ``DEST_DIR`` can be used to adjust
134 the root directory for the install, for example when packaging.
135
136 With the base install directory, the individual directories for libraries
137 and headers are configurable. By default, the following will be the
138 installed layout::
139
140         headers -> /usr/local/include
141         libraries -> /usr/local/lib64
142         drivers -> /usr/local/lib64/dpdk/drivers
143         libdpdk.pc -> /usr/local/lib64/pkgconfig
144
145 For the drivers, these will also be symbolically linked into the library
146 install directory, so that ld.so can find them in cases where one driver may
147 depend on another, e.g. a NIC PMD depending upon the PCI bus driver. Within
148 the EAL, the default search path for drivers will be set to the configured
149 driver install path, so dynamically-linked applications can be run without
150 having to pass in ``-d /path/to/driver`` options for standard drivers.
151
152
153 Cross Compiling DPDK
154 --------------------
155
156 To cross-compile DPDK on a desired target machine we can use the following
157 command::
158
159         meson cross-build --cross-file <target_machine_configuration>
160
161 For example if the target machine is arm64 we can use the following
162 command::
163         meson arm-build --cross-file config/arm/arm64_armv8_linuxapp_gcc
164
165 where config/arm/arm64_armv8_linuxapp_gcc contains the following
166 parameters::
167
168         [binaries]
169         c = 'aarch64-linux-gnu-gcc'
170         cpp = 'aarch64-linux-gnu-cpp'
171         ar = 'aarch64-linux-gnu-ar'
172
173         [host_machine]
174         system = 'linux'
175         cpu_family = 'aarch64'
176         cpu = 'armv8-a'
177         endian = 'little'
178
179
180 Using the DPDK within an Application
181 -------------------------------------
182
183 To compile and link against DPDK within an application, pkg-config should
184 be used to query the correct parameters. Examples of this are given in the
185 makefiles for the example applications included with DPDK. They demonstrate
186 how to link either against the DPDK shared libraries, or against the static
187 versions of the same.
188
189 From examples/helloworld/Makefile::
190
191         PC_FILE := $(shell pkg-config --path libdpdk)
192         CFLAGS += -O3 $(shell pkg-config --cflags libdpdk)
193         LDFLAGS_SHARED = $(shell pkg-config --libs libdpdk)
194         LDFLAGS_STATIC = -Wl,-Bstatic $(shell pkg-config --static --libs libdpdk)
195
196         build/$(APP)-shared: $(SRCS-y) Makefile $(PC_FILE) | build
197                 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_SHARED)
198
199         build/$(APP)-static: $(SRCS-y) Makefile $(PC_FILE) | build
200                 $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) $(LDFLAGS_STATIC)
201
202         build:
203                 @mkdir -p $@