makefiles.txt 46.6 KB
Newer Older
L
Linus Torvalds 已提交
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
Linux Kernel Makefiles

This document describes the Linux kernel Makefiles.

=== Table of Contents

	=== 1 Overview
	=== 2 Who does what
	=== 3 The kbuild files
	   --- 3.1 Goal definitions
	   --- 3.2 Built-in object goals - obj-y
	   --- 3.3 Loadable module goals - obj-m
	   --- 3.4 Objects which export symbols
	   --- 3.5 Library file goals - lib-y
	   --- 3.6 Descending down in directories
	   --- 3.7 Compilation flags
	   --- 3.8 Command line dependency
	   --- 3.9 Dependency tracking
	   --- 3.10 Special Rules
20
	   --- 3.11 $(CC) support functions
S
Sam Ravnborg 已提交
21
	   --- 3.12 $(LD) support functions
L
Linus Torvalds 已提交
22 23 24 25

	=== 4 Host Program support
	   --- 4.1 Simple Host Program
	   --- 4.2 Composite Host Programs
26 27 28 29
	   --- 4.3 Using C++ for host programs
	   --- 4.4 Controlling compiler options for host programs
	   --- 4.5 When host programs are actually built
	   --- 4.6 Using hostprogs-$(CONFIG_FOO)
L
Linus Torvalds 已提交
30 31 32 33 34

	=== 5 Kbuild clean infrastructure

	=== 6 Architecture Makefiles
	   --- 6.1 Set variables to tweak the build to the architecture
35 36 37 38 39 40 41 42 43
	   --- 6.2 Add prerequisites to archheaders:
	   --- 6.3 Add prerequisites to archprepare:
	   --- 6.4 List directories to visit when descending
	   --- 6.5 Architecture-specific boot images
	   --- 6.6 Building non-kbuild targets
	   --- 6.7 Commands useful for building a boot image
	   --- 6.8 Custom kbuild commands
	   --- 6.9 Preprocessing linker scripts
	   --- 6.10 Generic header files
44
	   --- 6.11 Post-link pass
L
Linus Torvalds 已提交
45

46
	=== 7 Kbuild syntax for exported headers
47
		--- 7.1 no-export-headers
48 49 50
		--- 7.2 generic-y
		--- 7.3 generated-y
		--- 7.4 mandatory-y
51 52 53 54 55

	=== 8 Kbuild Variables
	=== 9 Makefile language
	=== 10 Credits
	=== 11 TODO
L
Linus Torvalds 已提交
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80

=== 1 Overview

The Makefiles have five parts:

	Makefile		the top Makefile.
	.config			the kernel configuration file.
	arch/$(ARCH)/Makefile	the arch Makefile.
	scripts/Makefile.*	common rules etc. for all kbuild Makefiles.
	kbuild Makefiles	there are about 500 of these.

The top Makefile reads the .config file, which comes from the kernel
configuration process.

The top Makefile is responsible for building two major products: vmlinux
(the resident kernel image) and modules (any module files).
It builds these goals by recursively descending into the subdirectories of
the kernel source tree.
The list of subdirectories which are visited depends upon the kernel
configuration. The top Makefile textually includes an arch Makefile
with the name arch/$(ARCH)/Makefile. The arch Makefile supplies
architecture-specific information to the top Makefile.

Each subdirectory has a kbuild Makefile which carries out the commands
passed down from above. The kbuild Makefile uses information from the
81
.config file to construct various file lists used by kbuild to build
L
Linus Torvalds 已提交
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
any built-in or modular targets.

scripts/Makefile.* contains all the definitions/rules etc. that
are used to build the kernel based on the kbuild makefiles.


=== 2 Who does what

People have four different relationships with the kernel Makefiles.

*Users* are people who build kernels.  These people type commands such as
"make menuconfig" or "make".  They usually do not read or edit
any kernel Makefiles (or any other source files).

*Normal developers* are people who work on features such as device
drivers, file systems, and network protocols.  These people need to
98
maintain the kbuild Makefiles for the subsystem they are
L
Linus Torvalds 已提交
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
working on.  In order to do this effectively, they need some overall
knowledge about the kernel Makefiles, plus detailed knowledge about the
public interface for kbuild.

*Arch developers* are people who work on an entire architecture, such
as sparc or ia64.  Arch developers need to know about the arch Makefile
as well as kbuild Makefiles.

*Kbuild developers* are people who work on the kernel build system itself.
These people need to know about all aspects of the kernel Makefiles.

This document is aimed towards normal developers and arch developers.


=== 3 The kbuild files

Most Makefiles within the kernel are kbuild Makefiles that use the
116
kbuild infrastructure. This chapter introduces the syntax used in the
L
Linus Torvalds 已提交
117
kbuild makefiles.
118
The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
119
be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
120
file will be used.
L
Linus Torvalds 已提交
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135

Section 3.1 "Goal definitions" is a quick intro, further chapters provide
more details, with real examples.

--- 3.1 Goal definitions

	Goal definitions are the main part (heart) of the kbuild Makefile.
	These lines define the files to be built, any special compilation
	options, and any subdirectories to be entered recursively.

	The most simple kbuild makefile contains one line:

	Example:
		obj-y += foo.o

R
Randy Dunlap 已提交
136
	This tells kbuild that there is one object in that directory, named
L
Linus Torvalds 已提交
137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
	foo.o. foo.o will be built from foo.c or foo.S.

	If foo.o shall be built as a module, the variable obj-m is used.
	Therefore the following pattern is often used:

	Example:
		obj-$(CONFIG_FOO) += foo.o

	$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
	If CONFIG_FOO is neither y nor m, then the file will not be compiled
	nor linked.

--- 3.2 Built-in object goals - obj-y

	The kbuild Makefile specifies object files for vmlinux
152
	in the $(obj-y) lists.  These lists depend on the kernel
L
Linus Torvalds 已提交
153 154 155 156 157 158 159 160 161 162 163 164 165
	configuration.

	Kbuild compiles all the $(obj-y) files.  It then calls
	"$(LD) -r" to merge these files into one built-in.o file.
	built-in.o is later linked into vmlinux by the parent Makefile.

	The order of files in $(obj-y) is significant.  Duplicates in
	the lists are allowed: the first instance will be linked into
	built-in.o and succeeding instances will be ignored.

	Link order is significant, because certain functions
	(module_init() / __initcall) will be called during boot in the
	order they appear. So keep in mind that changing the link
166 167
	order may e.g. change the order in which your SCSI
	controllers are detected, and thus your disks are renumbered.
L
Linus Torvalds 已提交
168 169 170 171 172

	Example:
		#drivers/isdn/i4l/Makefile
		# Makefile for the kernel ISDN subsystem and device drivers.
		# Each configuration option enables a list of files.
173
		obj-$(CONFIG_ISDN_I4L)         += isdn.o
L
Linus Torvalds 已提交
174 175 176 177
		obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o

--- 3.3 Loadable module goals - obj-m

178
	$(obj-m) specifies object files which are built as loadable
L
Linus Torvalds 已提交
179 180 181 182 183 184 185 186 187 188 189 190 191
	kernel modules.

	A module may be built from one source file or several source
	files. In the case of one source file, the kbuild makefile
	simply adds the file to $(obj-m).

	Example:
		#drivers/isdn/i4l/Makefile
		obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o

	Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'

	If a kernel module is built from several source files, you specify
192 193 194 195
	that you want to build a module in the same way as above; however,
	kbuild needs to know which object files you want to build your
	module from, so you have to tell it by setting a $(<module_name>-y)
	variable.
L
Linus Torvalds 已提交
196 197 198

	Example:
		#drivers/isdn/i4l/Makefile
199 200
		obj-$(CONFIG_ISDN_I4L) += isdn.o
		isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
L
Linus Torvalds 已提交
201 202

	In this example, the module name will be isdn.o. Kbuild will
203
	compile the objects listed in $(isdn-y) and then run
L
Linus Torvalds 已提交
204 205
	"$(LD) -r" on the list of these files to generate isdn.o.

206 207 208
	Due to kbuild recognizing $(<module_name>-y) for composite objects,
	you can use the value of a CONFIG_ symbol to optionally include an
	object file as part of a composite object.
L
Linus Torvalds 已提交
209 210 211

	Example:
		#fs/ext2/Makefile
212 213 214 215 216 217 218 219 220
	        obj-$(CONFIG_EXT2_FS) += ext2.o
		ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
			  namei.o super.o symlink.o
	        ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \
						xattr_trusted.o

	In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
	part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
	evaluates to 'y'.
L
Linus Torvalds 已提交
221 222 223 224 225 226 227 228 229 230 231 232 233

	Note: Of course, when you are building objects into the kernel,
	the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
	kbuild will build an ext2.o file for you out of the individual
	parts and then link this into built-in.o, as you would expect.

--- 3.4 Objects which export symbols

	No special notation is required in the makefiles for
	modules exporting symbols.

--- 3.5 Library file goals - lib-y

234
	Objects listed with obj-* are used for modules, or
L
Linus Torvalds 已提交
235 236 237 238 239
	combined in a built-in.o for that specific directory.
	There is also the possibility to list objects that will
	be included in a library, lib.a.
	All objects listed with lib-y are combined in a single
	library for that directory.
M
Matt LaPlante 已提交
240 241 242
	Objects that are listed in obj-y and additionally listed in
	lib-y will not be included in the library, since they will
	be accessible anyway.
243
	For consistency, objects listed in lib-m will be included in lib.a.
L
Linus Torvalds 已提交
244 245 246 247 248 249

	Note that the same kbuild makefile may list files to be built-in
	and to be part of a library. Therefore the same directory
	may contain both a built-in.o and a lib.a file.

	Example:
250 251
		#arch/x86/lib/Makefile
		lib-y    := delay.o
L
Linus Torvalds 已提交
252

253 254 255
	This will create a library lib.a based on delay.o. For kbuild to
	actually recognize that there is a lib.a being built, the directory
	shall be listed in libs-y.
256
	See also "6.4 List directories to visit when descending".
257

258
	Use of lib-y is normally restricted to lib/ and arch/*/lib.
L
Linus Torvalds 已提交
259 260 261 262 263 264 265 266 267

--- 3.6 Descending down in directories

	A Makefile is only responsible for building objects in its own
	directory. Files in subdirectories should be taken care of by
	Makefiles in these subdirs. The build system will automatically
	invoke make recursively in subdirectories, provided you let it know of
	them.

268
	To do so, obj-y and obj-m are used.
L
Linus Torvalds 已提交
269 270 271 272 273 274 275 276 277 278 279 280
	ext2 lives in a separate directory, and the Makefile present in fs/
	tells kbuild to descend down using the following assignment.

	Example:
		#fs/Makefile
		obj-$(CONFIG_EXT2_FS) += ext2/

	If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
	the corresponding obj- variable will be set, and kbuild will descend
	down in the ext2 directory.
	Kbuild only uses this information to decide that it needs to visit
	the directory, it is the Makefile in the subdirectory that
281
	specifies what is modular and what is built-in.
L
Linus Torvalds 已提交
282 283 284 285 286 287 288

	It is good practice to use a CONFIG_ variable when assigning directory
	names. This allows kbuild to totally skip the directory if the
	corresponding CONFIG_ option is neither 'y' nor 'm'.

--- 3.7 Compilation flags

289
    ccflags-y, asflags-y and ldflags-y
290 291 292
	These three flags apply only to the kbuild makefile in which they
	are assigned. They are used for all the normal cc, as and ld
	invocations happening during a recursive build.
293
	Note: Flags with the same behaviour were previously named:
294 295
	EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
	They are still supported but their usage is deprecated.
L
Linus Torvalds 已提交
296

297
	ccflags-y specifies options for compiling with $(CC).
L
Linus Torvalds 已提交
298 299

	Example:
300 301 302
		# drivers/acpi/acpica/Makefile
		ccflags-y			:= -Os -D_LINUX -DBUILDING_ACPICA
		ccflags-$(CONFIG_ACPI_DEBUG)	+= -DACPI_DEBUG_OUTPUT
L
Linus Torvalds 已提交
303 304

	This variable is necessary because the top Makefile owns the
305
	variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
L
Linus Torvalds 已提交
306 307
	entire tree.

308
	asflags-y specifies options for assembling with $(AS).
L
Linus Torvalds 已提交
309 310

	Example:
311 312
		#arch/sparc/kernel/Makefile
		asflags-y := -ansi
L
Linus Torvalds 已提交
313

314
	ldflags-y specifies options for linking with $(LD).
L
Linus Torvalds 已提交
315 316

	Example:
317 318
		#arch/cris/boot/compressed/Makefile
		ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
L
Linus Torvalds 已提交
319

320
    subdir-ccflags-y, subdir-asflags-y
321
	The two flags listed above are similar to ccflags-y and asflags-y.
322 323 324 325
	The difference is that the subdir- variants have effect for the kbuild
	file where they are present and all subdirectories.
	Options specified using subdir-* are added to the commandline before
	the options specified using the non-subdir variants.
326 327 328 329

	Example:
		subdir-ccflags-y := -Werror

L
Linus Torvalds 已提交
330 331 332 333 334 335 336 337 338 339 340 341 342 343
    CFLAGS_$@, AFLAGS_$@

	CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
	kbuild makefile.

	$(CFLAGS_$@) specifies per-file options for $(CC).  The $@
	part has a literal value which specifies the file that it is for.

	Example:
		# drivers/scsi/Makefile
		CFLAGS_aha152x.o =   -DAHA152X_STAT -DAUTOCONF
		CFLAGS_gdth.o    = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
				     -DGDTH_STATISTICS

344
	These two lines specify compilation flags for aha152x.o and gdth.o.
L
Linus Torvalds 已提交
345 346 347 348 349 350

	$(AFLAGS_$@) is a similar feature for source files in assembly
	languages.

	Example:
		# arch/arm/kernel/Makefile
351 352 353 354
		AFLAGS_head.o        := -DTEXT_OFFSET=$(TEXT_OFFSET)
		AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
		AFLAGS_iwmmxt.o      := -Wa,-mcpu=iwmmxt

L
Linus Torvalds 已提交
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370

--- 3.9 Dependency tracking

	Kbuild tracks dependencies on the following:
	1) All prerequisite files (both *.c and *.h)
	2) CONFIG_ options used in all prerequisite files
	3) Command-line used to compile target

	Thus, if you change an option to $(CC) all affected files will
	be re-compiled.

--- 3.10 Special Rules

	Special rules are used when the kbuild infrastructure does
	not provide the required support. A typical example is
	header files generated during the build process.
R
Randy Dunlap 已提交
371
	Another example are the architecture-specific Makefiles which
372
	need special rules to prepare boot images etc.
L
Linus Torvalds 已提交
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402

	Special rules are written as normal Make rules.
	Kbuild is not executing in the directory where the Makefile is
	located, so all special rules shall provide a relative
	path to prerequisite files and target files.

	Two variables are used when defining special rules:

    $(src)
	$(src) is a relative path which points to the directory
	where the Makefile is located. Always use $(src) when
	referring to files located in the src tree.

    $(obj)
	$(obj) is a relative path which points to the directory
	where the target is saved. Always use $(obj) when
	referring to generated files.

	Example:
		#drivers/scsi/Makefile
		$(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
			$(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl

	This is a special rule, following the normal syntax
	required by make.
	The target file depends on two prerequisite files. References
	to the target file are prefixed with $(obj), references
	to prerequisites are referenced with $(src) (because they are not
	generated files).

403 404 405 406
    $(kecho)
	echoing information to user in a rule is often a good practice
	but when execution "make -s" one does not expect to see any output
	except for warnings/errors.
407
	To support this kbuild defines $(kecho) which will echo out the
408 409 410 411 412 413 414 415 416
	text following $(kecho) to stdout except if "make -s" is used.

	Example:
		#arch/blackfin/boot/Makefile
		$(obj)/vmImage: $(obj)/vmlinux.gz
			$(call if_changed,uimage)
			@$(kecho) 'Kernel: $@ is ready'


417 418
--- 3.11 $(CC) support functions

419
	The kernel may be built with several different versions of
420
	$(CC), each supporting a unique set of features and options.
421
	kbuild provides basic support to check for valid options for $(CC).
D
Daniel Walker 已提交
422
	$(CC) is usually the gcc compiler, but other alternatives are
423 424 425
	available.

    as-option
426 427 428
	as-option is used to check if $(CC) -- when used to compile
	assembler (*.S) files -- supports the given option. An optional
	second option may be specified if the first option is not supported.
429 430 431 432 433

	Example:
		#arch/sh/Makefile
		cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)

434
	In the above example, cflags-y will be assigned the option
435 436 437 438
	-Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
	The second argument is optional, and if supplied will be used
	if first argument is not supported.

439 440
    cc-ldoption
	cc-ldoption is used to check if $(CC) when used to link object files
R
Roland McGrath 已提交
441 442 443 444
	supports the given option.  An optional second option may be
	specified if first option are not supported.

	Example:
445
		#arch/x86/kernel/Makefile
446
		vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
R
Roland McGrath 已提交
447

R
Randy Dunlap 已提交
448
	In the above example, vsyscall-flags will be assigned the option
R
Roland McGrath 已提交
449 450 451 452
	-Wl$(comma)--hash-style=sysv if it is supported by $(CC).
	The second argument is optional, and if supplied will be used
	if first argument is not supported.

453 454 455 456
    as-instr
	as-instr checks if the assembler reports a specific instruction
	and then outputs either option1 or option2
	C escapes are supported in the test instruction
457
	Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options
458

459
    cc-option
460 461
	cc-option is used to check if $(CC) supports a given option, and if
	not supported to use an optional second option.
462 463

	Example:
464
		#arch/x86/Makefile
465 466
		cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)

R
Randy Dunlap 已提交
467
	In the above example, cflags-y will be assigned the option
468 469
	-march=pentium-mmx if supported by $(CC), otherwise -march=i586.
	The second argument to cc-option is optional, and if omitted,
470
	cflags-y will be assigned no value if first option is not supported.
471
	Note: cc-option uses KBUILD_CFLAGS for $(CC) options
472 473

   cc-option-yn
474
	cc-option-yn is used to check if gcc supports a given option
475 476 477 478 479 480 481
	and return 'y' if supported, otherwise 'n'.

	Example:
		#arch/ppc/Makefile
		biarch := $(call cc-option-yn, -m32)
		aflags-$(biarch) += -a32
		cflags-$(biarch) += -m32
482

483 484 485 486
	In the above example, $(biarch) is set to y if $(CC) supports the -m32
	option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
	and $(cflags-y) will be assigned the values -a32 and -m32,
	respectively.
487
	Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
488

489 490 491 492 493 494 495 496 497 498 499 500
    cc-disable-warning
	cc-disable-warning checks if gcc supports a given warning and returns
	the commandline switch to disable it. This special function is needed,
	because gcc 4.4 and later accept any unknown -Wno-* option and only
	warn about it if there is another warning in the source file.

	Example:
		KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)

	In the above example, -Wno-unused-but-set-variable will be added to
	KBUILD_CFLAGS only if gcc really accepts it.

501
    cc-version
502
	cc-version returns a numerical version of the $(CC) compiler version.
503 504 505
	The format is <major><minor> where both are two digits. So for example
	gcc 3.41 would return 0341.
	cc-version is useful when a specific $(CC) version is faulty in one
506
	area, for example -mregparm=3 was broken in some gcc versions
507 508 509
	even though the option was accepted by gcc.

	Example:
510
		#arch/x86/Makefile
511
		cflags-y += $(shell \
512
		if [ $(cc-version) -ge 0300 ] ; then \
513 514
			echo "-mregparm=3"; fi ;)

515
	In the above example, -mregparm=3 is only used for gcc version greater
516 517 518
	than or equal to gcc 3.0.

    cc-ifversion
519 520 521
	cc-ifversion tests the version of $(CC) and equals the fourth parameter
	if version expression is true, or the fifth (if given) if the version
	expression is false.
522 523 524

	Example:
		#fs/reiserfs/Makefile
525
		ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
526

527
	In this example, ccflags-y will be assigned the value -O1 if the
528
	$(CC) version is less than 4.2.
529
	cc-ifversion takes all the shell operators:
530 531 532 533
	-eq, -ne, -lt, -le, -gt, and -ge
	The third parameter may be a text as in this example, but it may also
	be an expanded variable or a macro.

S
Sam Ravnborg 已提交
534 535 536 537 538 539 540
    cc-fullversion
	cc-fullversion is useful when the exact version of gcc is needed.
	One typical use-case is when a specific GCC version is broken.
	cc-fullversion points out a more specific version than cc-version does.

	Example:
		#arch/powerpc/Makefile
541
		$(Q)if test "$(cc-fullversion)" = "040200" ; then \
S
Sam Ravnborg 已提交
542 543 544 545
			echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ; \
			false ; \
		fi

546 547
	In this example for a specific GCC version the build will error out
	explaining to the user why it stops.
L
Linus Torvalds 已提交
548

S
Sam Ravnborg 已提交
549
    cc-cross-prefix
550
	cc-cross-prefix is used to check if there exists a $(CC) in path with
S
Sam Ravnborg 已提交
551 552 553 554 555
	one of the listed prefixes. The first prefix where there exist a
	prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
	then nothing is returned.
	Additional prefixes are separated by a single space in the
	call of cc-cross-prefix.
556 557
	This functionality is useful for architecture Makefiles that try
	to set CROSS_COMPILE to well-known values but may have several
S
Sam Ravnborg 已提交
558
	values to select between.
559 560
	It is recommended only to try to set CROSS_COMPILE if it is a cross
	build (host arch is different from target arch). And if CROSS_COMPILE
S
Sam Ravnborg 已提交
561 562 563 564 565 566 567 568 569 570
	is already set then leave it with the old value.

	Example:
		#arch/m68k/Makefile
		ifneq ($(SUBARCH),$(ARCH))
		        ifeq ($(CROSS_COMPILE),)
		               CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
			endif
		endif

S
Sam Ravnborg 已提交
571 572 573 574 575 576 577 578 579 580
--- 3.12 $(LD) support functions

    ld-option
	ld-option is used to check if $(LD) supports the supplied option.
	ld-option takes two options as arguments.
	The second argument is an optional option that can be used if the
	first option is not supported by $(LD).

	Example:
		#Makefile
A
Antony Pavlov 已提交
581
		LDFLAGS_vmlinux += $(call ld-option, -X)
S
Sam Ravnborg 已提交
582 583


L
Linus Torvalds 已提交
584 585 586 587 588 589 590 591 592 593
=== 4 Host Program support

Kbuild supports building executables on the host for use during the
compilation stage.
Two steps are required in order to use a host executable.

The first step is to tell kbuild that a host program exists. This is
done utilising the variable hostprogs-y.

The second step is to add an explicit dependency to the executable.
594
This can be done in two ways. Either add the dependency in a rule,
L
Linus Torvalds 已提交
595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610
or utilise the variable $(always).
Both possibilities are described in the following.

--- 4.1 Simple Host Program

	In some cases there is a need to compile and run a program on the
	computer where the build is running.
	The following line tells kbuild that the program bin2hex shall be
	built on the build host.

	Example:
		hostprogs-y := bin2hex

	Kbuild assumes in the above example that bin2hex is made from a single
	c-source file named bin2hex.c located in the same directory as
	the Makefile.
611

L
Linus Torvalds 已提交
612 613 614 615 616
--- 4.2 Composite Host Programs

	Host programs can be made up based on composite objects.
	The syntax used to define composite objects for host programs is
	similar to the syntax used for kernel objects.
M
Matt LaPlante 已提交
617
	$(<executable>-objs) lists all objects used to link the final
L
Linus Torvalds 已提交
618 619 620 621
	executable.

	Example:
		#scripts/lxdialog/Makefile
622
		hostprogs-y   := lxdialog
L
Linus Torvalds 已提交
623 624 625
		lxdialog-objs := checklist.o lxdialog.o

	Objects with extension .o are compiled from the corresponding .c
626
	files. In the above example, checklist.c is compiled to checklist.o
L
Linus Torvalds 已提交
627
	and lxdialog.c is compiled to lxdialog.o.
628
	Finally, the two .o files are linked to the executable, lxdialog.
L
Linus Torvalds 已提交
629 630
	Note: The syntax <executable>-y is not permitted for host-programs.

631
--- 4.3 Using C++ for host programs
L
Linus Torvalds 已提交
632 633 634 635 636 637 638 639 640 641 642 643

	kbuild offers support for host programs written in C++. This was
	introduced solely to support kconfig, and is not recommended
	for general use.

	Example:
		#scripts/kconfig/Makefile
		hostprogs-y   := qconf
		qconf-cxxobjs := qconf.o

	In the example above the executable is composed of the C++ file
	qconf.cc - identified by $(qconf-cxxobjs).
644

645
	If qconf is composed of a mixture of .c and .cc files, then an
L
Linus Torvalds 已提交
646 647 648 649 650 651 652
	additional line can be used to identify this.

	Example:
		#scripts/kconfig/Makefile
		hostprogs-y   := qconf
		qconf-cxxobjs := qconf.o
		qconf-objs    := check.o
653

654
--- 4.4 Controlling compiler options for host programs
L
Linus Torvalds 已提交
655 656 657 658 659

	When compiling host programs, it is possible to set specific flags.
	The programs will always be compiled utilising $(HOSTCC) passed
	the options specified in $(HOSTCFLAGS).
	To set flags that will take effect for all host programs created
660
	in that Makefile, use the variable HOST_EXTRACFLAGS.
L
Linus Torvalds 已提交
661 662 663 664

	Example:
		#scripts/lxdialog/Makefile
		HOST_EXTRACFLAGS += -I/usr/include/ncurses
665

L
Linus Torvalds 已提交
666 667 668 669 670 671
	To set specific flags for a single file the following construction
	is used:

	Example:
		#arch/ppc64/boot/Makefile
		HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
672

L
Linus Torvalds 已提交
673
	It is also possible to specify additional options to the linker.
674

L
Linus Torvalds 已提交
675 676 677 678
	Example:
		#scripts/kconfig/Makefile
		HOSTLOADLIBES_qconf := -L$(QTDIR)/lib

679 680
	When linking qconf, it will be passed the extra option
	"-L$(QTDIR)/lib".
681

682
--- 4.5 When host programs are actually built
L
Linus Torvalds 已提交
683 684 685 686 687 688 689 690 691 692 693 694 695

	Kbuild will only build host-programs when they are referenced
	as a prerequisite.
	This is possible in two ways:

	(1) List the prerequisite explicitly in a special rule.

	Example:
		#drivers/pci/Makefile
		hostprogs-y := gen-devlist
		$(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
			( cd $(obj); ./gen-devlist ) < $<

696
	The target $(obj)/devlist.h will not be built before
L
Linus Torvalds 已提交
697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712
	$(obj)/gen-devlist is updated. Note that references to
	the host programs in special rules must be prefixed with $(obj).

	(2) Use $(always)
	When there is no suitable special rule, and the host program
	shall be built when a makefile is entered, the $(always)
	variable shall be used.

	Example:
		#scripts/lxdialog/Makefile
		hostprogs-y   := lxdialog
		always        := $(hostprogs-y)

	This will tell kbuild to build lxdialog even if not referenced in
	any rule.

713
--- 4.6 Using hostprogs-$(CONFIG_FOO)
L
Linus Torvalds 已提交
714

715
	A typical pattern in a Kbuild file looks like this:
L
Linus Torvalds 已提交
716 717 718 719 720 721

	Example:
		#scripts/Makefile
		hostprogs-$(CONFIG_KALLSYMS) += kallsyms

	Kbuild knows about both 'y' for built-in and 'm' for module.
722
	So if a config symbol evaluates to 'm', kbuild will still build
723 724 725
	the binary. In other words, Kbuild handles hostprogs-m exactly
	like hostprogs-y. But only hostprogs-y is recommended to be used
	when no CONFIG symbols are involved.
L
Linus Torvalds 已提交
726 727 728

=== 5 Kbuild clean infrastructure

729
"make clean" deletes most generated files in the obj tree where the kernel
L
Linus Torvalds 已提交
730 731 732 733 734 735 736 737 738 739
is compiled. This includes generated files such as host programs.
Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
$(extra-y) and $(targets). They are all deleted during "make clean".
Files matching the patterns "*.[oas]", "*.ko", plus some additional files
generated by kbuild are deleted all over the kernel src tree when
"make clean" is executed.

Additional files can be specified in kbuild makefiles by use of $(clean-files).

	Example:
740 741
		#lib/Makefile
		clean-files := crc32table.h
L
Linus Torvalds 已提交
742

743 744
When executing "make clean", the file "crc32table.h" will be deleted.
Kbuild will assume files to be in the same relative directory as the
745
Makefile, except if prefixed with $(objtree).
L
Linus Torvalds 已提交
746

747 748
To delete a directory hierarchy use:

L
Linus Torvalds 已提交
749 750 751 752
	Example:
		#scripts/package/Makefile
		clean-dirs := $(objtree)/debian/

753 754
This will delete the directory debian in the toplevel directory, including all
subdirectories.
L
Linus Torvalds 已提交
755

756 757 758 759 760 761 762
To exclude certain files from make clean, use the $(no-clean-files) variable.
This is only a special case used in the top level Kbuild file:

	Example:
		#Kbuild
		no-clean-files := $(bounds-file) $(offsets-file)

L
Linus Torvalds 已提交
763 764 765 766 767
Usually kbuild descends down in subdirectories due to "obj-* := dir/",
but in the architecture makefiles where the kbuild infrastructure
is not sufficient this sometimes needs to be explicit.

	Example:
768
		#arch/x86/boot/Makefile
L
Linus Torvalds 已提交
769 770 771 772 773
		subdir- := compressed/

The above assignment instructs kbuild to descend down in the
directory compressed/ when "make clean" is executed.

774
To support the clean infrastructure in the Makefiles that build the
L
Linus Torvalds 已提交
775 776 777
final bootimage there is an optional target named archclean:

	Example:
778
		#arch/x86/Makefile
L
Linus Torvalds 已提交
779
		archclean:
780
			$(Q)$(MAKE) $(clean)=arch/x86/boot
L
Linus Torvalds 已提交
781

782 783
When "make clean" is executed, make will descend down in arch/x86/boot,
and clean as usual. The Makefile located in arch/x86/boot/ may use
L
Linus Torvalds 已提交
784 785 786 787 788 789 790 791 792 793 794 795 796
the subdir- trick to descend further down.

Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is
included in the top level makefile, and the kbuild infrastructure
is not operational at that point.

Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
be visited during "make clean".

=== 6 Architecture Makefiles

The top level Makefile sets up the environment and does the preparation,
before starting to descend down in the individual directories.
797 798 799 800
The top level makefile contains the generic part, whereas
arch/$(ARCH)/Makefile contains what is required to set up kbuild
for said architecture.
To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
L
Linus Torvalds 已提交
801 802
a few targets.

803 804
When kbuild executes, the following steps are followed (roughly):
1) Configuration of the kernel => produce .config
L
Linus Torvalds 已提交
805
2) Store kernel version in include/linux/version.h
806
3) Updating all other prerequisites to the target prepare:
L
Linus Torvalds 已提交
807
   - Additional prerequisites are specified in arch/$(ARCH)/Makefile
808
4) Recursively descend down in all directories listed in
L
Linus Torvalds 已提交
809
   init-* core* drivers-* net-* libs-* and build all targets.
810
   - The values of the above variables are expanded in arch/$(ARCH)/Makefile.
811
5) All object files are then linked and the resulting file vmlinux is
812
   located at the root of the obj tree.
L
Linus Torvalds 已提交
813 814
   The very first objects linked are listed in head-y, assigned by
   arch/$(ARCH)/Makefile.
815
6) Finally, the architecture-specific part does any required post processing
L
Linus Torvalds 已提交
816 817
   and builds the final bootimage.
   - This includes building boot records
R
Randy Dunlap 已提交
818
   - Preparing initrd images and the like
L
Linus Torvalds 已提交
819 820 821 822 823 824 825 826 827 828 829 830


--- 6.1 Set variables to tweak the build to the architecture

    LDFLAGS		Generic $(LD) options

	Flags used for all invocations of the linker.
	Often specifying the emulation is sufficient.

	Example:
		#arch/s390/Makefile
		LDFLAGS         := -m elf_s390
831
	Note: ldflags-y can be used to further customise
832
	the flags used. See chapter 3.7.
833

L
Linus Torvalds 已提交
834 835 836 837 838 839 840 841 842
    LDFLAGS_MODULE	Options for $(LD) when linking modules

	LDFLAGS_MODULE is used to set specific flags for $(LD) when
	linking the .ko files used for modules.
	Default is "-r", for relocatable output.

    LDFLAGS_vmlinux	Options for $(LD) when linking vmlinux

	LDFLAGS_vmlinux is used to specify additional flags to pass to
843
	the linker when linking the final vmlinux image.
L
Linus Torvalds 已提交
844 845 846
	LDFLAGS_vmlinux uses the LDFLAGS_$@ support.

	Example:
847
		#arch/x86/Makefile
L
Linus Torvalds 已提交
848 849 850 851 852
		LDFLAGS_vmlinux := -e stext

    OBJCOPYFLAGS	objcopy flags

	When $(call if_changed,objcopy) is used to translate a .o file,
853
	the flags specified in OBJCOPYFLAGS will be used.
L
Linus Torvalds 已提交
854 855 856 857 858 859 860 861 862 863 864
	$(call if_changed,objcopy) is often used to generate raw binaries on
	vmlinux.

	Example:
		#arch/s390/Makefile
		OBJCOPYFLAGS := -O binary

		#arch/s390/boot/Makefile
		$(obj)/image: vmlinux FORCE
			$(call if_changed,objcopy)

865
	In this example, the binary $(obj)/image is a binary version of
L
Linus Torvalds 已提交
866 867
	vmlinux. The usage of $(call if_changed,xxx) will be described later.

868
    KBUILD_AFLAGS		$(AS) assembler flags
L
Linus Torvalds 已提交
869 870 871 872 873 874

	Default value - see top level Makefile
	Append or modify as required per architecture.

	Example:
		#arch/sparc64/Makefile
875
		KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
L
Linus Torvalds 已提交
876

877
    KBUILD_CFLAGS		$(CC) compiler flags
L
Linus Torvalds 已提交
878 879 880 881

	Default value - see top level Makefile
	Append or modify as required per architecture.

882
	Often, the KBUILD_CFLAGS variable depends on the configuration.
L
Linus Torvalds 已提交
883 884

	Example:
885 886 887
		#arch/x86/boot/compressed/Makefile
		cflags-$(CONFIG_X86_32) := -march=i386
		cflags-$(CONFIG_X86_64) := -mcmodel=small
888
		KBUILD_CFLAGS += $(cflags-y)
L
Linus Torvalds 已提交
889 890 891 892

	Many arch Makefiles dynamically run the target C compiler to
	probe supported options:

893
		#arch/x86/Makefile
L
Linus Torvalds 已提交
894 895 896 897 898 899

		...
		cflags-$(CONFIG_MPENTIUMII)     += $(call cc-option,\
						-march=pentium2,-march=i686)
		...
		# Disable unit-at-a-time mode ...
900
		KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
L
Linus Torvalds 已提交
901 902 903
		...


904
	The first example utilises the trick that a config option expands
L
Linus Torvalds 已提交
905 906
	to 'y' when selected.

907
    KBUILD_AFLAGS_KERNEL	$(AS) options specific for built-in
L
Linus Torvalds 已提交
908

909
	$(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
L
Linus Torvalds 已提交
910 911
	resident kernel code.

912
    KBUILD_AFLAGS_MODULE   Options for $(AS) when building modules
L
Linus Torvalds 已提交
913

914
	$(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
915 916
	are used for $(AS).
	From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
L
Linus Torvalds 已提交
917

918 919 920 921 922
    KBUILD_CFLAGS_KERNEL	$(CC) options specific for built-in

	$(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
	resident kernel code.

923 924
    KBUILD_CFLAGS_MODULE   Options for $(CC) when building modules

925
	$(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
926 927 928 929 930
	are used for $(CC).
	From commandline CFLAGS_MODULE shall be used (see kbuild.txt).

    KBUILD_LDFLAGS_MODULE   Options for $(LD) when linking modules

931
	$(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options
932 933
	used when linking modules. This is often a linker script.
	From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).
934

935 936 937 938 939
    KBUILD_ARFLAGS   Options for $(AR) when creating archives

	$(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic
	mode) if this option is supported by $(AR).

940 941 942 943 944 945 946 947
    ARCH_CPPFLAGS, ARCH_AFLAGS, ARCH_CFLAGS   Overrides the kbuild defaults

	These variables are appended to the KBUILD_CPPFLAGS,
	KBUILD_AFLAGS, and KBUILD_CFLAGS, respectively, after the
	top-level Makefile has set any other flags. This provides a
	means for an architecture to override the defaults.


948 949 950 951 952 953 954 955 956 957 958 959 960 961
--- 6.2 Add prerequisites to archheaders:

	The archheaders: rule is used to generate header files that
	may be installed into user space by "make header_install" or
	"make headers_install_all".  In order to support
	"make headers_install_all", this target has to be able to run
	on an unconfigured tree, or a tree configured for another
	architecture.

	It is run before "make archprepare" when run on the
	architecture itself.


--- 6.3 Add prerequisites to archprepare:
L
Linus Torvalds 已提交
962

963
	The archprepare: rule is used to list prerequisites that need to be
L
Linus Torvalds 已提交
964
	built before starting to descend down in the subdirectories.
965
	This is usually used for header files containing assembler constants.
L
Linus Torvalds 已提交
966 967

		Example:
968 969
		#arch/arm/Makefile
		archprepare: maketools
L
Linus Torvalds 已提交
970

971
	In this example, the file target maketools will be processed
972
	before descending down in the subdirectories.
L
Linus Torvalds 已提交
973 974 975 976
	See also chapter XXX-TODO that describe how kbuild supports
	generating offset header files.


977
--- 6.4 List directories to visit when descending
L
Linus Torvalds 已提交
978 979 980 981 982 983

	An arch Makefile cooperates with the top Makefile to define variables
	which specify how to build the vmlinux file.  Note that there is no
	corresponding arch-specific section for modules; the module-building
	machinery is all architecture-independent.

984

L
Linus Torvalds 已提交
985 986
    head-y, init-y, core-y, libs-y, drivers-y, net-y

987 988
	$(head-y) lists objects to be linked first in vmlinux.
	$(libs-y) lists directories where a lib.a archive can be located.
R
Randy Dunlap 已提交
989
	The rest list directories where a built-in.o object file can be
990
	located.
L
Linus Torvalds 已提交
991 992 993 994 995

	$(init-y) objects will be located after $(head-y).
	Then the rest follows in this order:
	$(core-y), $(libs-y), $(drivers-y) and $(net-y).

996
	The top level Makefile defines values for all generic directories,
R
Randy Dunlap 已提交
997
	and arch/$(ARCH)/Makefile only adds architecture-specific directories.
L
Linus Torvalds 已提交
998 999 1000 1001 1002 1003 1004 1005

	Example:
		#arch/sparc64/Makefile
		core-y += arch/sparc64/kernel/
		libs-y += arch/sparc64/prom/ arch/sparc64/lib/
		drivers-$(CONFIG_OPROFILE)  += arch/sparc64/oprofile/


1006
--- 6.5 Architecture-specific boot images
L
Linus Torvalds 已提交
1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024

	An arch Makefile specifies goals that take the vmlinux file, compress
	it, wrap it in bootstrapping code, and copy the resulting files
	somewhere. This includes various kinds of installation commands.
	The actual goals are not standardized across architectures.

	It is common to locate any additional processing in a boot/
	directory below arch/$(ARCH)/.

	Kbuild does not provide any smart way to support building a
	target specified in boot/. Therefore arch/$(ARCH)/Makefile shall
	call make manually to build a target in boot/.

	The recommended approach is to include shortcuts in
	arch/$(ARCH)/Makefile, and use the full path when calling down
	into the arch/$(ARCH)/boot/Makefile.

	Example:
1025 1026
		#arch/x86/Makefile
		boot := arch/x86/boot
L
Linus Torvalds 已提交
1027 1028 1029 1030 1031 1032
		bzImage: vmlinux
			$(Q)$(MAKE) $(build)=$(boot) $(boot)/$@

	"$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
	make in a subdirectory.

R
Randy Dunlap 已提交
1033
	There are no rules for naming architecture-specific targets,
L
Linus Torvalds 已提交
1034
	but executing "make help" will list all relevant targets.
1035
	To support this, $(archhelp) must be defined.
L
Linus Torvalds 已提交
1036 1037

	Example:
1038
		#arch/x86/Makefile
L
Linus Torvalds 已提交
1039 1040
		define archhelp
		  echo  '* bzImage      - Image (arch/$(ARCH)/boot/bzImage)'
1041
		endif
L
Linus Torvalds 已提交
1042 1043 1044 1045

	When make is executed without arguments, the first goal encountered
	will be built. In the top level Makefile the first goal present
	is all:.
1046 1047
	An architecture shall always, per default, build a bootable image.
	In "make help", the default goal is highlighted with a '*'.
L
Linus Torvalds 已提交
1048 1049 1050 1051
	Add a new prerequisite to all: to select a default goal different
	from vmlinux.

	Example:
1052
		#arch/x86/Makefile
1053
		all: bzImage
L
Linus Torvalds 已提交
1054 1055 1056

	When "make" is executed without arguments, bzImage will be built.

1057
--- 6.6 Building non-kbuild targets
L
Linus Torvalds 已提交
1058 1059 1060

    extra-y

1061
	extra-y specifies additional targets created in the current
L
Linus Torvalds 已提交
1062 1063 1064 1065 1066 1067 1068 1069
	directory, in addition to any targets specified by obj-*.

	Listing all targets in extra-y is required for two purposes:
	1) Enable kbuild to check changes in command lines
	   - When $(call if_changed,xxx) is used
	2) kbuild knows what files to delete during "make clean"

	Example:
1070
		#arch/x86/kernel/Makefile
L
Linus Torvalds 已提交
1071 1072
		extra-y := head.o init_task.o

1073
	In this example, extra-y is used to list object files that
L
Linus Torvalds 已提交
1074 1075
	shall be built, but shall not be linked as part of built-in.o.

1076

1077
--- 6.7 Commands useful for building a boot image
L
Linus Torvalds 已提交
1078 1079 1080 1081 1082 1083 1084 1085 1086 1087

	Kbuild provides a few macros that are useful when building a
	boot image.

    if_changed

	if_changed is the infrastructure used for the following commands.

	Usage:
		target: source(s) FORCE
1088
			$(call if_changed,ld/objcopy/gzip/...)
L
Linus Torvalds 已提交
1089

1090
	When the rule is evaluated, it is checked to see if any files
R
Randy Dunlap 已提交
1091
	need an update, or the command line has changed since the last
L
Linus Torvalds 已提交
1092 1093 1094 1095 1096 1097 1098
	invocation. The latter will force a rebuild if any options
	to the executable have changed.
	Any target that utilises if_changed must be listed in $(targets),
	otherwise the command line check will fail, and the target will
	always be built.
	Assignments to $(targets) are without $(obj)/ prefix.
	if_changed may be used in conjunction with custom commands as
1099
	defined in 6.8 "Custom kbuild commands".
1100

L
Linus Torvalds 已提交
1101
	Note: It is a typical mistake to forget the FORCE prerequisite.
1102 1103 1104 1105
	Another common pitfall is that whitespace is sometimes
	significant; for instance, the below will fail (note the extra space
	after the comma):
		target: source(s) FORCE
1106
	#WRONG!#	$(call if_changed, ld/objcopy/gzip/...)
L
Linus Torvalds 已提交
1107 1108

    ld
1109
	Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1110

L
Linus Torvalds 已提交
1111
	Example:
1112
		#arch/x86/boot/Makefile
L
Linus Torvalds 已提交
1113 1114 1115 1116 1117 1118 1119
		LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
		LDFLAGS_setup    := -Ttext 0x0 -s --oformat binary -e begtext

		targets += setup setup.o bootsect bootsect.o
		$(obj)/setup $(obj)/bootsect: %: %.o FORCE
			$(call if_changed,ld)

1120 1121
	In this example, there are two possible targets, requiring different
	options to the linker. The linker options are specified using the
L
Linus Torvalds 已提交
1122
	LDFLAGS_$@ syntax - one for each potential target.
M
Matt LaPlante 已提交
1123
	$(targets) are assigned all potential targets, by which kbuild knows
L
Linus Torvalds 已提交
1124 1125 1126 1127 1128
	the targets and will:
		1) check for commandline changes
		2) delete target during make clean

	The ": %: %.o" part of the prerequisite is a shorthand that
1129
	frees us from listing the setup.o and bootsect.o files.
1130
	Note: It is a common mistake to forget the "targets :=" assignment,
L
Linus Torvalds 已提交
1131 1132 1133
	      resulting in the target file being recompiled for no
	      obvious reason.

1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146
    objcopy
	Copy binary. Uses OBJCOPYFLAGS usually specified in
	arch/$(ARCH)/Makefile.
	OBJCOPYFLAGS_$@ may be used to set additional options.

    gzip
	Compress target. Use maximum compression to compress target.

	Example:
		#arch/x86/boot/compressed/Makefile
		$(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE
			$(call if_changed,gzip)

1147
    dtc
1148
	Create flattened device tree blob object suitable for linking
1149 1150 1151 1152
	into vmlinux. Device tree blobs linked into vmlinux are placed
	in an init section in the image. Platform code *must* copy the
	blob to non-init memory prior to calling unflatten_device_tree().

1153 1154
	To use this command, simply add *.dtb into obj-y or targets, or make
	some other target depend on %.dtb
1155

1156 1157
	A central rule exists to create $(obj)/%.dtb from $(src)/%.dts;
	architecture Makefiles do no need to explicitly write out that rule.
1158

1159 1160 1161 1162
	Example:
		targets += $(dtb-y)
		clean-files += *.dtb
		DTC_FLAGS ?= -p 1024
L
Linus Torvalds 已提交
1163

1164
--- 6.8 Custom kbuild commands
L
Linus Torvalds 已提交
1165

1166
	When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
L
Linus Torvalds 已提交
1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183
	of a command is normally displayed.
	To enable this behaviour for custom commands kbuild requires
	two variables to be set:
	quiet_cmd_<command>	- what shall be echoed
	      cmd_<command>	- the command to execute

	Example:
		#
		quiet_cmd_image = BUILD   $@
		      cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
		                                     $(obj)/vmlinux.bin > $@

		targets += bzImage
		$(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
			$(call if_changed,image)
			@echo 'Kernel: $@ is ready'

1184
	When updating the $(obj)/bzImage target, the line
L
Linus Torvalds 已提交
1185

1186
	BUILD    arch/x86/boot/bzImage
L
Linus Torvalds 已提交
1187 1188

	will be displayed with "make KBUILD_VERBOSE=0".
1189

L
Linus Torvalds 已提交
1190

1191
--- 6.9 Preprocessing linker scripts
L
Linus Torvalds 已提交
1192

1193
	When the vmlinux image is built, the linker script
L
Linus Torvalds 已提交
1194 1195 1196
	arch/$(ARCH)/kernel/vmlinux.lds is used.
	The script is a preprocessed variant of the file vmlinux.lds.S
	located in the same directory.
1197
	kbuild knows .lds files and includes a rule *lds.S -> *lds.
1198

L
Linus Torvalds 已提交
1199
	Example:
1200
		#arch/x86/kernel/Makefile
L
Linus Torvalds 已提交
1201
		always := vmlinux.lds
1202

L
Linus Torvalds 已提交
1203 1204
		#Makefile
		export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
1205 1206

	The assignment to $(always) is used to tell kbuild to build the
1207 1208
	target vmlinux.lds.
	The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
L
Linus Torvalds 已提交
1209
	specified options when building the target vmlinux.lds.
1210

1211
	When building the *.lds target, kbuild uses the variables:
1212
	KBUILD_CPPFLAGS	: Set in top-level Makefile
1213
	cppflags-y	: May be set in the kbuild makefile
1214
	CPPFLAGS_$(@F)  : Target-specific flags.
L
Linus Torvalds 已提交
1215 1216 1217
	                  Note that the full filename is used in this
	                  assignment.

1218
	The kbuild infrastructure for *lds files is used in several
R
Randy Dunlap 已提交
1219
	architecture-specific files.
L
Linus Torvalds 已提交
1220

1221
--- 6.10 Generic header files
S
Sam Ravnborg 已提交
1222 1223 1224 1225 1226

	The directory include/asm-generic contains the header files
	that may be shared between individual architectures.
	The recommended approach how to use a generic header file is
	to list the file in the Kbuild file.
1227
	See "7.2 generic-y" for further info on syntax etc.
S
Sam Ravnborg 已提交
1228

1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243
--- 6.11 Post-link pass

	If the file arch/xxx/Makefile.postlink exists, this makefile
	will be invoked for post-link objects (vmlinux and modules.ko)
	for architectures to run post-link passes on. Must also handle
	the clean target.

	This pass runs after kallsyms generation. If the architecture
	needs to modify symbol locations, rather than manipulate the
	kallsyms, it may be easier to add another postlink target for
	.tmp_vmlinux? targets to be called from link-vmlinux.sh.

	For example, powerpc uses this to check relocation sanity of
	the linked vmlinux file.

1244 1245
=== 7 Kbuild syntax for exported headers

1246
The kernel includes a set of headers that is exported to userspace.
1247
Many headers can be exported as-is but other headers require a
1248 1249
minimal pre-processing before they are ready for user-space.
The pre-processing does:
1250
- drop kernel-specific annotations
1251
- drop include of compiler.h
1252
- drop all sections that are kernel internal (guarded by ifdef __KERNEL__)
1253

1254
All headers under include/uapi/, include/generated/uapi/,
1255
arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/
1256
are exported.
1257

1258 1259 1260
A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and
arch/<arch>/include/asm/ to list asm files coming from asm-generic.
See subsequent chapter for the syntax of the Kbuild file.
1261

1262
--- 7.1 no-export-headers
1263

1264 1265 1266
	no-export-headers is essentially used by include/uapi/linux/Kbuild to
	avoid exporting specific headers (e.g. kvm.h) on architectures that do
	not support it. It should be avoided as much as possible.
1267

1268
--- 7.2 generic-y
S
Sam Ravnborg 已提交
1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293

	If an architecture uses a verbatim copy of a header from
	include/asm-generic then this is listed in the file
	arch/$(ARCH)/include/asm/Kbuild like this:

		Example:
			#arch/x86/include/asm/Kbuild
			generic-y += termios.h
			generic-y += rtc.h

	During the prepare phase of the build a wrapper include
	file is generated in the directory:

		arch/$(ARCH)/include/generated/asm

	When a header is exported where the architecture uses
	the generic header a similar wrapper is generated as part
	of the set of exported headers in the directory:

		usr/include/asm

	The generated wrapper will in both cases look like the following:

		Example: termios.h
			#include <asm-generic/termios.h>
1294

1295
--- 7.3 generated-y
1296 1297

	If an architecture generates other header files alongside generic-y
1298
	wrappers, generated-y specifies them.
1299 1300 1301 1302 1303 1304 1305 1306

	This prevents them being treated as stale asm-generic wrappers and
	removed.

		Example:
			#arch/x86/include/asm/Kbuild
			generated-y += syscalls_32.h

1307
--- 7.4 mandatory-y
1308 1309

	mandatory-y is essentially used by include/uapi/asm-generic/Kbuild.asm
1310
	to define the minimum set of headers that must be exported in
1311 1312 1313 1314 1315
	include/asm.

	The convention is to list one subdir per line and
	preferably in alphabetic order.

1316
=== 8 Kbuild Variables
L
Linus Torvalds 已提交
1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356

The top Makefile exports the following variables:

    VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION

	These variables define the current kernel version.  A few arch
	Makefiles actually use these values directly; they should use
	$(KERNELRELEASE) instead.

	$(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
	three-part version number, such as "2", "4", and "0".  These three
	values are always numeric.

	$(EXTRAVERSION) defines an even tinier sublevel for pre-patches
	or additional patches.	It is usually some non-numeric string
	such as "-pre4", and is often blank.

    KERNELRELEASE

	$(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
	for constructing installation directory names or showing in
	version strings.  Some arch Makefiles use it for this purpose.

    ARCH

	This variable defines the target architecture, such as "i386",
	"arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
	determine which files to compile.

	By default, the top Makefile sets $(ARCH) to be the same as the
	host system architecture.  For a cross build, a user may
	override the value of $(ARCH) on the command line:

	    make ARCH=m68k ...


    INSTALL_PATH

	This variable defines a place for the arch Makefiles to install
	the resident kernel image and System.map file.
R
Randy Dunlap 已提交
1357
	Use this for architecture-specific install targets.
L
Linus Torvalds 已提交
1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369

    INSTALL_MOD_PATH, MODLIB

	$(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
	installation.  This variable is not defined in the Makefile but
	may be passed in by the user if desired.

	$(MODLIB) specifies the directory for module installation.
	The top Makefile defines $(MODLIB) to
	$(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE).  The user may
	override this value on the command line if desired.

1370 1371
    INSTALL_MOD_STRIP

1372
	If this variable is specified, it will cause modules to be stripped
1373
	after they are installed.  If INSTALL_MOD_STRIP is '1', then the
1374
	default option --strip-debug will be used.  Otherwise, the
1375 1376
	INSTALL_MOD_STRIP value will be used as the option(s) to the strip
	command.
1377 1378


1379
=== 9 Makefile language
L
Linus Torvalds 已提交
1380

1381
The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
L
Linus Torvalds 已提交
1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397
use only the documented features of GNU Make, but they do use many
GNU extensions.

GNU Make supports elementary list-processing functions.  The kernel
Makefiles use a novel style of list building and manipulation with few
"if" statements.

GNU Make has two assignment operators, ":=" and "=".  ":=" performs
immediate evaluation of the right-hand side and stores an actual string
into the left-hand side.  "=" is like a formula definition; it stores the
right-hand side in an unevaluated form and then evaluates this form each
time the left-hand side is used.

There are some cases where "=" is appropriate.  Usually, though, ":="
is the right choice.

1398
=== 10 Credits
L
Linus Torvalds 已提交
1399 1400 1401 1402

Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
Updates by Sam Ravnborg <sam@ravnborg.org>
1403
Language QA by Jan Engelhardt <jengelh@gmx.de>
L
Linus Torvalds 已提交
1404

1405
=== 11 TODO
L
Linus Torvalds 已提交
1406

1407
- Describe how kbuild supports shipped files with _shipped.
L
Linus Torvalds 已提交
1408 1409 1410
- Generating offset header files.
- Add more variables to section 7?

1411 1412