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