--- /dev/null
+.. BSD LICENSE
+ Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of Intel Corporation nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+.. _Development_Kit_Build_System:
+
+Development Kit Build System
+============================
+
+The DPDK requires a build system for compilation activities and so on.
+This section describes the constraints and the mechanisms used in the DPDK framework.
+
+There are two use-cases for the framework:
+
+* Compilation of the DPDK libraries and sample applications;
+ the framework generates specific binary libraries,
+ include files and sample applications
+
+* Compilation of an external application or library, using an installed binary DPDK
+
+Building the Development Kit Binary
+-----------------------------------
+
+The following provides details on how to build the DPDK binary.
+
+Build Directory Concept
+~~~~~~~~~~~~~~~~~~~~~~~
+
+After installation, a build directory structure is created.
+Each build directory contains include files, libraries, and applications:
+
+.. code-block:: console
+
+ ~/DPDK$ ls
+ app MAINTAINERS
+ config Makefile
+ COPYRIGHT mk
+ doc scripts
+ examples lib
+ tools x86_64-native-linuxapp-gcc
+ x86_64-native-linuxapp-icc i686-native-linuxapp-gcc
+ i686-native-linuxapp-icc
+
+ ...
+ ~/DEV/DPDK$ ls i686-native-linuxapp-gcc
+
+ app build hostapp include kmod lib Makefile
+
+
+ ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/app/
+ cmdline_test dump_cfg test testpmd
+ cmdline_test.map dump_cfg.map test.map
+ testpmd.map
+
+
+ ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/lib/
+
+ libethdev.a librte_hash.a librte_mbuf.a librte_pmd_ixgbe.a
+
+ librte_cmdline.a librte_lpm.a librte_mempool.a librte_ring.a
+
+ librte_eal.a librte_pmd_e1000.a librte_timer.a
+
+
+ ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/include/
+ arch rte_cpuflags.h rte_memcpy.h
+ cmdline_cirbuf.h rte_cycles.h rte_memory.h
+ cmdline.h rte_debug.h rte_mempool.h
+ cmdline_parse_etheraddr.h rte_eal.h rte_memzone.h
+ cmdline_parse.h rte_errno.h rte_pci_dev_ids.h
+ cmdline_parse_ipaddr.h rte_ethdev.h rte_pci.h
+ cmdline_parse_num.h rte_ether.h rte_per_lcore.h
+ cmdline_parse_portlist.h rte_fbk_hash.h rte_prefetch.h
+ cmdline_parse_string.h rte_hash_crc.h rte_random.h
+ cmdline_rdline.h rte_hash.h rte_ring.h
+ cmdline_socket.h rte_interrupts.h rte_rwlock.h
+ cmdline_vt100.h rte_ip.h rte_sctp.h
+ exec-env rte_jhash.h rte_spinlock.h
+ rte_alarm.h rte_launch.h rte_string_fns.h
+ rte_atomic.h rte_lcore.h rte_tailq.h
+ rte_branch_prediction.h rte_log.h rte_tcp.h
+ rte_byteorder.h rte_lpm.h rte_timer.h
+ rte_common.h rte_malloc.h rte_udp.h
+ rte_config.h rte_mbuf.h
+
+
+A build directory is specific to a configuration that includes architecture + execution environment + toolchain.
+It is possible to have several build directories sharing the same sources with different configurations.
+
+For instance, to create a new build directory called my_sdk_build_dir using the default configuration template config/defconfig_x86_64-linuxapp,
+we use:
+
+.. code-block:: console
+
+ cd ${RTE_SDK}
+ make config T=x86_64-native-linuxapp-gcc O=my_sdk_build_dir
+
+This creates a new my_sdk_build_dir directory. After that, we can compile by doing:
+
+.. code-block:: console
+
+ cd my_sdk_build_dir
+ make
+
+which is equivalent to:
+
+.. code-block:: console
+
+ make O=my_sdk_build_dir
+
+The content of the my_sdk_build_dir is then:
+
+::
+
+ -- .config # used configuration
+
+ -- Makefile # wrapper that calls head Makefile
+ # with $PWD as build directory
+
+
+ -- build #All temporary files used during build
+ +--app # process, including . o, .d, and .cmd files.
+ | +-- test # For libraries, we have the .a file.
+ | +-- test.o # For applications, we have the elf file.
+ | `-- ...
+ +-- lib
+ +-- librte_eal
+ | `-- ...
+ +-- librte_mempool
+ | +-- mempool-file1.o
+ | +-- .mempool-file1.o.cmd
+ | +-- .mempool-file1.o.d
+ | +-- mempool-file2.o
+ | +-- .mempool-file2.o.cmd
+ | +-- .mempool-file2.o.d
+ | `-- mempool.a
+ `-- ...
+
+ -- include # All include files installed by libraries
+ +-- librte_mempool.h # and applications are located in this
+ +-- rte_eal.h # directory. The installed files can depend
+ +-- rte_spinlock.h # on configuration if needed (environment,
+ +-- rte_atomic.h # architecture, ..)
+ `-- \*.h ...
+
+ -- lib # all compiled libraries are copied in this
+ +-- librte_eal.a # directory
+ +-- librte_mempool.a
+ `-- \*.a ...
+
+ -- app # All compiled applications are installed
+ + --test # here. It includes the binary in elf format
+
+Refer to
+:ref:`Development Kit Root Makefile Help <Development_Kit_Root_Makefile_Help>`
+for details about make commands that can be used from the root of DPDK.
+
+Building External Applications
+------------------------------
+
+Since DPDK is in essence a development kit, the first objective of end users will be to create an application using this SDK.
+To compile an application, the user must set the RTE_SDK and RTE_TARGET environment variables.
+
+.. code-block:: console
+
+ export RTE_SDK=/opt/DPDK
+ export RTE_TARGET=x86_64-native-linuxapp-gcc
+ cd /path/to/my_app
+
+For a new application, the user must create their own Makefile that includes some .mk files, such as
+${RTE_SDK}/mk/rte.vars.mk, and ${RTE_SDK}/mk/ rte.app.mk.
+This is described in
+:ref:`Building Your Own Application <Building_Your_Own_Application>`.
+
+Depending on the chosen target (architecture, machine, executive environment, toolchain) defined in the Makefile or as an environment variable,
+the applications and libraries will compile using the appropriate .h files and will link with the appropriate .a files.
+These files are located in ${RTE_SDK}/arch-machine-execenv-toolchain, which is referenced internally by ${RTE_BIN_SDK}.
+
+To compile their application, the user just has to call make.
+The compilation result will be located in /path/to/my_app/build directory.
+
+Sample applications are provided in the examples directory.
+
+.. _Makefile_Description:
+
+Makefile Description
+--------------------
+
+General Rules For DPDK Makefiles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the DPDK, Makefiles always follow the same scheme:
+
+#. Include $(RTE_SDK)/mk/rte.vars.mk at the beginning.
+
+#. Define specific variables for RTE build system.
+
+#. Include a specific $(RTE_SDK)/mk/rte.XYZ.mk, where XYZ can be app, lib, extapp, extlib, obj, gnuconfigure,
+ and so on, depending on what kind of object you want to build.
+ :ref:`See Makefile Types <Makefile_Types>` below.
+
+#. Include user-defined rules and variables.
+
+ The following is a very simple example of an external application Makefile:
+
+ .. code-block:: make
+
+ include $(RTE_SDK)/mk/rte.vars.mk
+
+ # binary name
+ APP = helloworld
+
+ # all source are stored in SRCS-y
+ SRCS-y := main.c
+
+ CFLAGS += -O3
+ CFLAGS += $(WERROR_FLAGS)
+
+ include $(RTE_SDK)/mk/rte.extapp.mk
+
+.. _Makefile_Types:
+
+Makefile Types
+~~~~~~~~~~~~~~
+
+Depending on the .mk file which is included at the end of the user Makefile, the Makefile will have a different role.
+Note that it is not possible to build a library and an application in the same Makefile.
+For that, the user must create two separate Makefiles, possibly in two different directories.
+
+In any case, the rte.vars.mk file must be included in the user Makefile as soon as possible.
+
+Application
+^^^^^^^^^^^
+
+These Makefiles generate a binary application.
+
+* rte.app.mk: Application in the development kit framework
+
+* rte.extapp.mk: External application
+
+* rte.hostapp.mk: Host application in the development kit framework
+
+Library
+^^^^^^^
+
+Generate a .a library.
+
+* rte.lib.mk: Library in the development kit framework
+
+* rte.extlib.mk: external library
+
+* rte.hostlib.mk: host library in the development kit framework
+
+Install
+^^^^^^^
+
+* rte.install.mk: Does not build anything, it is only used to create links or copy files to the installation directory.
+ This is useful for including files in the development kit framework.
+
+Kernel Module
+^^^^^^^^^^^^^
+
+* rte.module.mk: Build a kernel module in the development kit framework.
+
+Objects
+^^^^^^^
+
+* rte.obj.mk: Object aggregation (merge several .o in one) in the development kit framework.
+
+* rte.extobj.mk: Object aggregation (merge several .o in one) outside the development kit framework.
+
+Misc
+^^^^
+
+* rte.doc.mk: Documentation in the development kit framework
+
+* rte.gnuconfigure.mk: Build an application that is configure-based.
+
+* rte.subdir.mk: Build several directories in the development kit framework.
+
+.. _Useful_Variables_Provided_by_the_Build_System:
+
+Useful Variables Provided by the Build System
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* RTE_SDK: The absolute path to the DPDK sources.
+ When compiling the development kit, this variable is automatically set by the framework.
+ It has to be defined by the user as an environment variable if compiling an external application.
+
+* RTE_SRCDIR: The path to the root of the sources. When compiling the development kit, RTE_SRCDIR = RTE_SDK.
+ When compiling an external application, the variable points to the root of external application sources.
+
+* RTE_OUTPUT: The path to which output files are written.
+ Typically, it is $(RTE_SRCDIR)/build, but it can be overridden by the O= option in the make command line.
+
+* RTE_TARGET: A string identifying the target for which we are building.
+ The format is arch-machine-execenv-toolchain.
+ When compiling the SDK, the target is deduced by the build system from the configuration (.config).
+ When building an external application, it must be specified by the user in the Makefile or as an environment variable.
+
+* RTE_SDK_BIN: References $(RTE_SDK)/$(RTE_TARGET).
+
+* RTE_ARCH: Defines the architecture (i686, x86_64).
+ It is the same value as CONFIG_RTE_ARCH but without the double-quotes around the string.
+
+* RTE_MACHINE: Defines the machine.
+ It is the same value as CONFIG_RTE_MACHINE but without the double-quotes around the string.
+
+* RTE_TOOLCHAIN: Defines the toolchain (gcc , icc).
+ It is the same value as CONFIG_RTE_TOOLCHAIN but without the double-quotes around the string.
+
+* RTE_EXEC_ENV: Defines the executive environment (linuxapp).
+ It is the same value as CONFIG_RTE_EXEC_ENV but without the double-quotes around the string.
+
+* RTE_KERNELDIR: This variable contains the absolute path to the kernel sources that will be used to compile the kernel modules.
+ 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).
+ By default, the variable is set to /lib/modules/$(shell uname -r)/build,
+ which is correct when the target machine is also the build machine.
+
+* RTE_DEVEL_BUILD: Stricter options (stop on warning). It defaults to y in a git tree.
+
+Variables that Can be Set/Overridden in a Makefile Only
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* VPATH: The path list that the build system will search for sources. By default, RTE_SRCDIR will be included in VPATH.
+
+* CFLAGS: Flags to use for C compilation. The user should use += to append data in this variable.
+
+* LDFLAGS: Flags to use for linking. The user should use += to append data in this variable.
+
+* ASFLAGS: Flags to use for assembly. The user should use += to append data in this variable.
+
+* CPPFLAGS: Flags to use to give flags to C preprocessor (only useful when assembling .S files).
+ The user should use += to append data in this variable.
+
+* LDLIBS: In an application, the list of libraries to link with (for example, -L /path/to/libfoo -lfoo ).
+ The user should use += to append data in this variable.
+
+* 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.
+ The sources must be available from VPATH.
+
+* INSTALL-y-$(INSTPATH): A list of files to be installed in $(INSTPATH).
+ The files must be available from VPATH and will be copied in $(RTE_OUTPUT)/$(INSTPATH). Can be used in almost any RTE Makefile.
+
+* SYMLINK-y-$(INSTPATH): A list of files to be installed in $(INSTPATH).
+ The files must be available from VPATH and will be linked (symbolically) in $(RTE_OUTPUT)/$(INSTPATH).
+ This variable can be used in almost any DPDK Makefile.
+
+* PREBUILD: A list of prerequisite actions to be taken before building. The user should use += to append data in this variable.
+
+* POSTBUILD: A list of actions to be taken after the main build. The user should use += to append data in this variable.
+
+* PREINSTALL: A list of prerequisite actions to be taken before installing. The user should use += to append data in this variable.
+
+* POSTINSTALL: A list of actions to be taken after installing. The user should use += to append data in this variable.
+
+* PRECLEAN: A list of prerequisite actions to be taken before cleaning. The user should use += to append data in this variable.
+
+* POSTCLEAN: A list of actions to be taken after cleaning. The user should use += to append data in this variable.
+
+* DEPDIR-y: Only used in the development kit framework to specify if the build of the current directory depends on build of another one.
+ This is needed to support parallel builds correctly.
+
+Variables that can be Set/Overridden by the User on the Command Line Only
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some variables can be used to configure the build system behavior. They are documented in
+:ref:`Development Kit Root Makefile Help <Development_Kit_Root_Makefile_Help>` and
+:ref:`External Application/Library Makefile Help <External_Application/Library_Makefile_Help>`
+
+ * WERROR_CFLAGS: By default, this is set to a specific value that depends on the compiler.
+ Users are encouraged to use this variable as follows:
+
+ CFLAGS += $(WERROR_CFLAGS)
+
+This avoids the use of different cases depending on the compiler (icc or gcc).
+Also, this variable can be overridden from the command line, which allows bypassing of the flags for testing purposes.
+
+Variables that Can be Set/Overridden by the User in a Makefile or Command Line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* CFLAGS_my_file.o: Specific flags to add for C compilation of my_file.c.
+
+* LDFLAGS_my_app: Specific flags to add when linking my_app.
+
+* EXTRA_CFLAGS: The content of this variable is appended after CFLAGS when compiling.
+
+* EXTRA_LDFLAGS: The content of this variable is appended after LDFLAGS when linking.
+
+* EXTRA_LDLIBS: The content of this variable is appended after LDLIBS when linking.
+
+* EXTRA_ASFLAGS: The content of this variable is appended after ASFLAGS when assembling.
+
+* EXTRA_CPPFLAGS: The content of this variable is appended after CPPFLAGS when using a C preprocessor on assembly files.
Code Review / deb_dpdk.git / blobdiff