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