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