1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2010-2014 Intel Corporation.
4 .. _Development_Kit_Build_System:
6 Development Kit Build System
7 ============================
9 The DPDK requires a build system for compilation activities and so on.
10 This section describes the constraints and the mechanisms used in the DPDK framework.
12 There are two use-cases for the framework:
14 * Compilation of the DPDK libraries and sample applications;
15 the framework generates specific binary libraries,
16 include files and sample applications
18 * Compilation of an external application or library, using an installed binary DPDK
20 Building the Development Kit Binary
21 -----------------------------------
23 The following provides details on how to build the DPDK binary.
25 Build Directory Concept
26 ~~~~~~~~~~~~~~~~~~~~~~~
28 After installation, a build directory structure is created.
29 Each build directory contains include files, libraries, and applications.
31 A build directory is specific to a configuration that includes architecture + execution environment + toolchain.
32 It is possible to have several build directories sharing the same sources with different configurations.
34 For instance, to create a new build directory called my_sdk_build_dir using the default configuration template config/defconfig_x86_64-linuxapp,
37 .. code-block:: console
40 make config T=x86_64-native-linuxapp-gcc O=my_sdk_build_dir
42 This creates a new my_sdk_build_dir directory. After that, we can compile by doing:
44 .. code-block:: console
49 which is equivalent to:
51 .. code-block:: console
53 make O=my_sdk_build_dir
56 :ref:`Development Kit Root Makefile Help <Development_Kit_Root_Makefile_Help>`
57 for details about make commands that can be used from the root of DPDK.
59 Building External Applications
60 ------------------------------
62 Since DPDK is in essence a development kit, the first objective of end users will be to create an application using this SDK.
63 To compile an application, the user must set the RTE_SDK and RTE_TARGET environment variables.
65 .. code-block:: console
67 export RTE_SDK=/opt/DPDK
68 export RTE_TARGET=x86_64-native-linuxapp-gcc
71 For a new application, the user must create their own Makefile that includes some .mk files, such as
72 ${RTE_SDK}/mk/rte.vars.mk, and ${RTE_SDK}/mk/ rte.app.mk.
74 :ref:`Building Your Own Application <Building_Your_Own_Application>`.
76 Depending on the chosen target (architecture, machine, executive environment, toolchain) defined in the Makefile or as an environment variable,
77 the applications and libraries will compile using the appropriate .h files and will link with the appropriate .a files.
78 These files are located in ${RTE_SDK}/arch-machine-execenv-toolchain, which is referenced internally by ${RTE_BIN_SDK}.
80 To compile their application, the user just has to call make.
81 The compilation result will be located in /path/to/my_app/build directory.
83 Sample applications are provided in the examples directory.
85 .. _Makefile_Description:
90 General Rules For DPDK Makefiles
91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93 In the DPDK, Makefiles always follow the same scheme:
95 #. Include $(RTE_SDK)/mk/rte.vars.mk at the beginning.
97 #. Define specific variables for RTE build system.
99 #. Include a specific $(RTE_SDK)/mk/rte.XYZ.mk, where XYZ can be app, lib, extapp, extlib, obj, gnuconfigure,
100 and so on, depending on what kind of object you want to build.
101 :ref:`See Makefile Types <Makefile_Types>` below.
103 #. Include user-defined rules and variables.
105 The following is a very simple example of an external application Makefile:
109 include $(RTE_SDK)/mk/rte.vars.mk
114 # all source are stored in SRCS-y
118 CFLAGS += $(WERROR_FLAGS)
120 include $(RTE_SDK)/mk/rte.extapp.mk
127 Depending on the .mk file which is included at the end of the user Makefile, the Makefile will have a different role.
128 Note that it is not possible to build a library and an application in the same Makefile.
129 For that, the user must create two separate Makefiles, possibly in two different directories.
131 In any case, the rte.vars.mk file must be included in the user Makefile as soon as possible.
136 These Makefiles generate a binary application.
138 * rte.app.mk: Application in the development kit framework
140 * rte.extapp.mk: External application
142 * rte.hostapp.mk: prerequisite tool to build dpdk
147 Generate a .a library.
149 * rte.lib.mk: Library in the development kit framework
151 * rte.extlib.mk: external library
153 * rte.hostlib.mk: host library in the development kit framework
158 * rte.install.mk: Does not build anything, it is only used to create links or copy files to the installation directory.
159 This is useful for including files in the development kit framework.
164 * rte.module.mk: Build a kernel module in the development kit framework.
169 * rte.obj.mk: Object aggregation (merge several .o in one) in the development kit framework.
171 * rte.extobj.mk: Object aggregation (merge several .o in one) outside the development kit framework.
176 * rte.doc.mk: Documentation in the development kit framework
178 * rte.gnuconfigure.mk: Build an application that is configure-based.
180 * rte.subdir.mk: Build several directories in the development kit framework.
182 .. _Internally_Generated_Build_Tools:
184 Internally Generated Build Tools
185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187 ``app/dpdk-pmdinfogen``
190 ``dpdk-pmdinfogen`` scans an object (.o) file for various well known symbol names.
191 These well known symbol names are defined by various macros and used to export
192 important information about hardware support and usage for pmd files. For
197 RTE_PMD_REGISTER_PCI(name, drv)
199 Creates the following symbol:
203 static char this_pmd_name0[] __attribute__((used)) = "<name>";
206 Which ``dpdk-pmdinfogen`` scans for. Using this information other relevant
207 bits of data can be exported from the object file and used to produce a
208 hardware support description, that ``dpdk-pmdinfogen`` then encodes into a
209 json formatted string in the following format:
213 static char <name_pmd_string>="PMD_INFO_STRING=\"{'name' : '<name>', ...}\"";
216 These strings can then be searched for by external tools to determine the
217 hardware support of a given library or application.
220 .. _Useful_Variables_Provided_by_the_Build_System:
222 Useful Variables Provided by the Build System
223 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
225 * RTE_SDK: The absolute path to the DPDK sources.
226 When compiling the development kit, this variable is automatically set by the framework.
227 It has to be defined by the user as an environment variable if compiling an external application.
229 * RTE_SRCDIR: The path to the root of the sources. When compiling the development kit, RTE_SRCDIR = RTE_SDK.
230 When compiling an external application, the variable points to the root of external application sources.
232 * RTE_OUTPUT: The path to which output files are written.
233 Typically, it is $(RTE_SRCDIR)/build, but it can be overridden by the O= option in the make command line.
235 * RTE_TARGET: A string identifying the target for which we are building.
236 The format is arch-machine-execenv-toolchain.
237 When compiling the SDK, the target is deduced by the build system from the configuration (.config).
238 When building an external application, it must be specified by the user in the Makefile or as an environment variable.
240 * RTE_SDK_BIN: References $(RTE_SDK)/$(RTE_TARGET).
242 * RTE_ARCH: Defines the architecture (i686, x86_64).
243 It is the same value as CONFIG_RTE_ARCH but without the double-quotes around the string.
245 * RTE_MACHINE: Defines the machine.
246 It is the same value as CONFIG_RTE_MACHINE but without the double-quotes around the string.
248 * RTE_TOOLCHAIN: Defines the toolchain (gcc , icc).
249 It is the same value as CONFIG_RTE_TOOLCHAIN but without the double-quotes around the string.
251 * RTE_EXEC_ENV: Defines the executive environment (linuxapp).
252 It is the same value as CONFIG_RTE_EXEC_ENV but without the double-quotes around the string.
254 * RTE_KERNELDIR: This variable contains the absolute path to the kernel sources that will be used to compile the kernel modules.
255 The kernel headers must be the same as the ones that will be used on the target machine (the machine that will run the application).
256 By default, the variable is set to /lib/modules/$(shell uname -r)/build,
257 which is correct when the target machine is also the build machine.
259 * RTE_DEVEL_BUILD: Stricter options (stop on warning). It defaults to y in a git tree.
261 Variables that Can be Set/Overridden in a Makefile Only
262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
264 * VPATH: The path list that the build system will search for sources. By default, RTE_SRCDIR will be included in VPATH.
266 * CFLAGS: Flags to use for C compilation. The user should use += to append data in this variable.
268 * LDFLAGS: Flags to use for linking. The user should use += to append data in this variable.
270 * ASFLAGS: Flags to use for assembly. The user should use += to append data in this variable.
272 * CPPFLAGS: Flags to use to give flags to C preprocessor (only useful when assembling .S files).
273 The user should use += to append data in this variable.
275 * LDLIBS: In an application, the list of libraries to link with (for example, -L /path/to/libfoo -lfoo ).
276 The user should use += to append data in this variable.
278 * SRC-y: A list of source files (.c, .S, or .o if the source is a binary) in case of application, library or object Makefiles.
279 The sources must be available from VPATH.
281 * INSTALL-y-$(INSTPATH): A list of files to be installed in $(INSTPATH).
282 The files must be available from VPATH and will be copied in $(RTE_OUTPUT)/$(INSTPATH). Can be used in almost any RTE Makefile.
284 * SYMLINK-y-$(INSTPATH): A list of files to be installed in $(INSTPATH).
285 The files must be available from VPATH and will be linked (symbolically) in $(RTE_OUTPUT)/$(INSTPATH).
286 This variable can be used in almost any DPDK Makefile.
288 * PREBUILD: A list of prerequisite actions to be taken before building. The user should use += to append data in this variable.
290 * POSTBUILD: A list of actions to be taken after the main build. The user should use += to append data in this variable.
292 * PREINSTALL: A list of prerequisite actions to be taken before installing. The user should use += to append data in this variable.
294 * POSTINSTALL: A list of actions to be taken after installing. The user should use += to append data in this variable.
296 * PRECLEAN: A list of prerequisite actions to be taken before cleaning. The user should use += to append data in this variable.
298 * POSTCLEAN: A list of actions to be taken after cleaning. The user should use += to append data in this variable.
300 * DEPDIRS-$(DIR): Only used in the development kit framework to specify if the build of the current directory depends on build of another one.
301 This is needed to support parallel builds correctly.
303 Variables that can be Set/Overridden by the User on the Command Line Only
304 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
306 Some variables can be used to configure the build system behavior. They are documented in
307 :ref:`Development Kit Root Makefile Help <Development_Kit_Root_Makefile_Help>` and
308 :ref:`External Application/Library Makefile Help <External_Application/Library_Makefile_Help>`
310 * WERROR_CFLAGS: By default, this is set to a specific value that depends on the compiler.
311 Users are encouraged to use this variable as follows:
313 CFLAGS += $(WERROR_CFLAGS)
315 This avoids the use of different cases depending on the compiler (icc or gcc).
316 Also, this variable can be overridden from the command line, which allows bypassing of the flags for testing purposes.
318 Variables that Can be Set/Overridden by the User in a Makefile or Command Line
319 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
321 * CFLAGS_my_file.o: Specific flags to add for C compilation of my_file.c.
323 * LDFLAGS_my_app: Specific flags to add when linking my_app.
325 * EXTRA_CFLAGS: The content of this variable is appended after CFLAGS when compiling.
327 * EXTRA_LDFLAGS: The content of this variable is appended after LDFLAGS when linking.
329 * EXTRA_LDLIBS: The content of this variable is appended after LDLIBS when linking.
331 * EXTRA_ASFLAGS: The content of this variable is appended after ASFLAGS when assembling.
333 * EXTRA_CPPFLAGS: The content of this variable is appended after CPPFLAGS when using a C preprocessor on assembly files.