1.. SPDX-License-Identifier: GPL-2.0
2
3=============
4Xen Makefiles
5=============
6
7Documentation for the build system of Xen, found in xen.git/xen/.
8
9Makefile files
10==============
11
12Description of the syntax that can be used in most Makefiles named
13'Makefile'. ('xen/Makefile' isn't part of the description.)
14
15'Makefile's are consumed by 'Rules.mk' when building.
16
17Goal definitions
18----------------
19
20	Goal definitions are the main part (heart) of the Makefile.
21	These lines define the files to be built, any special compilation
22	options, and any subdirectories to be entered recursively.
23
24	The most simple makefile contains one line:
25
26	Example::
27
28		obj-y += foo.o
29
30	This tells the build system that there is one object in that
31	directory, named foo.o. foo.o will be built from foo.c or foo.S.
32
33	The following pattern is often used to have object selected
34	depending on the configuration:
35
36	Example::
37
38		obj-$(CONFIG_FOO) += foo.o
39
40	$(CONFIG_FOO) can evaluates to y.
41	If CONFIG_FOO is not y, then the file will not be compiled nor linked.
42
43Descending down in directories
44------------------------------
45
46	A Makefile is only responsible for building objects in its own
47	directory. Files in subdirectories should be taken care of by
48	Makefiles in these subdirs. The build system will automatically
49	invoke make recursively in subdirectories, provided you let it know of
50	them.
51
52	To do so, obj-y is used.
53	acpi lives in a separate directory, and the Makefile present in
54	drivers/ tells the build system to descend down using the following
55	assignment.
56
57	Example::
58
59		#drivers/Makefile
60		obj-$(CONFIG_ACPI) += acpi/
61
62	If CONFIG_ACPI is set to 'y'
63	the corresponding obj- variable will be set, and the build system
64	will descend down in the apci directory.
65	The build system only uses this information to decide that it needs
66	to visit the directory, it is the Makefile in the subdirectory that
67	specifies what is modular and what is built-in.
68
69	It is good practice to use a `CONFIG_` variable when assigning directory
70	names. This allows the build system to totally skip the directory if the
71	corresponding `CONFIG_` option is 'y'.
72
73Compilation flags
74-----------------
75
76    CFLAGS-y and AFLAGS-y
77	These two flags apply only to the makefile in which they
78	are assigned. They are used for all the normal cc, as and ld
79	invocations happening during a recursive build.
80
81	$(CFLAGS-y) is necessary because the top Makefile owns the
82	variable $(XEN_CFLAGS) and uses it for compilation flags for the
83	entire tree. And the variable $(CFLAGS) is modified by Config.mk
84	which evaluated in every subdirs.
85
86	CFLAGS-y specifies options for compiling with $(CC).
87	AFLAGS-y specifies assembler options.
88
89
90Build system infrastructure
91===========================
92
93This chapter describe some of the macro used when building Xen.
94
95Macros
96------
97
98
99    if_changed
100	if_changed is the infrastructure used for the following commands.
101
102	Usage::
103
104		target: source(s) FORCE
105			$(call if_changed,ld/objcopy/...)
106
107	When the rule is evaluated, it is checked to see if any files
108	need an update, or the command line has changed since the last
109	invocation. The latter will force a rebuild if any options
110	to the executable have changed.
111	Any target that utilises if_changed must be listed in $(targets),
112	otherwise the command line check will fail, and the target will
113	always be built.
114	if_changed may be used in conjunction with custom commands as
115	defined in "Custom commands".
116
117	Note: It is a typical mistake to forget the FORCE prerequisite.
118	Another common pitfall is that whitespace is sometimes
119	significant; for instance, the below will fail (note the extra space
120	after the comma)::
121
122		target: source(s) FORCE
123
124	**WRONG!**	$(call if_changed, ld/objcopy/...)
125
126	Note:
127		if_changed should not be used more than once per target.
128		It stores the executed command in a corresponding .cmd file
129		and multiple calls would result in overwrites and unwanted
130		results when the target is up to date and only the tests on
131		changed commands trigger execution of commands.
132
133    ld
134	Link target.
135
136	Example::
137
138		targets += setup setup.o bootsect bootsect.o
139		$(obj)/setup $(obj)/bootsect: %: %.o FORCE
140			$(call if_changed,ld)
141
142	$(targets) are assigned all potential targets, by which the build
143	system knows the targets and will:
144
145		1) check for commandline changes
146
147	The ": %: %.o" part of the prerequisite is a shorthand that
148	frees us from listing the setup.o and bootsect.o files.
149
150	Note:
151		It is a common mistake to forget the "targets :=" assignment,
152		resulting in the target file being recompiled for no
153		obvious reason.
154
155    objcopy
156	Copy binary. Uses OBJCOPYFLAGS usually specified in
157	arch/$(ARCH)/Makefile.
158
159Custom commands
160---------------
161
162	When the build system is executing with V=0, then only
163	a shorthand of a command is normally displayed.
164	To enable this behaviour for custom commands, two variables are
165	required to be set::
166
167		quiet_cmd_<command>	- what shall be echoed
168		      cmd_<command>	- the command to execute
169
170	Example::
171
172		# xsm/flask/Makefile
173		mkflask := policy/mkflask.sh
174		quiet_cmd_mkflask = MKFLASK $@
175		cmd_mkflask = $(CONFIG_SHELL) $(mkflask) $(AWK) include \
176			$(FLASK_H_DEPEND)
177
178		include/flask.h: $(FLASK_H_DEPEND) $(mkflask) FORCE
179			$(call if_changed,mkflask)
180
181	When updating the include/flask.h target, the line:
182
183		MKFLASK include/flask.h
184
185	will be displayed with "make V=0". (V=0 is the default)
186