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