1======================
2Linux Kernel Makefiles
3======================
4
5This document describes the Linux kernel Makefiles.
6
7.. Table of Contents
8
9	=== 1 Overview
10	=== 2 Who does what
11	=== 3 The kbuild files
12	   --- 3.1 Goal definitions
13	   --- 3.2 Built-in object goals - obj-y
14	   --- 3.3 Loadable module goals - obj-m
15	   --- 3.4 <deleted>
16	   --- 3.5 Library file goals - lib-y
17	   --- 3.6 Descending down in directories
18	   --- 3.7 Non-builtin vmlinux targets - extra-y
19	   --- 3.8 Always built goals - always-y
20	   --- 3.9 Compilation flags
21	   --- 3.10 Dependency tracking
22	   --- 3.11 Custom Rules
23	   --- 3.12 Command change detection
24	   --- 3.13 $(CC) support functions
25	   --- 3.14 $(LD) support functions
26	   --- 3.15 Script Invocation
27
28	=== 4 Host Program support
29	   --- 4.1 Simple Host Program
30	   --- 4.2 Composite Host Programs
31	   --- 4.3 Using C++ for host programs
32	   --- 4.4 Using Rust for host programs
33	   --- 4.5 Controlling compiler options for host programs
34	   --- 4.6 When host programs are actually built
35
36	=== 5 Userspace Program support
37	   --- 5.1 Simple Userspace Program
38	   --- 5.2 Composite Userspace Programs
39	   --- 5.3 Controlling compiler options for userspace programs
40	   --- 5.4 When userspace programs are actually built
41
42	=== 6 Kbuild clean infrastructure
43
44	=== 7 Architecture Makefiles
45	   --- 7.1 Set variables to tweak the build to the architecture
46	   --- 7.2 Add prerequisites to archheaders
47	   --- 7.3 Add prerequisites to archprepare
48	   --- 7.4 List directories to visit when descending
49	   --- 7.5 Architecture-specific boot images
50	   --- 7.6 Building non-kbuild targets
51	   --- 7.7 Commands useful for building a boot image
52	   --- 7.8 <deleted>
53	   --- 7.9 Preprocessing linker scripts
54	   --- 7.10 Generic header files
55	   --- 7.11 Post-link pass
56
57	=== 8 Kbuild syntax for exported headers
58		--- 8.1 no-export-headers
59		--- 8.2 generic-y
60		--- 8.3 generated-y
61		--- 8.4 mandatory-y
62
63	=== 9 Kbuild Variables
64	=== 10 Makefile language
65	=== 11 Credits
66	=== 12 TODO
67
681 Overview
69==========
70
71The Makefiles have five parts::
72
73	Makefile                    the top Makefile.
74	.config                     the kernel configuration file.
75	arch/$(SRCARCH)/Makefile    the arch Makefile.
76	scripts/Makefile.*          common rules etc. for all kbuild Makefiles.
77	kbuild Makefiles            exist in every subdirectory
78
79The top Makefile reads the .config file, which comes from the kernel
80configuration process.
81
82The top Makefile is responsible for building two major products: vmlinux
83(the resident kernel image) and modules (any module files).
84It builds these goals by recursively descending into the subdirectories of
85the kernel source tree.
86The list of subdirectories which are visited depends upon the kernel
87configuration. The top Makefile textually includes an arch Makefile
88with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies
89architecture-specific information to the top Makefile.
90
91Each subdirectory has a kbuild Makefile which carries out the commands
92passed down from above. The kbuild Makefile uses information from the
93.config file to construct various file lists used by kbuild to build
94any built-in or modular targets.
95
96scripts/Makefile.* contains all the definitions/rules etc. that
97are used to build the kernel based on the kbuild makefiles.
98
99
1002 Who does what
101===============
102
103People have four different relationships with the kernel Makefiles.
104
105*Users* are people who build kernels.  These people type commands such as
106"make menuconfig" or "make".  They usually do not read or edit
107any kernel Makefiles (or any other source files).
108
109*Normal developers* are people who work on features such as device
110drivers, file systems, and network protocols.  These people need to
111maintain the kbuild Makefiles for the subsystem they are
112working on.  In order to do this effectively, they need some overall
113knowledge about the kernel Makefiles, plus detailed knowledge about the
114public interface for kbuild.
115
116*Arch developers* are people who work on an entire architecture, such
117as sparc or ia64.  Arch developers need to know about the arch Makefile
118as well as kbuild Makefiles.
119
120*Kbuild developers* are people who work on the kernel build system itself.
121These people need to know about all aspects of the kernel Makefiles.
122
123This document is aimed towards normal developers and arch developers.
124
125
1263 The kbuild files
127==================
128
129Most Makefiles within the kernel are kbuild Makefiles that use the
130kbuild infrastructure. This chapter introduces the syntax used in the
131kbuild makefiles.
132The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
133be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
134file will be used.
135
136Section 3.1 "Goal definitions" is a quick intro; further chapters provide
137more details, with real examples.
138
1393.1 Goal definitions
140--------------------
141
142	Goal definitions are the main part (heart) of the kbuild Makefile.
143	These lines define the files to be built, any special compilation
144	options, and any subdirectories to be entered recursively.
145
146	The most simple kbuild makefile contains one line:
147
148	Example::
149
150		obj-y += foo.o
151
152	This tells kbuild that there is one object in that directory, named
153	foo.o. foo.o will be built from foo.c or foo.S.
154
155	If foo.o shall be built as a module, the variable obj-m is used.
156	Therefore the following pattern is often used:
157
158	Example::
159
160		obj-$(CONFIG_FOO) += foo.o
161
162	$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
163	If CONFIG_FOO is neither y nor m, then the file will not be compiled
164	nor linked.
165
1663.2 Built-in object goals - obj-y
167---------------------------------
168
169	The kbuild Makefile specifies object files for vmlinux
170	in the $(obj-y) lists.  These lists depend on the kernel
171	configuration.
172
173	Kbuild compiles all the $(obj-y) files.  It then calls
174	"$(AR) rcSTP" to merge these files into one built-in.a file.
175	This is a thin archive without a symbol table. It will be later
176	linked into vmlinux by scripts/link-vmlinux.sh
177
178	The order of files in $(obj-y) is significant.  Duplicates in
179	the lists are allowed: the first instance will be linked into
180	built-in.a and succeeding instances will be ignored.
181
182	Link order is significant, because certain functions
183	(module_init() / __initcall) will be called during boot in the
184	order they appear. So keep in mind that changing the link
185	order may e.g. change the order in which your SCSI
186	controllers are detected, and thus your disks are renumbered.
187
188	Example::
189
190		#drivers/isdn/i4l/Makefile
191		# Makefile for the kernel ISDN subsystem and device drivers.
192		# Each configuration option enables a list of files.
193		obj-$(CONFIG_ISDN_I4L)         += isdn.o
194		obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
195
1963.3 Loadable module goals - obj-m
197---------------------------------
198
199	$(obj-m) specifies object files which are built as loadable
200	kernel modules.
201
202	A module may be built from one source file or several source
203	files. In the case of one source file, the kbuild makefile
204	simply adds the file to $(obj-m).
205
206	Example::
207
208		#drivers/isdn/i4l/Makefile
209		obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
210
211	Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
212
213	If a kernel module is built from several source files, you specify
214	that you want to build a module in the same way as above; however,
215	kbuild needs to know which object files you want to build your
216	module from, so you have to tell it by setting a $(<module_name>-y)
217	variable.
218
219	Example::
220
221		#drivers/isdn/i4l/Makefile
222		obj-$(CONFIG_ISDN_I4L) += isdn.o
223		isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
224
225	In this example, the module name will be isdn.o. Kbuild will
226	compile the objects listed in $(isdn-y) and then run
227	"$(LD) -r" on the list of these files to generate isdn.o.
228
229	Due to kbuild recognizing $(<module_name>-y) for composite objects,
230	you can use the value of a `CONFIG_` symbol to optionally include an
231	object file as part of a composite object.
232
233	Example::
234
235		#fs/ext2/Makefile
236	        obj-$(CONFIG_EXT2_FS) += ext2.o
237		ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
238			  namei.o super.o symlink.o
239	        ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \
240						xattr_trusted.o
241
242	In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
243	part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
244	evaluates to 'y'.
245
246	Note: Of course, when you are building objects into the kernel,
247	the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
248	kbuild will build an ext2.o file for you out of the individual
249	parts and then link this into built-in.a, as you would expect.
250
2513.5 Library file goals - lib-y
252------------------------------
253
254	Objects listed with obj-* are used for modules, or
255	combined in a built-in.a for that specific directory.
256	There is also the possibility to list objects that will
257	be included in a library, lib.a.
258	All objects listed with lib-y are combined in a single
259	library for that directory.
260	Objects that are listed in obj-y and additionally listed in
261	lib-y will not be included in the library, since they will
262	be accessible anyway.
263	For consistency, objects listed in lib-m will be included in lib.a.
264
265	Note that the same kbuild makefile may list files to be built-in
266	and to be part of a library. Therefore the same directory
267	may contain both a built-in.a and a lib.a file.
268
269	Example::
270
271		#arch/x86/lib/Makefile
272		lib-y    := delay.o
273
274	This will create a library lib.a based on delay.o. For kbuild to
275	actually recognize that there is a lib.a being built, the directory
276	shall be listed in libs-y.
277
278	See also "7.4 List directories to visit when descending".
279
280	Use of lib-y is normally restricted to `lib/` and `arch/*/lib`.
281
2823.6 Descending down in directories
283----------------------------------
284
285	A Makefile is only responsible for building objects in its own
286	directory. Files in subdirectories should be taken care of by
287	Makefiles in these subdirs. The build system will automatically
288	invoke make recursively in subdirectories, provided you let it know of
289	them.
290
291	To do so, obj-y and obj-m are used.
292	ext2 lives in a separate directory, and the Makefile present in fs/
293	tells kbuild to descend down using the following assignment.
294
295	Example::
296
297		#fs/Makefile
298		obj-$(CONFIG_EXT2_FS) += ext2/
299
300	If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
301	the corresponding obj- variable will be set, and kbuild will descend
302	down in the ext2 directory.
303
304	Kbuild uses this information not only to decide that it needs to visit
305	the directory, but also to decide whether or not to link objects from
306	the directory into vmlinux.
307
308	When Kbuild descends into the directory with 'y', all built-in objects
309	from that directory are combined into the built-in.a, which will be
310	eventually linked into vmlinux.
311
312	When Kbuild descends into the directory with 'm', in contrast, nothing
313	from that directory will be linked into vmlinux. If the Makefile in
314	that directory specifies obj-y, those objects will be left orphan.
315	It is very likely a bug of the Makefile or of dependencies in Kconfig.
316
317	Kbuild also supports dedicated syntax, subdir-y and subdir-m, for
318	descending into subdirectories. It is a good fit when you know they
319	do not contain kernel-space objects at all. A typical usage is to let
320	Kbuild descend into subdirectories to build tools.
321
322	Examples::
323
324		# scripts/Makefile
325		subdir-$(CONFIG_GCC_PLUGINS) += gcc-plugins
326		subdir-$(CONFIG_MODVERSIONS) += genksyms
327		subdir-$(CONFIG_SECURITY_SELINUX) += selinux
328
329	Unlike obj-y/m, subdir-y/m does not need the trailing slash since this
330	syntax is always used for directories.
331
332	It is good practice to use a `CONFIG_` variable when assigning directory
333	names. This allows kbuild to totally skip the directory if the
334	corresponding `CONFIG_` option is neither 'y' nor 'm'.
335
3363.7 Non-builtin vmlinux targets - extra-y
337-----------------------------------------
338
339	extra-y specifies targets which are needed for building vmlinux,
340	but not combined into built-in.a.
341
342	Examples are:
343
344	1) vmlinux linker script
345
346	    The linker script for vmlinux is located at
347	    arch/$(SRCARCH)/kernel/vmlinux.lds
348
349	Example::
350
351		# arch/x86/kernel/Makefile
352		extra-y	+= vmlinux.lds
353
354	$(extra-y) should only contain targets needed for vmlinux.
355
356	Kbuild skips extra-y when vmlinux is apparently not a final goal.
357	(e.g. 'make modules', or building external modules)
358
359	If you intend to build targets unconditionally, always-y (explained
360	in the next section) is the correct syntax to use.
361
3623.8 Always built goals - always-y
363---------------------------------
364
365	always-y specifies targets which are literally always built when
366	Kbuild visits the Makefile.
367
368	Example::
369	  # ./Kbuild
370	  offsets-file := include/generated/asm-offsets.h
371	  always-y += $(offsets-file)
372
3733.9 Compilation flags
374---------------------
375
376    ccflags-y, asflags-y and ldflags-y
377	These three flags apply only to the kbuild makefile in which they
378	are assigned. They are used for all the normal cc, as and ld
379	invocations happening during a recursive build.
380	Note: Flags with the same behaviour were previously named:
381	EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
382	They are still supported but their usage is deprecated.
383
384	ccflags-y specifies options for compiling with $(CC).
385
386	Example::
387
388		# drivers/acpi/acpica/Makefile
389		ccflags-y			:= -Os -D_LINUX -DBUILDING_ACPICA
390		ccflags-$(CONFIG_ACPI_DEBUG)	+= -DACPI_DEBUG_OUTPUT
391
392	This variable is necessary because the top Makefile owns the
393	variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
394	entire tree.
395
396	asflags-y specifies assembler options.
397
398	Example::
399
400		#arch/sparc/kernel/Makefile
401		asflags-y := -ansi
402
403	ldflags-y specifies options for linking with $(LD).
404
405	Example::
406
407		#arch/cris/boot/compressed/Makefile
408		ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
409
410    subdir-ccflags-y, subdir-asflags-y
411	The two flags listed above are similar to ccflags-y and asflags-y.
412	The difference is that the subdir- variants have effect for the kbuild
413	file where they are present and all subdirectories.
414	Options specified using subdir-* are added to the commandline before
415	the options specified using the non-subdir variants.
416
417	Example::
418
419		subdir-ccflags-y := -Werror
420
421    ccflags-remove-y, asflags-remove-y
422	These flags are used to remove particular flags for the compiler,
423	assembler invocations.
424
425	Example::
426
427		ccflags-remove-$(CONFIG_MCOUNT) += -pg
428
429    CFLAGS_$@, AFLAGS_$@
430	CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
431	kbuild makefile.
432
433	$(CFLAGS_$@) specifies per-file options for $(CC).  The $@
434	part has a literal value which specifies the file that it is for.
435
436	CFLAGS_$@ has the higher priority than ccflags-remove-y; CFLAGS_$@
437	can re-add compiler flags that were removed by ccflags-remove-y.
438
439	Example::
440
441		# drivers/scsi/Makefile
442		CFLAGS_aha152x.o =   -DAHA152X_STAT -DAUTOCONF
443
444	This line specify compilation flags for aha152x.o.
445
446	$(AFLAGS_$@) is a similar feature for source files in assembly
447	languages.
448
449	AFLAGS_$@ has the higher priority than asflags-remove-y; AFLAGS_$@
450	can re-add assembler flags that were removed by asflags-remove-y.
451
452	Example::
453
454		# arch/arm/kernel/Makefile
455		AFLAGS_head.o        := -DTEXT_OFFSET=$(TEXT_OFFSET)
456		AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
457		AFLAGS_iwmmxt.o      := -Wa,-mcpu=iwmmxt
458
459
4603.10 Dependency tracking
461------------------------
462
463	Kbuild tracks dependencies on the following:
464
465	1) All prerequisite files (both `*.c` and `*.h`)
466	2) `CONFIG_` options used in all prerequisite files
467	3) Command-line used to compile target
468
469	Thus, if you change an option to $(CC) all affected files will
470	be re-compiled.
471
4723.11 Custom Rules
473-----------------
474
475	Custom rules are used when the kbuild infrastructure does
476	not provide the required support. A typical example is
477	header files generated during the build process.
478	Another example are the architecture-specific Makefiles which
479	need custom rules to prepare boot images etc.
480
481	Custom rules are written as normal Make rules.
482	Kbuild is not executing in the directory where the Makefile is
483	located, so all custom rules shall use a relative
484	path to prerequisite files and target files.
485
486	Two variables are used when defining custom rules:
487
488	$(src)
489	    $(src) is a relative path which points to the directory
490	    where the Makefile is located. Always use $(src) when
491	    referring to files located in the src tree.
492
493	$(obj)
494	    $(obj) is a relative path which points to the directory
495	    where the target is saved. Always use $(obj) when
496	    referring to generated files.
497
498	    Example::
499
500		#drivers/scsi/Makefile
501		$(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
502			$(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
503
504	    This is a custom rule, following the normal syntax
505	    required by make.
506
507	    The target file depends on two prerequisite files. References
508	    to the target file are prefixed with $(obj), references
509	    to prerequisites are referenced with $(src) (because they are not
510	    generated files).
511
512	$(kecho)
513	    echoing information to user in a rule is often a good practice
514	    but when execution "make -s" one does not expect to see any output
515	    except for warnings/errors.
516	    To support this kbuild defines $(kecho) which will echo out the
517	    text following $(kecho) to stdout except if "make -s" is used.
518
519	Example::
520
521		# arch/arm/Makefile
522		$(BOOT_TARGETS): vmlinux
523			$(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@
524			@$(kecho) '  Kernel: $(boot)/$@ is ready'
525
526	When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
527	of a command is normally displayed.
528	To enable this behaviour for custom commands kbuild requires
529	two variables to be set::
530
531		quiet_cmd_<command>	- what shall be echoed
532		      cmd_<command>	- the command to execute
533
534	Example::
535
536		# lib/Makefile
537		quiet_cmd_crc32 = GEN     $@
538		      cmd_crc32 = $< > $@
539
540		$(obj)/crc32table.h: $(obj)/gen_crc32table
541			$(call cmd,crc32)
542
543	When updating the $(obj)/crc32table.h target, the line:
544
545		  GEN     lib/crc32table.h
546
547	will be displayed with "make KBUILD_VERBOSE=0".
548
5493.12 Command change detection
550-----------------------------
551
552	When the rule is evaluated, timestamps are compared between the target
553	and its prerequisite files. GNU Make updates the target when any of the
554	prerequisites is newer than that.
555
556	The target should be rebuilt also when the command line has changed
557	since the last invocation. This is not supported by Make itself, so
558	Kbuild achieves this by a kind of meta-programming.
559
560	if_changed is the macro used for this purpose, in the following form::
561
562		quiet_cmd_<command> = ...
563		      cmd_<command> = ...
564
565		<target>: <source(s)> FORCE
566			$(call if_changed,<command>)
567
568	Any target that utilizes if_changed must be listed in $(targets),
569	otherwise the command line check will fail, and the target will
570	always be built.
571
572	If the target is already listed in the recognized syntax such as
573	obj-y/m, lib-y/m, extra-y/m, always-y/m, hostprogs, userprogs, Kbuild
574	automatically adds it to $(targets). Otherwise, the target must be
575	explicitly added to $(targets).
576
577	Assignments to $(targets) are without $(obj)/ prefix. if_changed may be
578	used in conjunction with custom rules as defined in "3.11 Custom Rules".
579
580	Note: It is a typical mistake to forget the FORCE prerequisite.
581	Another common pitfall is that whitespace is sometimes significant; for
582	instance, the below will fail (note the extra space after the comma)::
583
584		target: source(s) FORCE
585
586	**WRONG!**	$(call if_changed, objcopy)
587
588	Note:
589		if_changed should not be used more than once per target.
590		It stores the executed command in a corresponding .cmd
591		file and multiple calls would result in overwrites and
592		unwanted results when the target is up to date and only the
593		tests on changed commands trigger execution of commands.
594
5953.13 $(CC) support functions
596----------------------------
597
598	The kernel may be built with several different versions of
599	$(CC), each supporting a unique set of features and options.
600	kbuild provides basic support to check for valid options for $(CC).
601	$(CC) is usually the gcc compiler, but other alternatives are
602	available.
603
604    as-option
605	as-option is used to check if $(CC) -- when used to compile
606	assembler (`*.S`) files -- supports the given option. An optional
607	second option may be specified if the first option is not supported.
608
609	Example::
610
611		#arch/sh/Makefile
612		cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
613
614	In the above example, cflags-y will be assigned the option
615	-Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
616	The second argument is optional, and if supplied will be used
617	if first argument is not supported.
618
619    as-instr
620	as-instr checks if the assembler reports a specific instruction
621	and then outputs either option1 or option2
622	C escapes are supported in the test instruction
623	Note: as-instr-option uses KBUILD_AFLAGS for assembler options
624
625    cc-option
626	cc-option is used to check if $(CC) supports a given option, and if
627	not supported to use an optional second option.
628
629	Example::
630
631		#arch/x86/Makefile
632		cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
633
634	In the above example, cflags-y will be assigned the option
635	-march=pentium-mmx if supported by $(CC), otherwise -march=i586.
636	The second argument to cc-option is optional, and if omitted,
637	cflags-y will be assigned no value if first option is not supported.
638	Note: cc-option uses KBUILD_CFLAGS for $(CC) options
639
640   cc-option-yn
641	cc-option-yn is used to check if gcc supports a given option
642	and return 'y' if supported, otherwise 'n'.
643
644	Example::
645
646		#arch/ppc/Makefile
647		biarch := $(call cc-option-yn, -m32)
648		aflags-$(biarch) += -a32
649		cflags-$(biarch) += -m32
650
651	In the above example, $(biarch) is set to y if $(CC) supports the -m32
652	option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
653	and $(cflags-y) will be assigned the values -a32 and -m32,
654	respectively.
655	Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
656
657    cc-disable-warning
658	cc-disable-warning checks if gcc supports a given warning and returns
659	the commandline switch to disable it. This special function is needed,
660	because gcc 4.4 and later accept any unknown -Wno-* option and only
661	warn about it if there is another warning in the source file.
662
663	Example::
664
665		KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)
666
667	In the above example, -Wno-unused-but-set-variable will be added to
668	KBUILD_CFLAGS only if gcc really accepts it.
669
670    gcc-min-version
671	gcc-min-version tests if the value of $(CONFIG_GCC_VERSION) is greater than
672	or equal to the provided value and evaluates to y if so.
673
674	Example::
675
676		cflags-$(call gcc-min-version, 70100) := -foo
677
678	In this example, cflags-y will be assigned the value -foo if $(CC) is gcc and
679	$(CONFIG_GCC_VERSION) is >= 7.1.
680
681    clang-min-version
682	clang-min-version tests if the value of $(CONFIG_CLANG_VERSION) is greater
683	than or equal to the provided value and evaluates to y if so.
684
685	Example::
686
687		cflags-$(call clang-min-version, 110000) := -foo
688
689	In this example, cflags-y will be assigned the value -foo if $(CC) is clang
690	and $(CONFIG_CLANG_VERSION) is >= 11.0.0.
691
692    cc-cross-prefix
693	cc-cross-prefix is used to check if there exists a $(CC) in path with
694	one of the listed prefixes. The first prefix where there exist a
695	prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
696	then nothing is returned.
697	Additional prefixes are separated by a single space in the
698	call of cc-cross-prefix.
699	This functionality is useful for architecture Makefiles that try
700	to set CROSS_COMPILE to well-known values but may have several
701	values to select between.
702	It is recommended only to try to set CROSS_COMPILE if it is a cross
703	build (host arch is different from target arch). And if CROSS_COMPILE
704	is already set then leave it with the old value.
705
706	Example::
707
708		#arch/m68k/Makefile
709		ifneq ($(SUBARCH),$(ARCH))
710		        ifeq ($(CROSS_COMPILE),)
711		               CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
712			endif
713		endif
714
7153.14 $(LD) support functions
716----------------------------
717
718    ld-option
719	ld-option is used to check if $(LD) supports the supplied option.
720	ld-option takes two options as arguments.
721	The second argument is an optional option that can be used if the
722	first option is not supported by $(LD).
723
724	Example::
725
726		#Makefile
727		LDFLAGS_vmlinux += $(call ld-option, -X)
728
7293.15 Script invocation
730----------------------
731
732	Make rules may invoke scripts to build the kernel. The rules shall
733	always provide the appropriate interpreter to execute the script. They
734	shall not rely on the execute bits being set, and shall not invoke the
735	script directly. For the convenience of manual script invocation, such
736	as invoking ./scripts/checkpatch.pl, it is recommended to set execute
737	bits on the scripts nonetheless.
738
739	Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL),
740	and $(PYTHON3) to refer to interpreters for the respective
741	scripts.
742
743	Example::
744
745		#Makefile
746		cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \
747			     $(KERNELRELEASE)
748
7494 Host Program support
750======================
751
752Kbuild supports building executables on the host for use during the
753compilation stage.
754Two steps are required in order to use a host executable.
755
756The first step is to tell kbuild that a host program exists. This is
757done utilising the variable "hostprogs".
758
759The second step is to add an explicit dependency to the executable.
760This can be done in two ways. Either add the dependency in a rule,
761or utilise the variable "always-y".
762Both possibilities are described in the following.
763
7644.1 Simple Host Program
765-----------------------
766
767	In some cases there is a need to compile and run a program on the
768	computer where the build is running.
769	The following line tells kbuild that the program bin2hex shall be
770	built on the build host.
771
772	Example::
773
774		hostprogs := bin2hex
775
776	Kbuild assumes in the above example that bin2hex is made from a single
777	c-source file named bin2hex.c located in the same directory as
778	the Makefile.
779
7804.2 Composite Host Programs
781---------------------------
782
783	Host programs can be made up based on composite objects.
784	The syntax used to define composite objects for host programs is
785	similar to the syntax used for kernel objects.
786	$(<executable>-objs) lists all objects used to link the final
787	executable.
788
789	Example::
790
791		#scripts/lxdialog/Makefile
792		hostprogs     := lxdialog
793		lxdialog-objs := checklist.o lxdialog.o
794
795	Objects with extension .o are compiled from the corresponding .c
796	files. In the above example, checklist.c is compiled to checklist.o
797	and lxdialog.c is compiled to lxdialog.o.
798
799	Finally, the two .o files are linked to the executable, lxdialog.
800	Note: The syntax <executable>-y is not permitted for host-programs.
801
8024.3 Using C++ for host programs
803-------------------------------
804
805	kbuild offers support for host programs written in C++. This was
806	introduced solely to support kconfig, and is not recommended
807	for general use.
808
809	Example::
810
811		#scripts/kconfig/Makefile
812		hostprogs     := qconf
813		qconf-cxxobjs := qconf.o
814
815	In the example above the executable is composed of the C++ file
816	qconf.cc - identified by $(qconf-cxxobjs).
817
818	If qconf is composed of a mixture of .c and .cc files, then an
819	additional line can be used to identify this.
820
821	Example::
822
823		#scripts/kconfig/Makefile
824		hostprogs     := qconf
825		qconf-cxxobjs := qconf.o
826		qconf-objs    := check.o
827
8284.4 Using Rust for host programs
829--------------------------------
830
831	Kbuild offers support for host programs written in Rust. However,
832	since a Rust toolchain is not mandatory for kernel compilation,
833	it may only be used in scenarios where Rust is required to be
834	available (e.g. when  ``CONFIG_RUST`` is enabled).
835
836	Example::
837
838		hostprogs     := target
839		target-rust   := y
840
841	Kbuild will compile ``target`` using ``target.rs`` as the crate root,
842	located in the same directory as the ``Makefile``. The crate may
843	consist of several source files (see ``samples/rust/hostprogs``).
844
8454.5 Controlling compiler options for host programs
846--------------------------------------------------
847
848	When compiling host programs, it is possible to set specific flags.
849	The programs will always be compiled utilising $(HOSTCC) passed
850	the options specified in $(KBUILD_HOSTCFLAGS).
851	To set flags that will take effect for all host programs created
852	in that Makefile, use the variable HOST_EXTRACFLAGS.
853
854	Example::
855
856		#scripts/lxdialog/Makefile
857		HOST_EXTRACFLAGS += -I/usr/include/ncurses
858
859	To set specific flags for a single file the following construction
860	is used:
861
862	Example::
863
864		#arch/ppc64/boot/Makefile
865		HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
866
867	It is also possible to specify additional options to the linker.
868
869	Example::
870
871		#scripts/kconfig/Makefile
872		HOSTLDLIBS_qconf := -L$(QTDIR)/lib
873
874	When linking qconf, it will be passed the extra option
875	"-L$(QTDIR)/lib".
876
8774.6 When host programs are actually built
878-----------------------------------------
879
880	Kbuild will only build host-programs when they are referenced
881	as a prerequisite.
882	This is possible in two ways:
883
884	(1) List the prerequisite explicitly in a custom rule.
885
886	Example::
887
888		#drivers/pci/Makefile
889		hostprogs := gen-devlist
890		$(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
891			( cd $(obj); ./gen-devlist ) < $<
892
893	The target $(obj)/devlist.h will not be built before
894	$(obj)/gen-devlist is updated. Note that references to
895	the host programs in custom rules must be prefixed with $(obj).
896
897	(2) Use always-y
898
899	When there is no suitable custom rule, and the host program
900	shall be built when a makefile is entered, the always-y
901	variable shall be used.
902
903	Example::
904
905		#scripts/lxdialog/Makefile
906		hostprogs     := lxdialog
907		always-y      := $(hostprogs)
908
909	Kbuild provides the following shorthand for this:
910
911		hostprogs-always-y := lxdialog
912
913	This will tell kbuild to build lxdialog even if not referenced in
914	any rule.
915
9165 Userspace Program support
917===========================
918
919Just like host programs, Kbuild also supports building userspace executables
920for the target architecture (i.e. the same architecture as you are building
921the kernel for).
922
923The syntax is quite similar. The difference is to use "userprogs" instead of
924"hostprogs".
925
9265.1 Simple Userspace Program
927----------------------------
928
929	The following line tells kbuild that the program bpf-direct shall be
930	built for the target architecture.
931
932	Example::
933
934		userprogs := bpf-direct
935
936	Kbuild assumes in the above example that bpf-direct is made from a
937	single C source file named bpf-direct.c located in the same directory
938	as the Makefile.
939
9405.2 Composite Userspace Programs
941--------------------------------
942
943	Userspace programs can be made up based on composite objects.
944	The syntax used to define composite objects for userspace programs is
945	similar to the syntax used for kernel objects.
946	$(<executable>-objs) lists all objects used to link the final
947	executable.
948
949	Example::
950
951		#samples/seccomp/Makefile
952		userprogs      := bpf-fancy
953		bpf-fancy-objs := bpf-fancy.o bpf-helper.o
954
955	Objects with extension .o are compiled from the corresponding .c
956	files. In the above example, bpf-fancy.c is compiled to bpf-fancy.o
957	and bpf-helper.c is compiled to bpf-helper.o.
958
959	Finally, the two .o files are linked to the executable, bpf-fancy.
960	Note: The syntax <executable>-y is not permitted for userspace programs.
961
9625.3 Controlling compiler options for userspace programs
963-------------------------------------------------------
964
965	When compiling userspace programs, it is possible to set specific flags.
966	The programs will always be compiled utilising $(CC) passed
967	the options specified in $(KBUILD_USERCFLAGS).
968	To set flags that will take effect for all userspace programs created
969	in that Makefile, use the variable userccflags.
970
971	Example::
972
973		# samples/seccomp/Makefile
974		userccflags += -I usr/include
975
976	To set specific flags for a single file the following construction
977	is used:
978
979	Example::
980
981		bpf-helper-userccflags += -I user/include
982
983	It is also possible to specify additional options to the linker.
984
985	Example::
986
987		# net/bpfilter/Makefile
988		bpfilter_umh-userldflags += -static
989
990	When linking bpfilter_umh, it will be passed the extra option -static.
991
992	From command line, :ref:`USERCFLAGS and USERLDFLAGS <userkbuildflags>` will also be used.
993
9945.4 When userspace programs are actually built
995----------------------------------------------
996
997	Kbuild builds userspace programs only when told to do so.
998	There are two ways to do this.
999
1000	(1) Add it as the prerequisite of another file
1001
1002	Example::
1003
1004		#net/bpfilter/Makefile
1005		userprogs := bpfilter_umh
1006		$(obj)/bpfilter_umh_blob.o: $(obj)/bpfilter_umh
1007
1008	$(obj)/bpfilter_umh is built before $(obj)/bpfilter_umh_blob.o
1009
1010	(2) Use always-y
1011
1012	Example::
1013
1014		userprogs := binderfs_example
1015		always-y := $(userprogs)
1016
1017	Kbuild provides the following shorthand for this:
1018
1019		userprogs-always-y := binderfs_example
1020
1021	This will tell Kbuild to build binderfs_example when it visits this
1022	Makefile.
1023
10246 Kbuild clean infrastructure
1025=============================
1026
1027"make clean" deletes most generated files in the obj tree where the kernel
1028is compiled. This includes generated files such as host programs.
1029Kbuild knows targets listed in $(hostprogs), $(always-y), $(always-m),
1030$(always-), $(extra-y), $(extra-) and $(targets). They are all deleted
1031during "make clean". Files matching the patterns "*.[oas]", "*.ko", plus
1032some additional files generated by kbuild are deleted all over the kernel
1033source tree when "make clean" is executed.
1034
1035Additional files or directories can be specified in kbuild makefiles by use of
1036$(clean-files).
1037
1038	Example::
1039
1040		#lib/Makefile
1041		clean-files := crc32table.h
1042
1043When executing "make clean", the file "crc32table.h" will be deleted.
1044Kbuild will assume files to be in the same relative directory as the
1045Makefile.
1046
1047To exclude certain files or directories from make clean, use the
1048$(no-clean-files) variable.
1049
1050Usually kbuild descends down in subdirectories due to "obj-* := dir/",
1051but in the architecture makefiles where the kbuild infrastructure
1052is not sufficient this sometimes needs to be explicit.
1053
1054	Example::
1055
1056		#arch/x86/boot/Makefile
1057		subdir- := compressed
1058
1059The above assignment instructs kbuild to descend down in the
1060directory compressed/ when "make clean" is executed.
1061
1062Note 1: arch/$(SRCARCH)/Makefile cannot use "subdir-", because that file is
1063included in the top level makefile. Instead, arch/$(SRCARCH)/Kbuild can use
1064"subdir-".
1065
1066Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
1067be visited during "make clean".
1068
10697 Architecture Makefiles
1070========================
1071
1072The top level Makefile sets up the environment and does the preparation,
1073before starting to descend down in the individual directories.
1074The top level makefile contains the generic part, whereas
1075arch/$(SRCARCH)/Makefile contains what is required to set up kbuild
1076for said architecture.
1077To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines
1078a few targets.
1079
1080When kbuild executes, the following steps are followed (roughly):
1081
10821) Configuration of the kernel => produce .config
10832) Store kernel version in include/linux/version.h
10843) Updating all other prerequisites to the target prepare:
1085   - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile
10864) Recursively descend down in all directories listed in
1087   init-* core* drivers-* net-* libs-* and build all targets.
1088   - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile.
10895) All object files are then linked and the resulting file vmlinux is
1090   located at the root of the obj tree.
1091   The very first objects linked are listed in scripts/head-object-list.txt.
10926) Finally, the architecture-specific part does any required post processing
1093   and builds the final bootimage.
1094   - This includes building boot records
1095   - Preparing initrd images and the like
1096
1097
10987.1 Set variables to tweak the build to the architecture
1099--------------------------------------------------------
1100
1101    KBUILD_LDFLAGS
1102	Generic $(LD) options
1103
1104	Flags used for all invocations of the linker.
1105	Often specifying the emulation is sufficient.
1106
1107	Example::
1108
1109		#arch/s390/Makefile
1110		KBUILD_LDFLAGS         := -m elf_s390
1111
1112	Note: ldflags-y can be used to further customise
1113	the flags used. See section 3.7.
1114
1115    LDFLAGS_vmlinux
1116	Options for $(LD) when linking vmlinux
1117
1118	LDFLAGS_vmlinux is used to specify additional flags to pass to
1119	the linker when linking the final vmlinux image.
1120	LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
1121
1122	Example::
1123
1124		#arch/x86/Makefile
1125		LDFLAGS_vmlinux := -e stext
1126
1127    OBJCOPYFLAGS
1128	objcopy flags
1129
1130	When $(call if_changed,objcopy) is used to translate a .o file,
1131	the flags specified in OBJCOPYFLAGS will be used.
1132	$(call if_changed,objcopy) is often used to generate raw binaries on
1133	vmlinux.
1134
1135	Example::
1136
1137		#arch/s390/Makefile
1138		OBJCOPYFLAGS := -O binary
1139
1140		#arch/s390/boot/Makefile
1141		$(obj)/image: vmlinux FORCE
1142			$(call if_changed,objcopy)
1143
1144	In this example, the binary $(obj)/image is a binary version of
1145	vmlinux. The usage of $(call if_changed,xxx) will be described later.
1146
1147    KBUILD_AFLAGS
1148	Assembler flags
1149
1150	Default value - see top level Makefile
1151	Append or modify as required per architecture.
1152
1153	Example::
1154
1155		#arch/sparc64/Makefile
1156		KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
1157
1158    KBUILD_CFLAGS
1159	$(CC) compiler flags
1160
1161	Default value - see top level Makefile
1162	Append or modify as required per architecture.
1163
1164	Often, the KBUILD_CFLAGS variable depends on the configuration.
1165
1166	Example::
1167
1168		#arch/x86/boot/compressed/Makefile
1169		cflags-$(CONFIG_X86_32) := -march=i386
1170		cflags-$(CONFIG_X86_64) := -mcmodel=small
1171		KBUILD_CFLAGS += $(cflags-y)
1172
1173	Many arch Makefiles dynamically run the target C compiler to
1174	probe supported options::
1175
1176		#arch/x86/Makefile
1177
1178		...
1179		cflags-$(CONFIG_MPENTIUMII)     += $(call cc-option,\
1180						-march=pentium2,-march=i686)
1181		...
1182		# Disable unit-at-a-time mode ...
1183		KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
1184		...
1185
1186
1187	The first example utilises the trick that a config option expands
1188	to 'y' when selected.
1189
1190    KBUILD_RUSTFLAGS
1191	$(RUSTC) compiler flags
1192
1193	Default value - see top level Makefile
1194	Append or modify as required per architecture.
1195
1196	Often, the KBUILD_RUSTFLAGS variable depends on the configuration.
1197
1198	Note that target specification file generation (for ``--target``)
1199	is handled in ``scripts/generate_rust_target.rs``.
1200
1201    KBUILD_AFLAGS_KERNEL
1202	Assembler options specific for built-in
1203
1204	$(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
1205	resident kernel code.
1206
1207    KBUILD_AFLAGS_MODULE
1208	Assembler options specific for modules
1209
1210	$(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
1211	are used for assembler.
1212
1213	From commandline AFLAGS_MODULE shall be used (see kbuild.rst).
1214
1215    KBUILD_CFLAGS_KERNEL
1216	$(CC) options specific for built-in
1217
1218	$(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
1219	resident kernel code.
1220
1221    KBUILD_CFLAGS_MODULE
1222	Options for $(CC) when building modules
1223
1224	$(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
1225	are used for $(CC).
1226	From commandline CFLAGS_MODULE shall be used (see kbuild.rst).
1227
1228    KBUILD_RUSTFLAGS_KERNEL
1229	$(RUSTC) options specific for built-in
1230
1231	$(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to
1232	compile resident kernel code.
1233
1234    KBUILD_RUSTFLAGS_MODULE
1235	Options for $(RUSTC) when building modules
1236
1237	$(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that
1238	are used for $(RUSTC).
1239	From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst).
1240
1241    KBUILD_LDFLAGS_MODULE
1242	Options for $(LD) when linking modules
1243
1244	$(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options
1245	used when linking modules. This is often a linker script.
1246
1247	From commandline LDFLAGS_MODULE shall be used (see kbuild.rst).
1248
1249    KBUILD_LDS
1250
1251	The linker script with full path. Assigned by the top-level Makefile.
1252
1253    KBUILD_LDS_MODULE
1254
1255	The module linker script with full path. Assigned by the top-level
1256	Makefile and additionally by the arch Makefile.
1257
1258    KBUILD_VMLINUX_OBJS
1259
1260	All object files for vmlinux. They are linked to vmlinux in the same
1261	order as listed in KBUILD_VMLINUX_OBJS.
1262
1263	The objects listed in scripts/head-object-list.txt are exceptions;
1264	they are placed before the other objects.
1265
1266    KBUILD_VMLINUX_LIBS
1267
1268	All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and
1269	KBUILD_VMLINUX_LIBS together specify all the object files used to
1270	link vmlinux.
1271
12727.2 Add prerequisites to archheaders
1273------------------------------------
1274
1275	The archheaders: rule is used to generate header files that
1276	may be installed into user space by "make header_install".
1277
1278	It is run before "make archprepare" when run on the
1279	architecture itself.
1280
1281
12827.3 Add prerequisites to archprepare
1283------------------------------------
1284
1285	The archprepare: rule is used to list prerequisites that need to be
1286	built before starting to descend down in the subdirectories.
1287	This is usually used for header files containing assembler constants.
1288
1289	Example::
1290
1291		#arch/arm/Makefile
1292		archprepare: maketools
1293
1294	In this example, the file target maketools will be processed
1295	before descending down in the subdirectories.
1296	See also chapter XXX-TODO that describes how kbuild supports
1297	generating offset header files.
1298
1299
13007.4 List directories to visit when descending
1301---------------------------------------------
1302
1303	An arch Makefile cooperates with the top Makefile to define variables
1304	which specify how to build the vmlinux file.  Note that there is no
1305	corresponding arch-specific section for modules; the module-building
1306	machinery is all architecture-independent.
1307
1308
1309	core-y, libs-y, drivers-y
1310
1311	    $(libs-y) lists directories where a lib.a archive can be located.
1312
1313	    The rest list directories where a built-in.a object file can be
1314	    located.
1315
1316	    Then the rest follows in this order:
1317
1318		$(core-y), $(libs-y), $(drivers-y)
1319
1320	    The top level Makefile defines values for all generic directories,
1321	    and arch/$(SRCARCH)/Makefile only adds architecture-specific
1322	    directories.
1323
1324	    Example::
1325
1326		# arch/sparc/Makefile
1327		core-y                 += arch/sparc/
1328
1329		libs-y                 += arch/sparc/prom/
1330		libs-y                 += arch/sparc/lib/
1331
1332		drivers-$(CONFIG_PM) += arch/sparc/power/
1333
13347.5 Architecture-specific boot images
1335-------------------------------------
1336
1337	An arch Makefile specifies goals that take the vmlinux file, compress
1338	it, wrap it in bootstrapping code, and copy the resulting files
1339	somewhere. This includes various kinds of installation commands.
1340	The actual goals are not standardized across architectures.
1341
1342	It is common to locate any additional processing in a boot/
1343	directory below arch/$(SRCARCH)/.
1344
1345	Kbuild does not provide any smart way to support building a
1346	target specified in boot/. Therefore arch/$(SRCARCH)/Makefile shall
1347	call make manually to build a target in boot/.
1348
1349	The recommended approach is to include shortcuts in
1350	arch/$(SRCARCH)/Makefile, and use the full path when calling down
1351	into the arch/$(SRCARCH)/boot/Makefile.
1352
1353	Example::
1354
1355		#arch/x86/Makefile
1356		boot := arch/x86/boot
1357		bzImage: vmlinux
1358			$(Q)$(MAKE) $(build)=$(boot) $(boot)/$@
1359
1360	"$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
1361	make in a subdirectory.
1362
1363	There are no rules for naming architecture-specific targets,
1364	but executing "make help" will list all relevant targets.
1365	To support this, $(archhelp) must be defined.
1366
1367	Example::
1368
1369		#arch/x86/Makefile
1370		define archhelp
1371		  echo  '* bzImage      - Compressed kernel image (arch/x86/boot/bzImage)'
1372		endif
1373
1374	When make is executed without arguments, the first goal encountered
1375	will be built. In the top level Makefile the first goal present
1376	is all:.
1377	An architecture shall always, per default, build a bootable image.
1378	In "make help", the default goal is highlighted with a '*'.
1379	Add a new prerequisite to all: to select a default goal different
1380	from vmlinux.
1381
1382	Example::
1383
1384		#arch/x86/Makefile
1385		all: bzImage
1386
1387	When "make" is executed without arguments, bzImage will be built.
1388
13897.7 Commands useful for building a boot image
1390---------------------------------------------
1391
1392    Kbuild provides a few macros that are useful when building a
1393    boot image.
1394
1395    ld
1396	Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1397
1398	Example::
1399
1400		#arch/x86/boot/Makefile
1401		LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
1402		LDFLAGS_setup    := -Ttext 0x0 -s --oformat binary -e begtext
1403
1404		targets += setup setup.o bootsect bootsect.o
1405		$(obj)/setup $(obj)/bootsect: %: %.o FORCE
1406			$(call if_changed,ld)
1407
1408	In this example, there are two possible targets, requiring different
1409	options to the linker. The linker options are specified using the
1410	LDFLAGS_$@ syntax - one for each potential target.
1411	$(targets) are assigned all potential targets, by which kbuild knows
1412	the targets and will:
1413
1414		1) check for commandline changes
1415		2) delete target during make clean
1416
1417	The ": %: %.o" part of the prerequisite is a shorthand that
1418	frees us from listing the setup.o and bootsect.o files.
1419
1420	Note:
1421	      It is a common mistake to forget the "targets :=" assignment,
1422	      resulting in the target file being recompiled for no
1423	      obvious reason.
1424
1425    objcopy
1426	Copy binary. Uses OBJCOPYFLAGS usually specified in
1427	arch/$(SRCARCH)/Makefile.
1428	OBJCOPYFLAGS_$@ may be used to set additional options.
1429
1430    gzip
1431	Compress target. Use maximum compression to compress target.
1432
1433	Example::
1434
1435		#arch/x86/boot/compressed/Makefile
1436		$(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE
1437			$(call if_changed,gzip)
1438
1439    dtc
1440	Create flattened device tree blob object suitable for linking
1441	into vmlinux. Device tree blobs linked into vmlinux are placed
1442	in an init section in the image. Platform code *must* copy the
1443	blob to non-init memory prior to calling unflatten_device_tree().
1444
1445	To use this command, simply add `*.dtb` into obj-y or targets, or make
1446	some other target depend on `%.dtb`
1447
1448	A central rule exists to create `$(obj)/%.dtb` from `$(src)/%.dts`;
1449	architecture Makefiles do no need to explicitly write out that rule.
1450
1451	Example::
1452
1453		targets += $(dtb-y)
1454		DTC_FLAGS ?= -p 1024
1455
14567.9 Preprocessing linker scripts
1457--------------------------------
1458
1459	When the vmlinux image is built, the linker script
1460	arch/$(SRCARCH)/kernel/vmlinux.lds is used.
1461	The script is a preprocessed variant of the file vmlinux.lds.S
1462	located in the same directory.
1463	kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`.
1464
1465	Example::
1466
1467		#arch/x86/kernel/Makefile
1468		extra-y := vmlinux.lds
1469
1470	The assignment to extra-y is used to tell kbuild to build the
1471	target vmlinux.lds.
1472	The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
1473	specified options when building the target vmlinux.lds.
1474
1475	When building the `*.lds` target, kbuild uses the variables::
1476
1477		KBUILD_CPPFLAGS	: Set in top-level Makefile
1478		cppflags-y	: May be set in the kbuild makefile
1479		CPPFLAGS_$(@F)  : Target-specific flags.
1480				Note that the full filename is used in this
1481				assignment.
1482
1483	The kbuild infrastructure for `*lds` files is used in several
1484	architecture-specific files.
1485
14867.10 Generic header files
1487-------------------------
1488
1489	The directory include/asm-generic contains the header files
1490	that may be shared between individual architectures.
1491	The recommended approach how to use a generic header file is
1492	to list the file in the Kbuild file.
1493	See "8.2 generic-y" for further info on syntax etc.
1494
14957.11 Post-link pass
1496-------------------
1497
1498	If the file arch/xxx/Makefile.postlink exists, this makefile
1499	will be invoked for post-link objects (vmlinux and modules.ko)
1500	for architectures to run post-link passes on. Must also handle
1501	the clean target.
1502
1503	This pass runs after kallsyms generation. If the architecture
1504	needs to modify symbol locations, rather than manipulate the
1505	kallsyms, it may be easier to add another postlink target for
1506	.tmp_vmlinux? targets to be called from link-vmlinux.sh.
1507
1508	For example, powerpc uses this to check relocation sanity of
1509	the linked vmlinux file.
1510
15118 Kbuild syntax for exported headers
1512------------------------------------
1513
1514The kernel includes a set of headers that is exported to userspace.
1515Many headers can be exported as-is but other headers require a
1516minimal pre-processing before they are ready for user-space.
1517The pre-processing does:
1518
1519- drop kernel-specific annotations
1520- drop include of compiler.h
1521- drop all sections that are kernel internal (guarded by `ifdef __KERNEL__`)
1522
1523All headers under include/uapi/, include/generated/uapi/,
1524arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/
1525are exported.
1526
1527A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and
1528arch/<arch>/include/asm/ to list asm files coming from asm-generic.
1529See subsequent chapter for the syntax of the Kbuild file.
1530
15318.1 no-export-headers
1532---------------------
1533
1534	no-export-headers is essentially used by include/uapi/linux/Kbuild to
1535	avoid exporting specific headers (e.g. kvm.h) on architectures that do
1536	not support it. It should be avoided as much as possible.
1537
15388.2 generic-y
1539-------------
1540
1541	If an architecture uses a verbatim copy of a header from
1542	include/asm-generic then this is listed in the file
1543	arch/$(SRCARCH)/include/asm/Kbuild like this:
1544
1545		Example::
1546
1547			#arch/x86/include/asm/Kbuild
1548			generic-y += termios.h
1549			generic-y += rtc.h
1550
1551	During the prepare phase of the build a wrapper include
1552	file is generated in the directory::
1553
1554		arch/$(SRCARCH)/include/generated/asm
1555
1556	When a header is exported where the architecture uses
1557	the generic header a similar wrapper is generated as part
1558	of the set of exported headers in the directory::
1559
1560		usr/include/asm
1561
1562	The generated wrapper will in both cases look like the following:
1563
1564		Example: termios.h::
1565
1566			#include <asm-generic/termios.h>
1567
15688.3 generated-y
1569---------------
1570
1571	If an architecture generates other header files alongside generic-y
1572	wrappers, generated-y specifies them.
1573
1574	This prevents them being treated as stale asm-generic wrappers and
1575	removed.
1576
1577		Example::
1578
1579			#arch/x86/include/asm/Kbuild
1580			generated-y += syscalls_32.h
1581
15828.4 mandatory-y
1583---------------
1584
1585	mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild
1586	to define the minimum set of ASM headers that all architectures must have.
1587
1588	This works like optional generic-y. If a mandatory header is missing
1589	in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically
1590	generate a wrapper of the asm-generic one.
1591
15929 Kbuild Variables
1593==================
1594
1595The top Makefile exports the following variables:
1596
1597    VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
1598	These variables define the current kernel version.  A few arch
1599	Makefiles actually use these values directly; they should use
1600	$(KERNELRELEASE) instead.
1601
1602	$(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
1603	three-part version number, such as "2", "4", and "0".  These three
1604	values are always numeric.
1605
1606	$(EXTRAVERSION) defines an even tinier sublevel for pre-patches
1607	or additional patches.	It is usually some non-numeric string
1608	such as "-pre4", and is often blank.
1609
1610    KERNELRELEASE
1611	$(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
1612	for constructing installation directory names or showing in
1613	version strings.  Some arch Makefiles use it for this purpose.
1614
1615    ARCH
1616	This variable defines the target architecture, such as "i386",
1617	"arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
1618	determine which files to compile.
1619
1620	By default, the top Makefile sets $(ARCH) to be the same as the
1621	host system architecture.  For a cross build, a user may
1622	override the value of $(ARCH) on the command line::
1623
1624	    make ARCH=m68k ...
1625
1626    SRCARCH
1627	This variable specifies the directory in arch/ to build.
1628
1629	ARCH and SRCARCH may not necessarily match. A couple of arch
1630	directories are biarch, that is, a single `arch/*/` directory supports
1631	both 32-bit and 64-bit.
1632
1633	For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86.
1634	For all of them, SRCARCH=x86 because arch/x86/ supports	both i386 and
1635	x86_64.
1636
1637    INSTALL_PATH
1638	This variable defines a place for the arch Makefiles to install
1639	the resident kernel image and System.map file.
1640	Use this for architecture-specific install targets.
1641
1642    INSTALL_MOD_PATH, MODLIB
1643	$(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
1644	installation.  This variable is not defined in the Makefile but
1645	may be passed in by the user if desired.
1646
1647	$(MODLIB) specifies the directory for module installation.
1648	The top Makefile defines $(MODLIB) to
1649	$(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE).  The user may
1650	override this value on the command line if desired.
1651
1652    INSTALL_MOD_STRIP
1653	If this variable is specified, it will cause modules to be stripped
1654	after they are installed.  If INSTALL_MOD_STRIP is '1', then the
1655	default option --strip-debug will be used.  Otherwise, the
1656	INSTALL_MOD_STRIP value will be used as the option(s) to the strip
1657	command.
1658
1659
166010 Makefile language
1661====================
1662
1663The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
1664use only the documented features of GNU Make, but they do use many
1665GNU extensions.
1666
1667GNU Make supports elementary list-processing functions.  The kernel
1668Makefiles use a novel style of list building and manipulation with few
1669"if" statements.
1670
1671GNU Make has two assignment operators, ":=" and "=".  ":=" performs
1672immediate evaluation of the right-hand side and stores an actual string
1673into the left-hand side.  "=" is like a formula definition; it stores the
1674right-hand side in an unevaluated form and then evaluates this form each
1675time the left-hand side is used.
1676
1677There are some cases where "=" is appropriate.  Usually, though, ":="
1678is the right choice.
1679
168011 Credits
1681==========
1682
1683- Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1684- Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1685- Updates by Sam Ravnborg <sam@ravnborg.org>
1686- Language QA by Jan Engelhardt <jengelh@gmx.de>
1687
168812 TODO
1689=======
1690
1691- Describe how kbuild supports shipped files with _shipped.
1692- Generating offset header files.
1693- Add more variables to chapters 7 or 9?
1694