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