About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / kbuild / makefiles.txt




Custom Search

Based on kernel version 4.9. Page generated on 2016-12-21 14:34 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.