blob: 034339f405d64f6e85d12e0e95ac115bb3b41f3b [file] [log] [blame]
Dave Barach8e83bcb2018-08-09 16:12:20 -04001Introduction to build-root/Makefile
2===================================
3
4The vpp build system consists of a top-level Makefile, a data-driven
5build-root/Makefile, and a set of makefile fragments. The various parts
6come together as the result of a set of well-thought-out conventions.
7
8This section describes build-root/Makefile in some detail.
9
10Repository Groups and Source Paths
11----------------------------------
12
13Current vpp workspaces comprise a single repository group. The file
14.../build-root/build-config.mk defines a key variable called
15SOURCE\_PATH. The SOURCE\_PATH variable names the set of repository
16groups. At the moment, there is only one repository group.
17
18Single pass build system, dependencies and components
19-----------------------------------------------------
20
21The vpp build system caters to components built with GNU autoconf /
22automake. Adding such components is a simple process. Dealing with
23components which use BSD-style raw Makefiles is a more difficult.
24Dealing with toolchain components such as gcc, glibc, and binutils can
25be considerably more complicated.
26
27The vpp build system is a **single-pass** build system. A partial order
28must exist for any set of components: the set of (a before b) tuples
29must resolve to an ordered list. If you create a circular dependency of
30the form; (a,b) (b,c) (c,a), gmake will try to build the target list,
31but theres a 0.0% chance that the results will be pleasant. Cut-n-paste
32mistakes in .../build-data/packages/.mk can produce confusing failures.
33
34In a single-pass build system, its best to separate libraries and
35applications which instantiate them. For example, if vpp depends on
36libfoo.a, and myapp depends on both vpp and libfoo.a, it's best to place
37libfoo.a and myapp in separate components. The build system will build
38libfoo.a, vpp, and then (as a separate component) myapp. If you try to
39build libfoo.a and myapp from the same component, it won’t work.
40
41If you absolutely, positively insist on having myapp and libfoo.a in the
42same source tree, you can create a pseudo-component in a separate .mk
43file in the .../build-data/packages/ directory. Define the code
44phoneycomponent\_source = realcomponent, and provide manual
45configure/build/install targets.
46
47Separate components for myapp, libfoo.a, and vpp is the best and easiest
48solution. However, the “mumble\_source = realsource” degree of freedom
49exists to solve intractable circular dependencies, such as: to build
50gcc-bootstrap, followed by glibc, followed by “real” gcc/g++ [which
51depends on glibc too].
52
53.../build-root
54--------------
55
56The .../build-root directory contains the repository group specification
57build-config.mk, the main Makefile, and the system-wide set of
58autoconf/automake variable overrides in config.site. We'll describe
59these files in some detail. To be clear about expectations: the main
60Makefile and config.site file are subtle and complex. It's unlikely that
61you'll need or want to modify them. Poorly planned changes in either
62place typically cause bugs that are difficult to solve.
63
64.../build-root/build-config.mk
65------------------------------
66
67As described above, the build-config.mk file is straightforward: it sets
68the make variable SOURCE\_PATH to a list of repository group absolute
69paths.
70
71The SOURCE\_PATH variable If you choose to move a workspace, make sure
72to modify the paths defined by the SOURCE\_PATH variable. Those paths
73need to match changes you make in the workspace paths. For example, if
74you place the vpp directory in the workspace of a user named jsmith, you
75might change the SOURCE\_PATH to:
76
77SOURCE\_PATH = /home/jsmithuser/workspace/vpp
78
79The "out of the box" setting should work 99.5% of the time:
80
81::
82
83 SOURCE_PATH = $(CURDIR)/..
84
85.../vpp/build-root/Makefile
86---------------------------
87
88The main Makefile is complex in a number of dimensions. If you think you
89need to modify it, it's a good idea to do some research, or ask for
90advice before you change it.
91
92The main Makefile was organized and designed to provide the following
93characteristics: excellent performance, accurate dependency processing,
94cache enablement, timestamp optimizations, git integration,
95extensibility, builds with cross-compilation tool chains, and builds
96with embedded Linux distributions.
97
98If you really need to do so, you can build double-cross tools with it,
99with a minimum amount of fuss. For example, you could: compile gdb on
100x86\_64, to run on PowerPC, to debug the Xtensa instruction set.
101
102The PLATFORM variable
103---------------------
104
105The PLATFORM make/environment variable controls a number of important
106characteristics, primarily:
107
108- CPU architecture
109- The list of images to build.
110
111With respect to .../build-root/Makefile, the list of images to build is
112specified by the target. For example:
113
114::
115
116 make PLATFORM=vpp TAG=vpp_debug install-deb
117
118builds vpp debug Debian packages.
119
120The main Makefile interprets $PLATFORM by attempting to "-include" the
121file /build-data/platforms.mk:
122
123::
124
125 $(foreach d,$(FULL_SOURCE_PATH), \
126 $(eval -include $(d)/platforms.mk))
127
128By convention, we don't define **platforms** in the
129...//build-data/platforms.mk file.
130
131In the vpp case, we search for platform definition makefile fragments in
132.../vpp/build-data/platforms.mk, as follows:
133
134::
135
136 $(foreach d,$(SOURCE_PATH_BUILD_DATA_DIRS), \
137 $(eval -include $(d)/platforms/*.mk))
138
139With vpp, which uses the "vpp" platform as discussed above, we end up
140"-include"-ing .../vpp/build-data/platforms/vpp.mk.
141
142The platform-specific .mk fragment
143----------------------------------
144
145Here are the contents of .../build-data/platforms/vpp.mk:
146
147::
148
149 MACHINE=$(shell uname -m)
150
151 vpp_arch = native
152 ifeq ($(TARGET_PLATFORM),thunderx)
153 vpp_dpdk_target = arm64-thunderx-linuxapp-gcc
154 endif
155 vpp_native_tools = vppapigen
156
157 vpp_uses_dpdk = yes
158
Paul Vinciguerra7fa3dd22019-10-27 17:28:10 -0400159 # Uncomment to enable building unit tests
Dave Barach8e83bcb2018-08-09 16:12:20 -0400160 # vpp_enable_tests = yes
161
Damjan Marion8c1afb52020-10-16 15:28:47 +0200162 vpp_root_packages = vpp
Dave Barach8e83bcb2018-08-09 16:12:20 -0400163
164 # DPDK configuration parameters
165 # vpp_uses_dpdk_mlx4_pmd = yes
166 # vpp_uses_dpdk_mlx5_pmd = yes
167 # vpp_uses_external_dpdk = yes
168 # vpp_dpdk_inc_dir = /usr/include/dpdk
169 # vpp_dpdk_lib_dir = /usr/lib
170 # vpp_dpdk_shared_lib = yes
171
172 # Use '--without-libnuma' for non-numa aware architecture
173 # Use '--enable-dlmalloc' to use dlmalloc instead of mheap
174 vpp_configure_args_vpp = --enable-dlmalloc
175 sample-plugin_configure_args_vpp = --enable-dlmalloc
176
177 # load balancer plugin is not portable on 32 bit platform
178 ifeq ($(MACHINE),i686)
179 vpp_configure_args_vpp += --disable-lb-plugin
180 endif
181
Neale Ranns2a81d9a2021-01-20 09:03:30 +0000182 vpp_debug_TAG_CFLAGS = -g -O0 -DCLIB_DEBUG -D_FORTIFY_SOURCE=2 \
Dave Barach8e83bcb2018-08-09 16:12:20 -0400183 -fstack-protector-all -fPIC -Werror
Neale Ranns2a81d9a2021-01-20 09:03:30 +0000184 vpp_debug_TAG_CXXFLAGS = -g -O0 -DCLIB_DEBUG -D_FORTIFY_SOURCE=2 \
Dave Barach8e83bcb2018-08-09 16:12:20 -0400185 -fstack-protector-all -fPIC -Werror
Neale Ranns2a81d9a2021-01-20 09:03:30 +0000186 vpp_debug_TAG_LDFLAGS = -g -O0 -DCLIB_DEBUG -D_FORTIFY_SOURCE=2 \
Dave Barach8e83bcb2018-08-09 16:12:20 -0400187 -fstack-protector-all -fPIC -Werror
188
Neale Ranns2a81d9a2021-01-20 09:03:30 +0000189 vpp_TAG_CFLAGS = -g -O2 -D_FORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror
190 vpp_TAG_CXXFLAGS = -g -O2 -D_FORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror
191 vpp_TAG_LDFLAGS = -g -O2 -D_FORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror -pie -Wl,-z,now
Dave Barach8e83bcb2018-08-09 16:12:20 -0400192
Neale Ranns2a81d9a2021-01-20 09:03:30 +0000193 vpp_clang_TAG_CFLAGS = -g -O2 -D_FORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror
194 vpp_clang_TAG_LDFLAGS = -g -O2 -D_FORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror
Dave Barach8e83bcb2018-08-09 16:12:20 -0400195
196 vpp_gcov_TAG_CFLAGS = -g -O0 -DCLIB_DEBUG -fPIC -Werror -fprofile-arcs -ftest-coverage
197 vpp_gcov_TAG_LDFLAGS = -g -O0 -DCLIB_DEBUG -fPIC -Werror -coverage
198
199 vpp_coverity_TAG_CFLAGS = -g -O2 -fPIC -Werror -D__COVERITY__
200 vpp_coverity_TAG_LDFLAGS = -g -O2 -fPIC -Werror -D__COVERITY__
201
202Note the following variable settings:
203
204- The variable \_arch sets the CPU architecture used to build the
205 per-platform cross-compilation toolchain. With the exception of the
206 "native" architecture - used in our example - the vpp build system
207 produces cross-compiled binaries.
208
209- The variable \_native\_tools lists the required set of self-compiled
210 build tools.
211
212- The variable \_root\_packages lists the set of images to build when
213 specifying the target: make PLATFORM= TAG= [install-deb \|
214 install-rpm].
215
216The TAG variable
217----------------
218
219The TAG variable indirectly sets CFLAGS and LDFLAGS, as well as the
220build and install directory names in the .../vpp/build-root directory.
221See definitions above.
222
223Important targets build-root/Makefile
224-------------------------------------
225
226The main Makefile and the various makefile fragments implement the
227following user-visible targets:
228
229+------------------+----------------------+--------------------------------------------------------------------------------------+
230| Target | ENV Variable Settings| Notes |
231| | | |
232+==================+======================+======================================================================================+
233| foo | bar | mumble |
234+------------------+----------------------+--------------------------------------------------------------------------------------+
235| bootstrap-tools | none | Builds the set of native tools needed by the vpp build system to |
236| | | build images. Example: vppapigen. In a full cross compilation case might include |
237| | | include "make", "git", "find", and "tar |
238+------------------+----------------------+--------------------------------------------------------------------------------------+
239| install-tools | PLATFORM | Builds the tool chain for the indicated <platform>. Not used in vpp builds |
240+------------------+----------------------+--------------------------------------------------------------------------------------+
241| distclean | none | Roto-rooters everything in sight: toolchains, images, and so forth. |
242+------------------+----------------------+--------------------------------------------------------------------------------------+
243| install-deb | PLATFORM and TAG | Build Debian packages comprising components listed in <platform>_root_packages, |
244| | | using compile / link options defined by TAG. |
245+------------------+----------------------+--------------------------------------------------------------------------------------+
246| install-rpm | PLATFORM and TAG | Build RPMs comprising components listed in <platform>_root_packages, |
247| | | using compile / link options defined by TAG. |
248+------------------+----------------------+--------------------------------------------------------------------------------------+
249
250Additional build-root/Makefile environment variable settings
251------------------------------------------------------------
252
253These variable settings may be of use:
254
255+----------------------+------------------------------------------------------------------------------------------------------------+
256| ENV Variable | Notes |
257+======================+======================+=====================================================================================+
258| BUILD_DEBUG=vx | Directs Makefile et al. to make a good-faith effort to show what's going on in excruciating detail. |
259| | Use it as follows: "make ... BUILD_DEBUG=vx". Fairly effective in Makefile debug situations. |
260+----------------------+------------------------------------------------------------------------------------------------------------+
261| V=1 | print detailed cc / ld command lines. Useful for discovering if -DFOO=11 is in the command line or not |
262+----------------------+------------------------------------------------------------------------------------------------------------+
263| CC=mygcc | Override the configured C-compiler |
264+----------------------+------------------------------------------------------------------------------------------------------------+
265
266.../build-root/config.site
267--------------------------
268
269The contents of .../build-root/config.site override individual autoconf /
270automake default variable settings. Here are a few sample settings related to
271building a full toolchain:
272
273::
274
275 # glibc needs these setting for cross compiling
276 libc_cv_forced_unwind=yes
277 libc_cv_c_cleanup=yes
278 libc_cv_ssp=no
279
280Determining the set of variables which need to be overridden, and the
281override values is a matter of trial and error. It should be
282unnecessary to modify this file for use with fd.io vpp.
283
284.../build-data/platforms.mk
285---------------------------
286
287Each repo group includes the platforms.mk file, which is included by
288the main Makefile. The vpp/build-data/platforms.mk file is not terribly
289complex. As of this writing, .../build-data/platforms.mk file accomplishes two
290tasks.
291
292First, it includes vpp/build-data/platforms/\*.mk:
293
294::
295
296 # Pick up per-platform makefile fragments
297 $(foreach d,$(SOURCE_PATH_BUILD_DATA_DIRS), \
298 $(eval -include $(d)/platforms/*.mk))
299
300This collects the set of platform definition makefile fragments, as discussed above.
301
302Second, platforms.mk implements the user-visible "install-deb" target.
303
304.../build-data/packages/\*.mk
305-----------------------------
306
307Each component needs a makefile fragment in order for the build system
308to recognize it. The per-component makefile fragments vary
309considerably in complexity. For a component built with GNU autoconf /
310automake which does not depend on other components, the make fragment
311can be empty. See .../build-data/packages/vpp.mk for an uncomplicated
312but fully realistic example.
313
314Here are some of the important variable settings in per-component makefile fragments:
315
316+----------------------+------------------------------------------------------------------------------------------------------------+
317| Variable | Notes |
318+======================+======================+=====================================================================================+
319| xxx_configure_depend | Lists the set of component build dependencies for the xxx component. In plain English: don't try to |
320| | configure this component until you've successfully built the indicated targets. Almost always, |
321| | xxx_configure_depend will list a set of "yyy-install" targets. Note the pattern: |
322| | "variable names contain underscores, make target names contain hyphens" |
323+----------------------+------------------------------------------------------------------------------------------------------------+
324| xxx_configure_args | (optional) Lists any additional arguments to pass to the xxx component "configure" script. |
325| | The main Makefile %-configure rule adds the required settings for --libdir, --prefix, and |
326| | --host (when cross-compiling) |
327+----------------------+------------------------------------------------------------------------------------------------------------+
328| xxx_CPPFLAGS | Adds -I stanzas to CPPFLAGS for components upon which xxx depends. |
329| | Almost invariably "xxx_CPPFLAGS = $(call installed_includes_fn, dep1 dep2 dep3)", where dep1, dep2, and |
330| | dep3 are listed in xxx_configure_depend. It is bad practice to set "-g -O3" here. Those settings |
331| | belong in a TAG. |
332+----------------------+------------------------------------------------------------------------------------------------------------+
333| xxx_LDFLAGS | Adds -Wl,-rpath -Wl,depN stanzas to LDFLAGS for components upon which xxx depends. |
334| | Almost invariably "xxx_LDFLAGS = $(call installed_lib_fn, dep1 dep2 dep3)", where dep1, dep2, and |
335| | dep3 are listed in xxx_configure_depend. It is bad manners to set "-liberty-or-death" here. |
336| | Those settings belong in Makefile.am. |
337+----------------------+------------------------------------------------------------------------------------------------------------+
338
339When dealing with "irritating" components built with raw Makefiles
340which only work when building in the source tree, we use a specific
341strategy in the xxx.mk file.
342
343The strategy is simple for those components: We copy the source tree
344into .../vpp/build-root/build-xxx. This works, but completely defeats
345dependency processing. This strategy is acceptable only for 3rd party
346software which won't need extensive (or preferably any) modifications.
347
348Take a look at .../vpp/build-data/packages/dpdk.mk. When invoked, the
349dpdk_configure variable copies source code into $(PACKAGE_BUILD_DIR),
350and performs the BSD equivalent of "autoreconf -i -f" to configure the
351build area. The rest of the file is similar: a bunch of hand-rolled
352glue code which manages to make the dpdk act like a good vpp build
353citizen even though it is not.