dev_kit_root_make_help.rst revision 97f17497
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_Root_Makefile_Help:
32
33Development Kit Root Makefile Help
34==================================
35
36The DPDK provides a root level Makefile with targets for configuration, building, cleaning, testing, installation and others.
37These targets are explained in the following sections.
38
39Configuration Targets
40---------------------
41
42The configuration target requires the name of the target, which is specified using T=mytarget and it is mandatory.
43The list of available targets are in $(RTE_SDK)/config (remove the defconfig _ prefix).
44
45Configuration targets also support the specification of the name of the output directory, using O=mybuilddir.
46This is an optional parameter, the default output directory is build.
47
48*   Config
49
50    This will create a build directory, and generates a configuration from a template.
51    A Makefile is also created in the new build directory.
52
53    Example:
54
55    .. code-block:: console
56
57        make config O=mybuild T=x86_64-native-linuxapp-gcc
58
59Build Targets
60-------------
61
62Build targets support the optional specification of the name of the output directory, using O=mybuilddir.
63The default output directory is build.
64
65*   all, build or just make
66
67    Build the DPDK in the output directory previously created by a make config.
68
69    Example:
70
71    .. code-block:: console
72
73        make O=mybuild
74
75*   clean
76
77    Clean all objects created using make build.
78
79    Example:
80
81    .. code-block:: console
82
83        make clean O=mybuild
84
85*   %_sub
86
87    Build a subdirectory only, without managing dependencies on other directories.
88
89    Example:
90
91    .. code-block:: console
92
93        make lib/librte_eal_sub O=mybuild
94
95*   %_clean
96
97    Clean a subdirectory only.
98
99    Example:
100
101    .. code-block:: console
102
103        make lib/librte_eal_clean O=mybuild
104
105Install Targets
106---------------
107
108*   Install
109
110    The list of available targets are in $(RTE_SDK)/config (remove the defconfig\_ prefix).
111
112    The GNU standards variables may be used:
113    http://gnu.org/prep/standards/html_node/Directory-Variables.html and
114    http://gnu.org/prep/standards/html_node/DESTDIR.html
115
116    Example:
117
118    .. code-block:: console
119
120        make install DESTDIR=myinstall prefix=/usr
121
122Test Targets
123------------
124
125*   test
126
127    Launch automatic tests for a build directory specified using O=mybuilddir.
128    It is optional, the default output directory is build.
129
130    Example:
131
132    .. code-block:: console
133
134        make test O=mybuild
135
136Documentation Targets
137---------------------
138
139*   doc
140
141    Generate the documentation (API and guides).
142
143*   doc-api-html
144
145    Generate the Doxygen API documentation in html.
146
147*   doc-guides-html
148
149    Generate the guides documentation in html.
150
151*   doc-guides-pdf
152
153    Generate the guides documentation in pdf.
154
155
156Deps Targets
157------------
158
159*   depdirs
160
161    This target is implicitly called by make config.
162    Typically, there is no need for a user to call it,
163    except if DEPDIRS-y variables have been updated in Makefiles.
164    It will generate the file  $(RTE_OUTPUT)/.depdirs.
165
166    Example:
167
168    .. code-block:: console
169
170        make depdirs O=mybuild
171
172*   depgraph
173
174    This command generates a dot graph of dependencies.
175    It can be displayed to debug circular dependency issues, or just to understand the dependencies.
176
177    Example:
178
179    .. code-block:: console
180
181        make depgraph O=mybuild > /tmp/graph.dot && dotty /tmp/ graph.dot
182
183Misc Targets
184------------
185
186*   help
187
188    Show a quick help.
189
190Other Useful Command-line Variables
191-----------------------------------
192
193The following variables can be specified on the command line:
194
195*   V=
196
197    Enable verbose build (show full compilation command line, and some intermediate commands).
198
199*   D=
200
201    Enable dependency debugging. This provides some useful information about why a target is built or not.
202
203*   EXTRA_CFLAGS=, EXTRA_LDFLAGS=, EXTRA_LDLIBS=, EXTRA_ASFLAGS=, EXTRA_CPPFLAGS=
204
205    Append specific compilation, link or asm flags.
206
207*   CROSS=
208
209    Specify a cross toolchain header that will prefix all gcc/binutils applications. This only works when using gcc.
210
211Make in a Build Directory
212-------------------------
213
214All targets described above are called from the SDK root $(RTE_SDK).
215It is possible to run the same Makefile targets inside the build directory.
216For instance, the following command:
217
218.. code-block:: console
219
220    cd $(RTE_SDK)
221    make config O=mybuild T=x86_64-native-linuxapp-gcc
222    make O=mybuild
223
224is equivalent to:
225
226.. code-block:: console
227
228    cd $(RTE_SDK)
229    make config O=mybuild T=x86_64-native-linuxapp-gcc
230    cd mybuild
231
232    # no need to specify O= now
233    make
234
235Compiling for Debug
236-------------------
237
238To compile the DPDK and sample applications with debugging information included and the optimization level set to 0,
239the EXTRA_CFLAGS environment variable should be set before compiling as follows:
240
241.. code-block:: console
242
243    export EXTRA_CFLAGS='-O0 -g'
244