doc/guides/prog_guide/dev_kit_build_system.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 .. _Development_Kit_Build_System:
  32
  33 Development Kit Build System
  34 ============================
  35
  36 The DPDK requires a build system for compilation activities and so on.
  37 This section describes the constraints and the mechanisms used in the DPDK framework.
  38
  39 There are two use-cases for the framework:
  40
  41 *   Compilation of the DPDK libraries and sample applications;
  42     the framework generates specific binary libraries,
  43     include files and sample applications
  44
  45 *   Compilation of an external application or library, using an installed binary DPDK
  46
  47 Building the Development Kit Binary
  48 -----------------------------------
  49
  50 The following provides details on how to build the DPDK binary.
  51
  52 Build Directory Concept
  53 ~~~~~~~~~~~~~~~~~~~~~~~
  54
  55 After installation, a build directory structure is created.
  56 Each build directory contains include files, libraries, and applications:
  57
  58 .. code-block:: console
  59
  60     ~/DPDK$ ls
  61     app                               MAINTAINERS
  62     config                            Makefile
  63     COPYRIGHT                         mk
  64     doc                               scripts
  65     examples                          lib
  66     tools                             x86_64-native-linuxapp-gcc
  67     x86_64-native-linuxapp-icc        i686-native-linuxapp-gcc
  68     i686-native-linuxapp-icc
  69
  70     ...
  71     ~/DEV/DPDK$ ls i686-native-linuxapp-gcc
  72
  73     app build hostapp include kmod lib Makefile
  74
  75
  76     ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/app/
  77     cmdline_test   dump_cfg     test     testpmd
  78     cmdline_test.map      dump_cfg.map   test.map
  79             testpmd.map
  80
  81
  82     ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/lib/
  83
  84     libethdev.a  librte_hash.a  librte_mbuf.a librte_pmd_ixgbe.a
  85
  86     librte_cmdline.a librte_lpm.a librte_mempool.a librte_ring.a
  87
  88     librte_eal.a librte_pmd_e1000.a librte_timer.a
  89
  90
  91     ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/include/
  92     arch                       rte_cpuflags.h       rte_memcpy.h
  93     cmdline_cirbuf.h           rte_cycles.h         rte_memory.h
  94     cmdline.h                  rte_debug.h          rte_mempool.h
  95     cmdline_parse_etheraddr.h  rte_eal.h            rte_memzone.h
  96     cmdline_parse.h            rte_errno.h          rte_pci_dev_ids.h
  97     cmdline_parse_ipaddr.h     rte_ethdev.h         rte_pci.h
  98     cmdline_parse_num.h        rte_ether.h          rte_per_lcore.h
  99     cmdline_parse_portlist.h   rte_fbk_hash.h       rte_prefetch.h
 100     cmdline_parse_string.h     rte_hash_crc.h       rte_random.h
 101     cmdline_rdline.h           rte_hash.h           rte_ring.h
 102     cmdline_socket.h           rte_interrupts.h     rte_rwlock.h
 103     cmdline_vt100.h            rte_ip.h             rte_sctp.h
 104     exec-env                   rte_jhash.h          rte_spinlock.h
 105     rte_alarm.h                rte_launch.h         rte_string_fns.h
 106     rte_atomic.h               rte_lcore.h          rte_tailq.h
 107     rte_branch_prediction.h    rte_log.h            rte_tcp.h
 108     rte_byteorder.h            rte_lpm.h            rte_timer.h
 109     rte_common.h               rte_malloc.h         rte_udp.h
 110     rte_config.h               rte_mbuf.h
 111
 112
 113 A build directory is specific to a configuration that includes architecture + execution environment + toolchain.
 114 It is possible to have several build directories sharing the same sources with different configurations.
 115
 116 For instance, to create a new build directory called my_sdk_build_dir using the default configuration template config/defconfig_x86_64-linuxapp,
 117 we use:
 118
 119 .. code-block:: console
 120
 121     cd ${RTE_SDK}
 122     make config T=x86_64-native-linuxapp-gcc O=my_sdk_build_dir
 123
 124 This creates a new my_sdk_build_dir directory. After that, we can compile by doing:
 125
 126 .. code-block:: console
 127
 128     cd my_sdk_build_dir
 129     make
 130
 131 which is equivalent to:
 132
 133 .. code-block:: console
 134
 135     make O=my_sdk_build_dir
 136
 137 The content of the my_sdk_build_dir is then:
 138
 139 ::
 140
 141     -- .config                         # used configuration
 142
 143     -- Makefile                        # wrapper that calls head Makefile
 144                                        # with $PWD as build directory
 145
 146
 147         -- build                              #All temporary files used during build
 148         +--app                                # process, including . o, .d, and .cmd files.
 149             |  +-- test                       # For libraries, we have the .a file.
 150             |  +-- test.o                     # For applications, we have the elf file.
 151             |  `-- ...
 152             +-- lib
 153                 +-- librte_eal
 154                 |   `-- ...
 155                 +-- librte_mempool
 156                 |  +--  mempool-file1.o
 157                 |  +--  .mempool-file1.o.cmd
 158                 |  +--  .mempool-file1.o.d
 159                 |  +--   mempool-file2.o
 160                 |  +--  .mempool-file2.o.cmd
 161                 |  +--  .mempool-file2.o.d
 162                 |  `--  mempool.a
 163                 `-- ...
 164
 165     -- include                # All include files installed by libraries
 166         +-- librte_mempool.h  # and applications are located in this
 167         +-- rte_eal.h         # directory. The installed files can depend
 168         +-- rte_spinlock.h    # on configuration if needed (environment,
 169         +-- rte_atomic.h      # architecture, ..)
 170         `-- \*.h ...
 171
 172     -- lib                    # all compiled libraries are copied in this
 173         +-- librte_eal.a      # directory
 174         +-- librte_mempool.a
 175         `-- \*.a ...
 176
 177     -- app                    # All compiled applications are installed
 178     + --test                  # here. It includes the binary in elf format
 179
 180 Refer to
 181 :ref:`Development Kit Root Makefile Help <Development_Kit_Root_Makefile_Help>`
 182 for details about make commands that can be used from the root of DPDK.
 183
 184 Building External Applications
 185 ------------------------------
 186
 187 Since DPDK is in essence a development kit, the first objective of end users will be to create an application using this SDK.
 188 To compile an application, the user must set the RTE_SDK and RTE_TARGET environment variables.
 189
 190 .. code-block:: console
 191
 192     export RTE_SDK=/opt/DPDK
 193     export RTE_TARGET=x86_64-native-linuxapp-gcc
 194     cd /path/to/my_app
 195
 196 For a new application, the user must create their own Makefile that includes some .mk files, such as
 197 ${RTE_SDK}/mk/rte.vars.mk, and ${RTE_SDK}/mk/ rte.app.mk.
 198 This is described in
 199 :ref:`Building Your Own Application <Building_Your_Own_Application>`.
 200
 201 Depending on the chosen target (architecture, machine, executive environment, toolchain) defined in the Makefile or as an environment variable,
 202 the applications and libraries will compile using the appropriate .h files and will link with the appropriate .a files.
 203 These files are located in ${RTE_SDK}/arch-machine-execenv-toolchain, which is referenced internally by ${RTE_BIN_SDK}.
 204
 205 To compile their application, the user just has to call make.
 206 The compilation result will be located in /path/to/my_app/build directory.
 207
 208 Sample applications are provided in the examples directory.
 209
 210 .. _Makefile_Description:
 211
 212 Makefile Description
 213 --------------------
 214
 215 General Rules For DPDK Makefiles
 216 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 217
 218 In the DPDK, Makefiles always follow the same scheme:
 219
 220 #. Include $(RTE_SDK)/mk/rte.vars.mk at the beginning.
 221
 222 #. Define specific variables for RTE build system.
 223
 224 #. Include a specific $(RTE_SDK)/mk/rte.XYZ.mk, where XYZ can be app, lib, extapp, extlib, obj, gnuconfigure,
 225    and so on, depending on what kind of object you want to build.
 226    :ref:`See Makefile Types <Makefile_Types>` below.
 227
 228 #. Include user-defined rules and variables.
 229
 230    The following is a very simple example of an external application Makefile:
 231
 232    ..  code-block:: make
 233
 234         include $(RTE_SDK)/mk/rte.vars.mk
 235
 236         # binary name
 237         APP = helloworld
 238
 239         # all source are stored in SRCS-y
 240         SRCS-y := main.c
 241
 242         CFLAGS += -O3
 243         CFLAGS += $(WERROR_FLAGS)
 244
 245         include $(RTE_SDK)/mk/rte.extapp.mk
 246
 247 .. _Makefile_Types:
 248
 249 Makefile Types
 250 ~~~~~~~~~~~~~~
 251
 252 Depending on the .mk file which is included at the end of the user Makefile, the Makefile will have a different role.
 253 Note that it is not possible to build a library and an application in the same Makefile.
 254 For that, the user must create two separate Makefiles, possibly in two different directories.
 255
 256 In any case, the rte.vars.mk file must be included in the user Makefile as soon as possible.
 257
 258 Application
 259 ^^^^^^^^^^^
 260
 261 These Makefiles generate a binary application.
 262
 263 *   rte.app.mk: Application in the development kit framework
 264
 265 *   rte.extapp.mk: External application
 266
 267 *   rte.hostapp.mk: Host application in the development kit framework
 268
 269 Library
 270 ^^^^^^^
 271
 272 Generate a .a library.
 273
 274 *   rte.lib.mk: Library in the development kit framework
 275
 276 *   rte.extlib.mk: external library
 277
 278 *   rte.hostlib.mk: host library in the development kit framework
 279
 280 Install
 281 ^^^^^^^
 282
 283 *   rte.install.mk: Does not build anything, it is only used to create links or copy files to the installation directory.
 284     This is useful for including files in the development kit framework.
 285
 286 Kernel Module
 287 ^^^^^^^^^^^^^
 288
 289 *   rte.module.mk: Build a kernel module in the development kit framework.
 290
 291 Objects
 292 ^^^^^^^
 293
 294 *   rte.obj.mk: Object aggregation (merge several .o in one) in the development kit framework.
 295
 296 *   rte.extobj.mk: Object aggregation (merge several .o in one) outside the development kit framework.
 297
 298 Misc
 299 ^^^^
 300
 301 *   rte.doc.mk: Documentation in the development kit framework
 302
 303 *   rte.gnuconfigure.mk: Build an application that is configure-based.
 304
 305 *   rte.subdir.mk: Build several directories in the development kit framework.
 306
 307 .. _Useful_Variables_Provided_by_the_Build_System:
 308
 309 Useful Variables Provided by the Build System
 310 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 311
 312 *   RTE_SDK: The absolute path to the DPDK sources.
 313     When compiling the development kit, this variable is automatically set by the framework.
 314     It has to be defined by the user as an environment variable if compiling an external application.
 315
 316 *   RTE_SRCDIR: The path to the root of the sources. When compiling the development kit, RTE_SRCDIR = RTE_SDK.
 317     When compiling an external application, the variable points to the root of external application sources.
 318
 319 *   RTE_OUTPUT: The path to which output files are written.
 320     Typically, it is $(RTE_SRCDIR)/build, but it can be overridden by the O= option in the make command line.
 321
 322 *   RTE_TARGET: A string identifying the target for which we are building.
 323     The format is arch-machine-execenv-toolchain.
 324     When compiling the SDK, the target is deduced by the build system from the configuration (.config).
 325     When building an external application, it must be specified by the user in the Makefile or as an environment variable.
 326
 327 *   RTE_SDK_BIN: References $(RTE_SDK)/$(RTE_TARGET).
 328
 329 *   RTE_ARCH: Defines the architecture (i686, x86_64).
 330     It is the same value as CONFIG_RTE_ARCH  but without the double-quotes around the string.
 331
 332 *   RTE_MACHINE: Defines the machine.
 333     It is the same value as CONFIG_RTE_MACHINE but without the double-quotes around the string.
 334
 335 *   RTE_TOOLCHAIN: Defines the toolchain (gcc , icc).
 336     It is the same value as CONFIG_RTE_TOOLCHAIN but without the double-quotes around the string.
 337
 338 *   RTE_EXEC_ENV: Defines the executive environment (linuxapp).
 339     It is the same value as CONFIG_RTE_EXEC_ENV but without the double-quotes around the string.
 340
 341 *   RTE_KERNELDIR: This variable contains the absolute path to the kernel sources that will be used to compile the kernel modules.
 342     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).
 343     By default, the variable is set to /lib/modules/$(shell uname -r)/build,
 344     which is correct when the target machine is also the build machine.
 345
 346 *   RTE_DEVEL_BUILD: Stricter options (stop on warning). It defaults to y in a git tree.
 347
 348 Variables that Can be Set/Overridden in a Makefile Only
 349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 350
 351 *   VPATH: The path list that the build system will search for sources. By default, RTE_SRCDIR will be included in VPATH.
 352
 353 *   CFLAGS: Flags to use for C compilation. The user should use +=  to append data in this variable.
 354
 355 *   LDFLAGS: Flags to use for linking. The user should use +=  to append data in this variable.
 356
 357 *   ASFLAGS: Flags to use for assembly. The user should use +=  to append data in this variable.
 358
 359 *   CPPFLAGS: Flags to use to give flags to C preprocessor (only useful when assembling .S files).
 360     The user should use += to append data in this variable.
 361
 362 *   LDLIBS: In an application, the list of libraries to link with (for example, -L  /path/to/libfoo -lfoo ).
 363     The user should use  +=  to append data in this variable.
 364
 365 *   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.
 366     The sources must be available from VPATH.
 367
 368 *   INSTALL-y-$(INSTPATH): A list of files to be installed in  $(INSTPATH).
 369     The files must be available from VPATH and will be copied in $(RTE_OUTPUT)/$(INSTPATH). Can be used in almost any RTE Makefile.
 370
 371 *   SYMLINK-y-$(INSTPATH): A list of files to be installed in $(INSTPATH).
 372     The files must be available from VPATH and will be linked (symbolically) in  $(RTE_OUTPUT)/$(INSTPATH).
 373     This variable can be used in almost any DPDK Makefile.
 374
 375 *   PREBUILD: A list of prerequisite actions to be taken before building. The user should use +=  to append data in this variable.
 376
 377 *   POSTBUILD: A list of actions to be taken after the main build. The user should use += to append data in this variable.
 378
 379 *   PREINSTALL: A list of prerequisite actions to be taken before installing. The user should use += to append data in this variable.
 380
 381 *   POSTINSTALL: A list of actions to be taken after installing. The user should use += to append data in this variable.
 382
 383 *   PRECLEAN: A list of prerequisite actions to be taken before cleaning. The user should use += to append data in this variable.
 384
 385 *   POSTCLEAN: A list of actions to be taken after cleaning. The user should use += to append data in this variable.
 386
 387 *   DEPDIR-y: Only used in the development kit framework to specify if the build of the current directory depends on build of another one.
 388     This is needed to support parallel builds correctly.
 389
 390 Variables that can be Set/Overridden by the User on the Command Line Only
 391 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 392
 393 Some variables can be used to configure the build system behavior. They are documented in
 394 :ref:`Development Kit Root Makefile Help <Development_Kit_Root_Makefile_Help>` and
 395 :ref:`External Application/Library Makefile Help <External_Application/Library_Makefile_Help>`
 396
 397     *   WERROR_CFLAGS: By default, this is set to a specific value that depends on the compiler.
 398         Users are encouraged to use this variable as follows:
 399
 400             CFLAGS += $(WERROR_CFLAGS)
 401
 402 This avoids the use of different cases depending on the compiler (icc or gcc).
 403 Also, this variable can be overridden from the command line, which allows bypassing of the flags for testing purposes.
 404
 405 Variables that Can be Set/Overridden by the User in a Makefile or Command Line
 406 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 407
 408 *   CFLAGS_my_file.o: Specific flags to add for C compilation of my_file.c.
 409
 410 *   LDFLAGS_my_app: Specific flags to add when linking my_app.
 411
 412 *   EXTRA_CFLAGS: The content of this variable is appended after CFLAGS when compiling.
 413
 414 *   EXTRA_LDFLAGS: The content of this variable is appended after LDFLAGS when linking.
 415
 416 *   EXTRA_LDLIBS: The content of this variable is appended after LDLIBS when linking.
 417
 418 *   EXTRA_ASFLAGS: The content of this variable is appended after ASFLAGS when assembling.
 419
 420 *   EXTRA_CPPFLAGS: The content of this variable is appended after CPPFLAGS when using a C preprocessor on assembly files.