makefiles.rst 50.7 KB
Newer Older
1
======================
Linus Torvalds's avatar
Linus Torvalds committed
2
Linux Kernel Makefiles
3
======================
Linus Torvalds's avatar
Linus Torvalds committed
4 5 6

This document describes the Linux kernel Makefiles.

7
.. Table of Contents
Linus Torvalds's avatar
Linus Torvalds committed
8 9 10 11 12 13 14 15 16 17 18

	=== 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
19
	   --- 3.8 <deleted>
Linus Torvalds's avatar
Linus Torvalds committed
20
	   --- 3.9 Dependency tracking
21
	   --- 3.10 Custom Rules
22
	   --- 3.11 $(CC) support functions
Sam Ravnborg's avatar
Sam Ravnborg committed
23
	   --- 3.12 $(LD) support functions
24
	   --- 3.13 Script Invocation
Linus Torvalds's avatar
Linus Torvalds committed
25 26 27 28

	=== 4 Host Program support
	   --- 4.1 Simple Host Program
	   --- 4.2 Composite Host Programs
29 30 31
	   --- 4.3 Using C++ for host programs
	   --- 4.4 Controlling compiler options for host programs
	   --- 4.5 When host programs are actually built
Linus Torvalds's avatar
Linus Torvalds committed
32

33 34 35 36 37 38 39 40 41 42
	=== 5 Userspace Program support
	   --- 5.1 Simple Userspace Program
	   --- 5.2 Composite Userspace Programs
	   --- 5.3 Controlling compiler options for userspace programs
	   --- 5.4 When userspace programs are actually built

	=== 6 Kbuild clean infrastructure

	=== 7 Architecture Makefiles
	   --- 7.1 Set variables to tweak the build to the architecture
43 44
	   --- 7.2 Add prerequisites to archheaders
	   --- 7.3 Add prerequisites to archprepare
45 46 47 48
	   --- 7.4 List directories to visit when descending
	   --- 7.5 Architecture-specific boot images
	   --- 7.6 Building non-kbuild targets
	   --- 7.7 Commands useful for building a boot image
49
	   --- 7.8 <deleted>
50 51 52 53 54 55 56 57 58 59 60 61 62 63
	   --- 7.9 Preprocessing linker scripts
	   --- 7.10 Generic header files
	   --- 7.11 Post-link pass

	=== 8 Kbuild syntax for exported headers
		--- 8.1 no-export-headers
		--- 8.2 generic-y
		--- 8.3 generated-y
		--- 8.4 mandatory-y

	=== 9 Kbuild Variables
	=== 10 Makefile language
	=== 11 Credits
	=== 12 TODO
Linus Torvalds's avatar
Linus Torvalds committed
64

65 66
1 Overview
==========
Linus Torvalds's avatar
Linus Torvalds committed
67

68
The Makefiles have five parts::
Linus Torvalds's avatar
Linus Torvalds committed
69

70 71 72 73 74
	Makefile                    the top Makefile.
	.config                     the kernel configuration file.
	arch/$(SRCARCH)/Makefile    the arch Makefile.
	scripts/Makefile.*          common rules etc. for all kbuild Makefiles.
	kbuild Makefiles            exist in every subdirectory
Linus Torvalds's avatar
Linus Torvalds committed
75 76 77 78 79 80 81 82 83 84

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
85
with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies
Linus Torvalds's avatar
Linus Torvalds committed
86 87 88 89
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
90
.config file to construct various file lists used by kbuild to build
Linus Torvalds's avatar
Linus Torvalds committed
91 92 93 94 95 96
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.


97 98
2 Who does what
===============
Linus Torvalds's avatar
Linus Torvalds committed
99 100 101 102 103 104 105 106 107

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
108
maintain the kbuild Makefiles for the subsystem they are
Linus Torvalds's avatar
Linus Torvalds committed
109 110 111 112 113 114 115 116 117 118 119 120 121 122
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.


123 124
3 The kbuild files
==================
Linus Torvalds's avatar
Linus Torvalds committed
125 126

Most Makefiles within the kernel are kbuild Makefiles that use the
127
kbuild infrastructure. This chapter introduces the syntax used in the
Linus Torvalds's avatar
Linus Torvalds committed
128
kbuild makefiles.
129
The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
130
be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
131
file will be used.
Linus Torvalds's avatar
Linus Torvalds committed
132

133
Section 3.1 "Goal definitions" is a quick intro; further chapters provide
Linus Torvalds's avatar
Linus Torvalds committed
134 135
more details, with real examples.

136 137
3.1 Goal definitions
--------------------
Linus Torvalds's avatar
Linus Torvalds committed
138 139 140 141 142 143 144

	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:

145 146
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
147 148
		obj-y += foo.o

Randy Dunlap's avatar
Randy Dunlap committed
149
	This tells kbuild that there is one object in that directory, named
Linus Torvalds's avatar
Linus Torvalds committed
150 151 152 153 154
	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:

155 156
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
157 158 159 160 161 162
		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.

163 164
3.2 Built-in object goals - obj-y
---------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
165 166

	The kbuild Makefile specifies object files for vmlinux
167
	in the $(obj-y) lists.  These lists depend on the kernel
Linus Torvalds's avatar
Linus Torvalds committed
168 169 170
	configuration.

	Kbuild compiles all the $(obj-y) files.  It then calls
171
	"$(AR) rcSTP" to merge these files into one built-in.a file.
172 173
	This is a thin archive without a symbol table. It will be later
	linked into vmlinux by scripts/link-vmlinux.sh
Linus Torvalds's avatar
Linus Torvalds committed
174 175 176

	The order of files in $(obj-y) is significant.  Duplicates in
	the lists are allowed: the first instance will be linked into
177
	built-in.a and succeeding instances will be ignored.
Linus Torvalds's avatar
Linus Torvalds committed
178 179 180 181

	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
182 183
	order may e.g. change the order in which your SCSI
	controllers are detected, and thus your disks are renumbered.
Linus Torvalds's avatar
Linus Torvalds committed
184

185 186
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
187 188 189
		#drivers/isdn/i4l/Makefile
		# Makefile for the kernel ISDN subsystem and device drivers.
		# Each configuration option enables a list of files.
190
		obj-$(CONFIG_ISDN_I4L)         += isdn.o
Linus Torvalds's avatar
Linus Torvalds committed
191 192
		obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o

193 194
3.3 Loadable module goals - obj-m
---------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
195

196
	$(obj-m) specifies object files which are built as loadable
Linus Torvalds's avatar
Linus Torvalds committed
197 198 199 200 201 202
	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).

203 204
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
205 206 207 208 209 210
		#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
211 212 213 214
	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.
Linus Torvalds's avatar
Linus Torvalds committed
215

216 217
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
218
		#drivers/isdn/i4l/Makefile
219 220
		obj-$(CONFIG_ISDN_I4L) += isdn.o
		isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
Linus Torvalds's avatar
Linus Torvalds committed
221 222

	In this example, the module name will be isdn.o. Kbuild will
223
	compile the objects listed in $(isdn-y) and then run
Linus Torvalds's avatar
Linus Torvalds committed
224 225
	"$(LD) -r" on the list of these files to generate isdn.o.

226
	Due to kbuild recognizing $(<module_name>-y) for composite objects,
227
	you can use the value of a `CONFIG_` symbol to optionally include an
228
	object file as part of a composite object.
Linus Torvalds's avatar
Linus Torvalds committed
229

230 231
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
232
		#fs/ext2/Makefile
233 234 235 236 237 238 239 240 241
	        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'.
Linus Torvalds's avatar
Linus Torvalds committed
242 243 244 245

	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
246
	parts and then link this into built-in.a, as you would expect.
Linus Torvalds's avatar
Linus Torvalds committed
247

248 249
3.4 Objects which export symbols
--------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
250 251 252 253

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

254 255
3.5 Library file goals - lib-y
------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
256

257
	Objects listed with obj-* are used for modules, or
258
	combined in a built-in.a for that specific directory.
Linus Torvalds's avatar
Linus Torvalds committed
259 260 261 262
	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.
263 264 265
	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.
266
	For consistency, objects listed in lib-m will be included in lib.a.
Linus Torvalds's avatar
Linus Torvalds committed
267 268 269

	Note that the same kbuild makefile may list files to be built-in
	and to be part of a library. Therefore the same directory
270
	may contain both a built-in.a and a lib.a file.
Linus Torvalds's avatar
Linus Torvalds committed
271

272 273
	Example::

274 275
		#arch/x86/lib/Makefile
		lib-y    := delay.o
Linus Torvalds's avatar
Linus Torvalds committed
276

277 278 279
	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.
280

281
	See also "7.4 List directories to visit when descending".
282

283
	Use of lib-y is normally restricted to `lib/` and `arch/*/lib`.
Linus Torvalds's avatar
Linus Torvalds committed
284

285 286
3.6 Descending down in directories
----------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
287 288 289 290 291 292 293

	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.

294
	To do so, obj-y and obj-m are used.
Linus Torvalds's avatar
Linus Torvalds committed
295 296 297
	ext2 lives in a separate directory, and the Makefile present in fs/
	tells kbuild to descend down using the following assignment.

298 299
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
300 301 302 303 304 305
		#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.
306 307 308 309 310 311 312 313 314 315 316 317 318

	Kbuild uses this information not only to decide that it needs to visit
	the directory, but also to decide whether or not to link objects from
	the directory into vmlinux.

	When Kbuild descends into the directory with 'y', all built-in objects
	from that directory are combined into the built-in.a, which will be
	eventually linked into vmlinux.

	When Kbuild descends into the directory with 'm', in contrast, nothing
	from that directory will be linked into vmlinux. If the Makefile in
	that directory specifies obj-y, those objects will be left orphan.
	It is very likely a bug of the Makefile or of dependencies in Kconfig.
Linus Torvalds's avatar
Linus Torvalds committed
319

320
	It is good practice to use a `CONFIG_` variable when assigning directory
Linus Torvalds's avatar
Linus Torvalds committed
321
	names. This allows kbuild to totally skip the directory if the
322
	corresponding `CONFIG_` option is neither 'y' nor 'm'.
Linus Torvalds's avatar
Linus Torvalds committed
323

324 325
3.7 Compilation flags
---------------------
Linus Torvalds's avatar
Linus Torvalds committed
326

327
    ccflags-y, asflags-y and ldflags-y
328 329 330
	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.
331
	Note: Flags with the same behaviour were previously named:
332 333
	EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
	They are still supported but their usage is deprecated.
Linus Torvalds's avatar
Linus Torvalds committed
334

335
	ccflags-y specifies options for compiling with $(CC).
Linus Torvalds's avatar
Linus Torvalds committed
336

337 338
	Example::

339 340 341
		# drivers/acpi/acpica/Makefile
		ccflags-y			:= -Os -D_LINUX -DBUILDING_ACPICA
		ccflags-$(CONFIG_ACPI_DEBUG)	+= -DACPI_DEBUG_OUTPUT
Linus Torvalds's avatar
Linus Torvalds committed
342 343

	This variable is necessary because the top Makefile owns the
344
	variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
Linus Torvalds's avatar
Linus Torvalds committed
345 346
	entire tree.

347
	asflags-y specifies assembler options.
Linus Torvalds's avatar
Linus Torvalds committed
348

349 350
	Example::

351 352
		#arch/sparc/kernel/Makefile
		asflags-y := -ansi
Linus Torvalds's avatar
Linus Torvalds committed
353

354
	ldflags-y specifies options for linking with $(LD).
Linus Torvalds's avatar
Linus Torvalds committed
355

356 357
	Example::

358 359
		#arch/cris/boot/compressed/Makefile
		ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
Linus Torvalds's avatar
Linus Torvalds committed
360

361
    subdir-ccflags-y, subdir-asflags-y
362
	The two flags listed above are similar to ccflags-y and asflags-y.
363 364 365 366
	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.
367

368 369
	Example::

370 371
		subdir-ccflags-y := -Werror

372 373 374 375 376 377 378 379
    ccflags-remove-y, asflags-remove-y
	These flags are used to remove particular flags for the compiler,
	assembler invocations.

	Example::

		ccflags-remove-$(CONFIG_MCOUNT) += -pg

Linus Torvalds's avatar
Linus Torvalds committed
380 381 382 383 384 385 386
    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.

387 388 389
	CFLAGS_$@ has the higher priority than ccflags-remove-y; CFLAGS_$@
	can re-add compiler flags that were removed by ccflags-remove-y.

390 391
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
392 393 394 395 396
		# drivers/scsi/Makefile
		CFLAGS_aha152x.o =   -DAHA152X_STAT -DAUTOCONF
		CFLAGS_gdth.o    = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
				     -DGDTH_STATISTICS

397
	These two lines specify compilation flags for aha152x.o and gdth.o.
Linus Torvalds's avatar
Linus Torvalds committed
398 399 400 401

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

402 403 404
	AFLAGS_$@ has the higher priority than asflags-remove-y; AFLAGS_$@
	can re-add assembler flags that were removed by asflags-remove-y.

405 406
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
407
		# arch/arm/kernel/Makefile
408 409 410 411
		AFLAGS_head.o        := -DTEXT_OFFSET=$(TEXT_OFFSET)
		AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
		AFLAGS_iwmmxt.o      := -Wa,-mcpu=iwmmxt

Linus Torvalds's avatar
Linus Torvalds committed
412

413 414
3.9 Dependency tracking
-----------------------
Linus Torvalds's avatar
Linus Torvalds committed
415 416

	Kbuild tracks dependencies on the following:
417

418 419
	1) All prerequisite files (both `*.c` and `*.h`)
	2) `CONFIG_` options used in all prerequisite files
Linus Torvalds's avatar
Linus Torvalds committed
420 421 422 423 424
	3) Command-line used to compile target

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

425
3.10 Custom Rules
426
------------------
Linus Torvalds's avatar
Linus Torvalds committed
427

428
	Custom rules are used when the kbuild infrastructure does
Linus Torvalds's avatar
Linus Torvalds committed
429 430
	not provide the required support. A typical example is
	header files generated during the build process.
Randy Dunlap's avatar
Randy Dunlap committed
431
	Another example are the architecture-specific Makefiles which
432
	need custom rules to prepare boot images etc.
Linus Torvalds's avatar
Linus Torvalds committed
433

434
	Custom rules are written as normal Make rules.
Linus Torvalds's avatar
Linus Torvalds committed
435
	Kbuild is not executing in the directory where the Makefile is
436
	located, so all custom rules shall use a relative
Linus Torvalds's avatar
Linus Torvalds committed
437 438
	path to prerequisite files and target files.

439
	Two variables are used when defining custom rules:
Linus Torvalds's avatar
Linus Torvalds committed
440

441 442 443 444 445 446 447 448 449
	$(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.
Linus Torvalds's avatar
Linus Torvalds committed
450

451
	    Example::
Linus Torvalds's avatar
Linus Torvalds committed
452 453 454 455 456

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

457
	    This is a custom rule, following the normal syntax
458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473
	    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).

	$(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.
	    To support this kbuild defines $(kecho) which will echo out the
	    text following $(kecho) to stdout except if "make -s" is used.

	Example::

474 475 476 477
		# arch/arm/Makefile
		$(BOOT_TARGETS): vmlinux
			$(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@
			@$(kecho) '  Kernel: $(boot)/$@ is ready'
478

479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500
	When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
	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::

		# lib/Makefile
		quiet_cmd_crc32 = GEN     $@
		      cmd_crc32 = $< > $@

		$(obj)/crc32table.h: $(obj)/gen_crc32table
			$(call cmd,crc32)

	When updating the $(obj)/crc32table.h target, the line:

		  GEN     lib/crc32table.h

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

502 503
3.11 $(CC) support functions
----------------------------
504

505
	The kernel may be built with several different versions of
506
	$(CC), each supporting a unique set of features and options.
507
	kbuild provides basic support to check for valid options for $(CC).
508
	$(CC) is usually the gcc compiler, but other alternatives are
509 510 511
	available.

    as-option
512
	as-option is used to check if $(CC) -- when used to compile
513
	assembler (`*.S`) files -- supports the given option. An optional
514
	second option may be specified if the first option is not supported.
515

516 517
	Example::

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

521
	In the above example, cflags-y will be assigned the option
522 523
	-Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
	The second argument is optional, and if supplied will be used
524 525
	if first argument is not supported.

526 527 528 529
    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
530
	Note: as-instr-option uses KBUILD_AFLAGS for assembler options
531

532
    cc-option
533 534
	cc-option is used to check if $(CC) supports a given option, and if
	not supported to use an optional second option.
535

536 537
	Example::

538
		#arch/x86/Makefile
539 540
		cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)

Randy Dunlap's avatar
Randy Dunlap committed
541
	In the above example, cflags-y will be assigned the option
542 543
	-march=pentium-mmx if supported by $(CC), otherwise -march=i586.
	The second argument to cc-option is optional, and if omitted,
544
	cflags-y will be assigned no value if first option is not supported.
545
	Note: cc-option uses KBUILD_CFLAGS for $(CC) options
546 547

   cc-option-yn
548
	cc-option-yn is used to check if gcc supports a given option
549 550
	and return 'y' if supported, otherwise 'n'.

551 552
	Example::

553 554 555 556
		#arch/ppc/Makefile
		biarch := $(call cc-option-yn, -m32)
		aflags-$(biarch) += -a32
		cflags-$(biarch) += -m32
557

558 559 560 561
	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.
562
	Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
563

564 565 566 567 568 569
    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.

570 571
	Example::

572 573 574 575 576
		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.

577
    cc-ifversion
578 579 580
	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.
581

582 583
	Example::

584
		#fs/reiserfs/Makefile
585
		ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
586

587
	In this example, ccflags-y will be assigned the value -O1 if the
588
	$(CC) version is less than 4.2.
589
	cc-ifversion takes all the shell operators:
590 591 592 593
	-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.

594
    cc-cross-prefix
595
	cc-cross-prefix is used to check if there exists a $(CC) in path with
596 597 598 599 600
	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.
601 602
	This functionality is useful for architecture Makefiles that try
	to set CROSS_COMPILE to well-known values but may have several
603
	values to select between.
604 605
	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
606 607
	is already set then leave it with the old value.

608 609
	Example::

610 611 612 613 614 615 616
		#arch/m68k/Makefile
		ifneq ($(SUBARCH),$(ARCH))
		        ifeq ($(CROSS_COMPILE),)
		               CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
			endif
		endif

617 618
3.12 $(LD) support functions
----------------------------
Sam Ravnborg's avatar
Sam Ravnborg committed
619 620 621 622 623 624 625

    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).

626 627
	Example::

Sam Ravnborg's avatar
Sam Ravnborg committed
628
		#Makefile
629
		LDFLAGS_vmlinux += $(call ld-option, -X)
Sam Ravnborg's avatar
Sam Ravnborg committed
630

631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649
3.13 Script invocation
----------------------

	Make rules may invoke scripts to build the kernel. The rules shall
	always provide the appropriate interpreter to execute the script. They
	shall not rely on the execute bits being set, and shall not invoke the
	script directly. For the convenience of manual script invocation, such
	as invoking ./scripts/checkpatch.pl, it is recommended to set execute
	bits on the scripts nonetheless.

	Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL),
	$(PYTHON) and $(PYTHON3) to refer to interpreters for the respective
	scripts.

	Example::

		#Makefile
		cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \
			     $(KERNELRELEASE)
Sam Ravnborg's avatar
Sam Ravnborg committed
650

651 652
4 Host Program support
======================
Linus Torvalds's avatar
Linus Torvalds committed
653 654 655 656 657 658

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
659
done utilising the variable "hostprogs".
Linus Torvalds's avatar
Linus Torvalds committed
660 661

The second step is to add an explicit dependency to the executable.
662
This can be done in two ways. Either add the dependency in a rule,
663
or utilise the variable "always-y".
Linus Torvalds's avatar
Linus Torvalds committed
664 665
Both possibilities are described in the following.

666 667
4.1 Simple Host Program
-----------------------
Linus Torvalds's avatar
Linus Torvalds committed
668 669 670 671 672 673

	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.

674 675
	Example::

676
		hostprogs := bin2hex
Linus Torvalds's avatar
Linus Torvalds committed
677 678 679 680

	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.
681

682 683
4.2 Composite Host Programs
---------------------------
Linus Torvalds's avatar
Linus Torvalds committed
684 685 686 687

	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.
688
	$(<executable>-objs) lists all objects used to link the final
Linus Torvalds's avatar
Linus Torvalds committed
689 690
	executable.

691 692
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
693
		#scripts/lxdialog/Makefile
694
		hostprogs     := lxdialog
Linus Torvalds's avatar
Linus Torvalds committed
695 696 697
		lxdialog-objs := checklist.o lxdialog.o

	Objects with extension .o are compiled from the corresponding .c
698
	files. In the above example, checklist.c is compiled to checklist.o
Linus Torvalds's avatar
Linus Torvalds committed
699
	and lxdialog.c is compiled to lxdialog.o.
700

701
	Finally, the two .o files are linked to the executable, lxdialog.
Linus Torvalds's avatar
Linus Torvalds committed
702 703
	Note: The syntax <executable>-y is not permitted for host-programs.

704 705
4.3 Using C++ for host programs
-------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
706 707 708 709 710

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

711 712
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
713
		#scripts/kconfig/Makefile
714
		hostprogs     := qconf
Linus Torvalds's avatar
Linus Torvalds committed
715 716 717 718
		qconf-cxxobjs := qconf.o

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

720
	If qconf is composed of a mixture of .c and .cc files, then an
Linus Torvalds's avatar
Linus Torvalds committed
721 722
	additional line can be used to identify this.

723 724
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
725
		#scripts/kconfig/Makefile
726
		hostprogs     := qconf
Linus Torvalds's avatar
Linus Torvalds committed
727 728
		qconf-cxxobjs := qconf.o
		qconf-objs    := check.o
729

730 731
4.4 Controlling compiler options for host programs
--------------------------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
732 733 734

	When compiling host programs, it is possible to set specific flags.
	The programs will always be compiled utilising $(HOSTCC) passed
735
	the options specified in $(KBUILD_HOSTCFLAGS).
Linus Torvalds's avatar
Linus Torvalds committed
736
	To set flags that will take effect for all host programs created
737
	in that Makefile, use the variable HOST_EXTRACFLAGS.
Linus Torvalds's avatar
Linus Torvalds committed
738

739 740
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
741 742
		#scripts/lxdialog/Makefile
		HOST_EXTRACFLAGS += -I/usr/include/ncurses
743

Linus Torvalds's avatar
Linus Torvalds committed
744 745 746
	To set specific flags for a single file the following construction
	is used:

747 748
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
749 750
		#arch/ppc64/boot/Makefile
		HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
751

Linus Torvalds's avatar
Linus Torvalds committed
752
	It is also possible to specify additional options to the linker.
753

754 755
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
756
		#scripts/kconfig/Makefile
757
		HOSTLDLIBS_qconf := -L$(QTDIR)/lib
Linus Torvalds's avatar
Linus Torvalds committed
758

759 760
	When linking qconf, it will be passed the extra option
	"-L$(QTDIR)/lib".
761

762 763
4.5 When host programs are actually built
-----------------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
764 765 766 767 768

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

769
	(1) List the prerequisite explicitly in a custom rule.
Linus Torvalds's avatar
Linus Torvalds committed
770

771 772
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
773
		#drivers/pci/Makefile
774
		hostprogs := gen-devlist
Linus Torvalds's avatar
Linus Torvalds committed
775 776 777
		$(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
			( cd $(obj); ./gen-devlist ) < $<

778
	The target $(obj)/devlist.h will not be built before
Linus Torvalds's avatar
Linus Torvalds committed
779
	$(obj)/gen-devlist is updated. Note that references to
780
	the host programs in custom rules must be prefixed with $(obj).
Linus Torvalds's avatar
Linus Torvalds committed
781

782
	(2) Use always-y
783

784
	When there is no suitable custom rule, and the host program
785
	shall be built when a makefile is entered, the always-y
Linus Torvalds's avatar
Linus Torvalds committed
786 787
	variable shall be used.

788 789
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
790
		#scripts/lxdialog/Makefile
791 792
		hostprogs     := lxdialog
		always-y      := $(hostprogs)
Linus Torvalds's avatar
Linus Torvalds committed
793

794 795 796 797
	Kbuild provides the following shorthand for this:

		hostprogs-always-y := lxdialog

Linus Torvalds's avatar
Linus Torvalds committed
798 799 800
	This will tell kbuild to build lxdialog even if not referenced in
	any rule.

801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879
5 Userspace Program support
===========================

Just like host programs, Kbuild also supports building userspace executables
for the target architecture (i.e. the same architecture as you are building
the kernel for).

The syntax is quite similar. The difference is to use "userprogs" instead of
"hostprogs".

5.1 Simple Userspace Program
----------------------------

	The following line tells kbuild that the program bpf-direct shall be
	built for the target architecture.

	Example::

		userprogs := bpf-direct

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

5.2 Composite Userspace Programs
--------------------------------

	Userspace programs can be made up based on composite objects.
	The syntax used to define composite objects for userspace programs is
	similar to the syntax used for kernel objects.
	$(<executable>-objs) lists all objects used to link the final
	executable.

	Example::

		#samples/seccomp/Makefile
		userprogs      := bpf-fancy
		bpf-fancy-objs := bpf-fancy.o bpf-helper.o

	Objects with extension .o are compiled from the corresponding .c
	files. In the above example, bpf-fancy.c is compiled to bpf-fancy.o
	and bpf-helper.c is compiled to bpf-helper.o.

	Finally, the two .o files are linked to the executable, bpf-fancy.
	Note: The syntax <executable>-y is not permitted for userspace programs.

5.3 Controlling compiler options for userspace programs
-------------------------------------------------------

	When compiling userspace programs, it is possible to set specific flags.
	The programs will always be compiled utilising $(CC) passed
	the options specified in $(KBUILD_USERCFLAGS).
	To set flags that will take effect for all userspace programs created
	in that Makefile, use the variable userccflags.

	Example::

		# samples/seccomp/Makefile
		userccflags += -I usr/include

	To set specific flags for a single file the following construction
	is used:

	Example::

		bpf-helper-userccflags += -I user/include

	It is also possible to specify additional options to the linker.

	Example::

		# net/bpfilter/Makefile
		bpfilter_umh-userldflags += -static

	When linking bpfilter_umh, it will be passed the extra option -static.

5.4 When userspace programs are actually built
----------------------------------------------

880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905
	Kbuild builds userspace programs only when told to do so.
	There are two ways to do this.

	(1) Add it as the prerequisite of another file

	Example::

		#net/bpfilter/Makefile
		userprogs := bpfilter_umh
		$(obj)/bpfilter_umh_blob.o: $(obj)/bpfilter_umh

	$(obj)/bpfilter_umh is built before $(obj)/bpfilter_umh_blob.o

	(2) Use always-y

	Example::

		userprogs := binderfs_example
		always-y := $(userprogs)

	Kbuild provides the following shorthand for this:

		userprogs-always-y := binderfs_example

	This will tell Kbuild to build binderfs_example when it visits this
	Makefile.
906 907

6 Kbuild clean infrastructure
908
=============================
Linus Torvalds's avatar
Linus Torvalds committed
909

910
"make clean" deletes most generated files in the obj tree where the kernel
Linus Torvalds's avatar
Linus Torvalds committed
911
is compiled. This includes generated files such as host programs.
912 913 914 915 916
Kbuild knows targets listed in $(hostprogs), $(always-y), $(always-m),
$(always-), $(extra-y), $(extra-) 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
source tree when "make clean" is executed.
Linus Torvalds's avatar
Linus Torvalds committed
917

918 919
Additional files or directories can be specified in kbuild makefiles by use of
$(clean-files).
Linus Torvalds's avatar
Linus Torvalds committed
920

921 922
	Example::

923 924
		#lib/Makefile
		clean-files := crc32table.h
Linus Torvalds's avatar
Linus Torvalds committed
925

926 927
When executing "make clean", the file "crc32table.h" will be deleted.
Kbuild will assume files to be in the same relative directory as the
928
Makefile, except if prefixed with $(objtree).
Linus Torvalds's avatar
Linus Torvalds committed
929

930 931
To exclude certain files or directories from make clean, use the
$(no-clean-files) variable.
932

Linus Torvalds's avatar
Linus Torvalds committed
933 934 935 936
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.

937 938
	Example::

939
		#arch/x86/boot/Makefile
940
		subdir- := compressed
Linus Torvalds's avatar
Linus Torvalds committed
941 942 943 944

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

945
To support the clean infrastructure in the Makefiles that build the
Linus Torvalds's avatar
Linus Torvalds committed
946 947
final bootimage there is an optional target named archclean:

948 949
	Example::

950
		#arch/x86/Makefile
Linus Torvalds's avatar
Linus Torvalds committed
951
		archclean:
952
			$(Q)$(MAKE) $(clean)=arch/x86/boot
Linus Torvalds's avatar
Linus Torvalds committed
953

954 955
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
Linus Torvalds's avatar
Linus Torvalds committed
956 957
the subdir- trick to descend further down.

958
Note 1: arch/$(SRCARCH)/Makefile cannot use "subdir-", because that file is
Linus Torvalds's avatar
Linus Torvalds committed
959 960 961 962 963 964
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".

965
7 Architecture Makefiles
966
========================
Linus Torvalds's avatar
Linus Torvalds committed
967 968 969

The top level Makefile sets up the environment and does the preparation,
before starting to descend down in the individual directories.
970
The top level makefile contains the generic part, whereas
971
arch/$(SRCARCH)/Makefile contains what is required to set up kbuild
972
for said architecture.
973
To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines
Linus Torvalds's avatar
Linus Torvalds committed
974 975
a few targets.

976
When kbuild executes, the following steps are followed (roughly):
977

978
1) Configuration of the kernel => produce .config
Linus Torvalds's avatar
Linus Torvalds committed
979
2) Store kernel version in include/linux/version.h
980
3) Updating all other prerequisites to the target prepare:
981
   - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile
982
4) Recursively descend down in all directories listed in
Linus Torvalds's avatar
Linus Torvalds committed
983
   init-* core* drivers-* net-* libs-* and build all targets.
984
   - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile.
985
5) All object files are then linked and the resulting file vmlinux is
986
   located at the root of the obj tree.
Linus Torvalds's avatar
Linus Torvalds committed
987
   The very first objects linked are listed in head-y, assigned by
988
   arch/$(SRCARCH)/Makefile.
989
6) Finally, the architecture-specific part does any required post processing
Linus Torvalds's avatar
Linus Torvalds committed
990 991
   and builds the final bootimage.
   - This includes building boot records
Randy Dunlap's avatar
Randy Dunlap committed
992
   - Preparing initrd images and the like
Linus Torvalds's avatar
Linus Torvalds committed
993 994


995
7.1 Set variables to tweak the build to the architecture
996
--------------------------------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
997

998
    KBUILD_LDFLAGS
999
	Generic $(LD) options
Linus Torvalds's avatar
Linus Torvalds committed
1000 1001 1002 1003

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

1004 1005
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
1006
		#arch/s390/Makefile
1007
		KBUILD_LDFLAGS         := -m elf_s390
1008

1009
	Note: ldflags-y can be used to further customise
1010
	the flags used. See section 3.7.
1011

1012 1013
    LDFLAGS_vmlinux
	Options for $(LD) when linking vmlinux
Linus Torvalds's avatar
Linus Torvalds committed
1014 1015

	LDFLAGS_vmlinux is used to specify additional flags to pass to
1016
	the linker when linking the final vmlinux image.
Linus Torvalds's avatar
Linus Torvalds committed
1017 1018
	LDFLAGS_vmlinux uses the LDFLAGS_$@ support.

1019 1020
	Example::

1021
		#arch/x86/Makefile
Linus Torvalds's avatar
Linus Torvalds committed
1022 1023
		LDFLAGS_vmlinux := -e stext

1024 1025
    OBJCOPYFLAGS
	objcopy flags
Linus Torvalds's avatar
Linus Torvalds committed
1026 1027

	When $(call if_changed,objcopy) is used to translate a .o file,
1028
	the flags specified in OBJCOPYFLAGS will be used.
Linus Torvalds's avatar
Linus Torvalds committed
1029 1030 1031
	$(call if_changed,objcopy) is often used to generate raw binaries on
	vmlinux.

1032 1033
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
1034 1035 1036 1037 1038 1039 1040
		#arch/s390/Makefile
		OBJCOPYFLAGS := -O binary

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

1041
	In this example, the binary $(obj)/image is a binary version of
Linus Torvalds's avatar
Linus Torvalds committed
1042 1043
	vmlinux. The usage of $(call if_changed,xxx) will be described later.

1044
    KBUILD_AFLAGS
1045
	Assembler flags
Linus Torvalds's avatar
Linus Torvalds committed
1046 1047 1048 1049

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

1050 1051
	Example::

Linus Torvalds's avatar
Linus Torvalds committed
1052
		#arch/sparc64/Makefile
1053
		KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
Linus Torvalds's avatar
Linus Torvalds committed
1054

1055 1056
    KBUILD_CFLAGS
	$(CC) compiler flags
Linus Torvalds's avatar
Linus Torvalds committed
1057 1058 1059 1060

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

1061
	Often, the KBUILD_CFLAGS variable depends on the configuration.
Linus Torvalds's avatar
Linus Torvalds committed
1062

1063 1064
	Example::

1065 1066 1067
		#arch/x86/boot/compressed/Makefile
		cflags-$(CONFIG_X86_32) := -march=i386
		cflags-$(CONFIG_X86_64) := -mcmodel=small
1068
		KBUILD_CFLAGS += $(cflags-y)
Linus Torvalds's avatar
Linus Torvalds committed
1069 1070

	Many arch Makefiles dynamically run the target C compiler to
1071
	probe supported options::
Linus Torvalds's avatar
Linus Torvalds committed
1072

1073
		#arch/x86/Makefile
Linus Torvalds's avatar
Linus Torvalds committed
1074 1075 1076 1077 1078 1079

		...
		cflags-$(CONFIG_MPENTIUMII)     += $(call cc-option,\
						-march=pentium2,-march=i686)
		...
		# Disable unit-at-a-time mode ...
1080
		KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
Linus Torvalds's avatar
Linus Torvalds committed
1081 1082 1083
		...


1084
	The first example utilises the trick that a config option expands
Linus Torvalds's avatar
Linus Torvalds committed
1085 1086
	to 'y' when selected.

1087
    KBUILD_AFLAGS_KERNEL
1088
	Assembler options specific for built-in
Linus Torvalds's avatar
Linus Torvalds committed
1089

1090
	$(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
Linus Torvalds's avatar
Linus Torvalds committed
1091 1092
	resident kernel code.

1093
    KBUILD_AFLAGS_MODULE
1094
	Assembler options specific for modules
Linus Torvalds's avatar
Linus Torvalds committed
1095

1096
	$(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
1097
	are used for assembler.
1098

1099
	From commandline AFLAGS_MODULE shall be used (see kbuild.rst).
Linus Torvalds's avatar
Linus Torvalds committed
1100

1101 1102
    KBUILD_CFLAGS_KERNEL
	$(CC) options specific for built-in
1103 1104 1105 1106

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

1107 1108
    KBUILD_CFLAGS_MODULE
	Options for $(CC) when building modules
1109

1110
	$(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
1111
	are used for $(CC).
1112
	From commandline CFLAGS_MODULE shall be used (see kbuild.rst).
1113

1114 1115
    KBUILD_LDFLAGS_MODULE
	Options for $(LD) when linking modules
1116

1117
	$(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options
1118
	used when linking modules. This is often a linker script.
1119

1120
	From commandline LDFLAGS_MODULE shall be used (see kbuild.rst).
1121

1122 1123 1124 1125
    KBUILD_LDS

	The linker script with full path. Assigned by the top-level Makefile.

1126 1127 1128 1129 1130
    KBUILD_LDS_MODULE

	The module linker script with full path. Assigned by the top-level
	Makefile and additionally by the arch Makefile.

1131 1132 1133 1134 1135 1136 1137 1138 1139 1140
    KBUILD_VMLINUX_OBJS

	All object files for vmlinux. They are linked to vmlinux in the same
	order as listed in KBUILD_VMLINUX_OBJS.

    KBUILD_VMLINUX_LIBS

	All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and
	KBUILD_VMLINUX_LIBS together specify all the object files used to
	link vmlinux.
1141

1142
7.2 Add prerequisites to archheaders
1143
------------------------------------
1144 1145

	The archheaders: rule is used to generate header files that
1146
	may be installed into user space by "make header_install".
1147 1148 1149 1150 1151

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


1152
7.3 Add prerequisites to archprepare
1153
------------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
1154

1155
	The archprepare: rule is used to list prerequisites that need to be
Linus Torvalds's avatar
Linus Torvalds committed
1156
	built before starting to descend down in the subdirectories.
1157
	This is usually used for header files containing assembler constants.
Linus Torvalds's avatar
Linus Torvalds committed
1158

1159 1160
	Example::

1161 1162
		#arch/arm/Makefile
		archprepare: maketools
Linus Torvalds's avatar
Linus Torvalds committed
1163

1164
	In this example, the file target maketools will be processed
1165
	before descending down in the subdirectories.
1166
	See also chapter XXX-TODO that describes how kbuild supports
Linus Torvalds's avatar
Linus Torvalds committed
1167 1168 1169
	generating offset header files.


1170
7.4 List directories to visit when descending
1171
---------------------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
1172 1173 1174 1175 1176 1177

	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.

1178

1179
	head-y, core-y, libs-y, drivers-y
1180 1181 1182 1183 1184 1185
	    $(head-y) lists objects to be linked first in vmlinux.

	    $(libs-y) lists directories where a lib.a archive can be located.

	    The rest list directories where a built-in.a object file can be
	    located.
Linus Torvalds's avatar
Linus Torvalds committed
1186

1187
	    Then the rest follows in this order:
Linus Torvalds's avatar
Linus Torvalds committed
1188

1189
		$(core-y), $(libs-y), $(drivers-y)
1190 1191

	    The top level Makefile defines values for all generic directories,
1192
	    and arch/$(SRCARCH)/Makefile only adds architecture-specific
1193 1194 1195
	    directories.

	    Example::
Linus Torvalds's avatar
Linus Torvalds committed
1196

1197 1198 1199 1200 1201
		# arch/sparc/Makefile
		core-y                 += arch/sparc/

		libs-y                 += arch/sparc/prom/
		libs-y                 += arch/sparc/lib/
Linus Torvalds's avatar
Linus Torvalds committed
1202

1203 1204
		drivers-$(CONFIG_PM) += arch/sparc/power/
		drivers-$(CONFIG_OPROFILE)	+= arch/sparc/oprofile/
Linus Torvalds's avatar
Linus Torvalds committed
1205

1206
7.5 Architecture-specific boot images
1207
-------------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
1208 1209 1210 1211 1212 1213 1214

	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/
1215
	directory below arch/$(SRCARCH)/.
Linus Torvalds's avatar
Linus Torvalds committed
1216 1217

	Kbuild does not provide any smart way to support building a
1218
	target specified in boot/. Therefore arch/$(SRCARCH)/Makefile shall
Linus Torvalds's avatar
Linus Torvalds committed
1219 1220 1221
	call make manually to build a target in boot/.

	The recommended approach is to include shortcuts in
1222 1223
	arch/$(SRCARCH)/Makefile, and use the full path when calling down
	into the arch/$(SRCARCH)/boot/Makefile.
Linus Torvalds's avatar
Linus Torvalds committed
1224

1225 1226
	Example::

1227 1228
		#arch/x86/Makefile
		boot := arch/x86/boot
Linus Torvalds's avatar
Linus Torvalds committed
1229 1230 1231 1232 1233 1234
		bzImage: vmlinux
			$(Q)$(MAKE) $(build)=$(boot) $(boot)/$@

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

Randy Dunlap's avatar
Randy Dunlap committed
1235
	There are no rules for naming architecture-specific targets,
Linus Torvalds's avatar
Linus Torvalds committed
1236
	but executing "make help" will list all relevant targets.
1237
	To support this, $(archhelp) must be defined.
Linus Torvalds's avatar
Linus Torvalds committed
1238

1239 1240
	Example::

1241
		#arch/x86/Makefile
Linus Torvalds's avatar
Linus Torvalds committed
1242
		define archhelp
1243
		  echo  '* bzImage      - Compressed kernel image (arch/x86/boot/bzImage)'
1244
		endif
Linus Torvalds's avatar
Linus Torvalds committed
1245 1246 1247 1248

	When make is executed without arguments, the first goal encountered
	will be built. In the top level Makefile the first goal present
	is all:.
1249 1250
	An architecture shall always, per default, build a bootable image.
	In "make help", the default goal is highlighted with a '*'.
Linus Torvalds's avatar
Linus Torvalds committed
1251 1252 1253
	Add a new prerequisite to all: to select a default goal different
	from vmlinux.

1254 1255
	Example::

1256
		#arch/x86/Makefile
1257
		all: bzImage
Linus Torvalds's avatar
Linus Torvalds committed
1258 1259 1260

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

1261
7.6 Building non-kbuild targets
1262
-------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
1263 1264

    extra-y
1265
	extra-y specifies additional targets created in the current
1266
	directory, in addition to any targets specified by `obj-*`.
Linus Torvalds's avatar
Linus Torvalds committed
1267 1268

	Listing all targets in extra-y is required for two purposes:
1269

Linus Torvalds's avatar
Linus Torvalds committed
1270
	1) Enable kbuild to check changes in command lines
1271

Linus Torvalds's avatar
Linus Torvalds committed
1272
	   - When $(call if_changed,xxx) is used
1273

Linus Torvalds's avatar
Linus Torvalds committed
1274 1275
	2) kbuild knows what files to delete during "make clean"

1276 1277
	Example::

1278
		#arch/x86/kernel/Makefile
Linus Torvalds's avatar
Linus Torvalds committed
1279 1280
		extra-y := head.o init_task.o

1281
	In this example, extra-y is used to list object files that
1282
	shall be built, but shall not be linked as part of built-in.a.
Linus Torvalds's avatar
Linus Torvalds committed
1283

1284
7.7 Commands useful for building a boot image
1285
---------------------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
1286

1287 1288
    Kbuild provides a few macros that are useful when building a
    boot image.
Linus Torvalds's avatar
Linus Torvalds committed
1289 1290 1291 1292

    if_changed
	if_changed is the infrastructure used for the following commands.

1293 1294
	Usage::

Linus Torvalds's avatar
Linus Torvalds committed
1295
		target: source(s) FORCE
1296
			$(call if_changed,ld/objcopy/gzip/...)
Linus Torvalds's avatar
Linus Torvalds committed
1297

1298
	When the rule is evaluated, it is checked to see if any files
Randy Dunlap's avatar
Randy Dunlap committed
1299
	need an update, or the command line has changed since the last
Linus Torvalds's avatar
Linus Torvalds committed
1300 1301 1302 1303 1304 1305
	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.
1306 1307
	if_changed may be used in conjunction with custom rules as
	defined in "3.10 Custom Rules".
1308

Linus Torvalds's avatar
Linus Torvalds committed
1309
	Note: It is a typical mistake to forget the FORCE prerequisite.
1310 1311
	Another common pitfall is that whitespace is sometimes
	significant; for instance, the below will fail (note the extra space
1312 1313
	after the comma)::

1314
		target: source(s) FORCE
Linus Torvalds's avatar
Linus Torvalds committed
1315

1316 1317 1318 1319
	**WRONG!**	$(call if_changed, ld/objcopy/gzip/...)

        Note:
	      if_changed should not be used more than once per target.
1320
              It stores the executed command in a corresponding .cmd
1321

1322 1323 1324 1325
        file and multiple calls would result in overwrites and
        unwanted results when the target is up to date and only the
        tests on changed commands trigger execution of commands.

Linus Torvalds's avatar
Linus Torvalds committed
1326
    ld
1327
	Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1328

1329 1330
	Example::

1331
		#arch/x86/boot/Makefile
Linus Torvalds's avatar
Linus Torvalds committed
1332 1333 1334 1335 1336 1337 1338
		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)

1339 1340
	In this example, there are two possible targets, requiring different
	options to the linker. The linker options are specified using the
Linus Torvalds's avatar
Linus Torvalds committed
1341
	LDFLAGS_$@ syntax - one for each potential target.
1342
	$(targets) are assigned all potential targets, by which kbuild knows
Linus Torvalds's avatar
Linus Torvalds committed
1343
	the targets and will:
1344

Linus Torvalds's avatar
Linus Torvalds committed
1345 1346 1347 1348
		1) check for commandline changes
		2) delete target during make clean

	The ": %: %.o" part of the prerequisite is a shorthand that
1349
	frees us from listing the setup.o and bootsect.o files.
1350 1351 1352

	Note:
	      It is a common mistake to forget the "targets :=" assignment,
Linus Torvalds's avatar
Linus Torvalds committed
1353 1354 1355
	      resulting in the target file being recompiled for no
	      obvious reason.

1356 1357
    objcopy
	Copy binary. Uses OBJCOPYFLAGS usually specified in
1358
	arch/$(SRCARCH)/Makefile.
1359 1360 1361 1362 1363
	OBJCOPYFLAGS_$@ may be used to set additional options.

    gzip
	Compress target. Use maximum compression to compress target.

1364 1365
	Example::

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

1370
    dtc
1371
	Create flattened device tree blob object suitable for linking
1372 1373 1374 1375
	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().

1376 1377
	To use this command, simply add `*.dtb` into obj-y or targets, or make
	some other target depend on `%.dtb`
1378

1379
	A central rule exists to create `$(obj)/%.dtb` from `$(src)/%.dts`;
1380
	architecture Makefiles do no need to explicitly write out that rule.
1381

1382 1383
	Example::

1384 1385
		targets += $(dtb-y)
		DTC_FLAGS ?= -p 1024
Linus Torvalds's avatar
Linus Torvalds committed
1386

1387
7.9 Preprocessing linker scripts
1388
--------------------------------
Linus Torvalds's avatar
Linus Torvalds committed
1389

1390
	When the vmlinux image is built, the linker script
1391
	arch/$(SRCARCH)/kernel/vmlinux.lds is used.
Linus Torvalds's avatar
Linus Torvalds committed
1392 1393
	The script is a preprocessed variant of the file vmlinux.lds.S
	located in the same directory.
1394 1395 1396
	kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`.

	Example::
1397

1398
		#arch/x86/kernel/Makefile
1399
		extra-y := vmlinux.lds
1400

1401
	The assignment to extra-y is used to tell kbuild to build the
1402 1403
	target vmlinux.lds.
	The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
Linus Torvalds's avatar
Linus Torvalds committed
1404
	specified options when building the target vmlinux.lds.
1405

1406 1407 1408 1409 1410 1411 1412
	When building the `*.lds` target, kbuild uses the variables::

		KBUILD_CPPFLAGS	: Set in top-level Makefile
		cppflags-y	: May be set in the kbuild makefile
		CPPFLAGS_$(@F)  : Target-specific flags.
				Note that the full filename is used in this
				assignment.
Linus Torvalds's avatar
Linus Torvalds committed
1413

1414
	The kbuild infrastructure for `*lds` files is used in several
Randy Dunlap's avatar
Randy Dunlap committed
1415
	architecture-specific files.
Linus Torvalds's avatar
Linus Torvalds committed
1416

1417
7.10 Generic header files
1418
-------------------------
Sam Ravnborg's avatar
Sam Ravnborg committed
1419 1420 1421 1422 1423

	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.
1424
	See "8.2 generic-y" for further info on syntax etc.
Sam Ravnborg's avatar
Sam Ravnborg committed
1425

1426
7.11 Post-link pass
1427
-------------------
1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441

	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.

1442
8 Kbuild syntax for exported headers
1443
------------------------------------
1444

1445
The kernel includes a set of headers that is exported to userspace.
1446
Many headers can be exported as-is but other headers require a
1447 1448
minimal pre-processing before they are ready for user-space.
The pre-processing does:
1449

1450
- drop kernel-specific annotations
1451
- drop include of compiler.h
1452
- drop all sections that are kernel internal (guarded by `ifdef __KERNEL__`)
1453

1454
All headers under include/uapi/, include/generated/uapi/,
1455
arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/
1456
are exported.
1457

1458 1459 1460
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.
1461

1462
8.1 no-export-headers
1463
---------------------
1464

1465 1466 1467
	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.
1468

1469
8.2 generic-y
1470
-------------
Sam Ravnborg's avatar
Sam Ravnborg committed
1471 1472 1473

	If an architecture uses a verbatim copy of a header from
	include/asm-generic then this is listed in the file
1474
	arch/$(SRCARCH)/include/asm/Kbuild like this:
Sam Ravnborg's avatar
Sam Ravnborg committed
1475

1476 1477
		Example::

Sam Ravnborg's avatar
Sam Ravnborg committed
1478 1479 1480 1481 1482
			#arch/x86/include/asm/Kbuild
			generic-y += termios.h
			generic-y += rtc.h

	During the prepare phase of the build a wrapper include
1483
	file is generated in the directory::
Sam Ravnborg's avatar
Sam Ravnborg committed
1484

1485
		arch/$(SRCARCH)/include/generated/asm
Sam Ravnborg's avatar
Sam Ravnborg committed
1486 1487 1488

	When a header is exported where the architecture uses
	the generic header a similar wrapper is generated as part
1489
	of the set of exported headers in the directory::
Sam Ravnborg's avatar
Sam Ravnborg committed
1490 1491 1492 1493 1494

		usr/include/asm

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

1495 1496
		Example: termios.h::

Sam Ravnborg's avatar
Sam Ravnborg committed
1497
			#include <asm-generic/termios.h>
1498

1499
8.3 generated-y
1500
---------------
1501 1502

	If an architecture generates other header files alongside generic-y
1503
	wrappers, generated-y specifies them.
1504 1505 1506 1507

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

1508 1509
		Example::

1510 1511 1512
			#arch/x86/include/asm/Kbuild
			generated-y += syscalls_32.h

1513
8.4 mandatory-y
1514
---------------
1515

1516
	mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild
1517 1518 1519
	to define the minimum set of ASM headers that all architectures must have.

	This works like optional generic-y. If a mandatory header is missing
1520 1521
	in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically
	generate a wrapper of the asm-generic one.
1522

1523
9 Kbuild Variables
1524
==================
Linus Torvalds's avatar
Linus Torvalds committed
1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552

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
1553
	override the value of $(ARCH) on the command line::
Linus Torvalds's avatar
Linus Torvalds committed
1554 1555 1556

	    make ARCH=m68k ...

1557 1558 1559 1560 1561 1562 1563 1564 1565 1566
    SRCARCH
	This variable specifies the directory in arch/ to build.

	ARCH and SRCARCH may not necessarily match. A couple of arch
	directories are biarch, that is, a single `arch/*/` directory supports
	both 32-bit and 64-bit.

	For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86.
	For all of them, SRCARCH=x86 because arch/x86/ supports	both i386 and
	x86_64.
Linus Torvalds's avatar
Linus Torvalds committed
1567 1568 1569 1570

    INSTALL_PATH
	This variable defines a place for the arch Makefiles to install
	the resident kernel image and System.map file.
Randy Dunlap's avatar
Randy Dunlap committed
1571
	Use this for architecture-specific install targets.
Linus Torvalds's avatar
Linus Torvalds committed
1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582

    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.

1583
    INSTALL_MOD_STRIP
1584
	If this variable is specified, it will cause modules to be stripped
1585
	after they are installed.  If INSTALL_MOD_STRIP is '1', then the
1586
	default option --strip-debug will be used.  Otherwise, the
1587 1588
	INSTALL_MOD_STRIP value will be used as the option(s) to the strip
	command.
1589 1590


1591 1592
10 Makefile language
====================
Linus Torvalds's avatar
Linus Torvalds committed
1593

1594
The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
Linus Torvalds's avatar
Linus Torvalds committed
1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610
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.

1611
11 Credits
1612
==========
Linus Torvalds's avatar
Linus Torvalds committed
1613

1614 1615 1616 1617
- 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>
- Language QA by Jan Engelhardt <jengelh@gmx.de>
Linus Torvalds's avatar
Linus Torvalds committed
1618

1619
12 TODO
1620
=======
Linus Torvalds's avatar
Linus Torvalds committed
1621

1622
- Describe how kbuild supports shipped files with _shipped.
Linus Torvalds's avatar
Linus Torvalds committed
1623
- Generating offset header files.
1624
- Add more variables to chapters 7 or 9?