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 ia64. 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 294$(extra-y) should only contain targets needed for vmlinux. 295 296Kbuild skips extra-y when vmlinux is apparently not a final goal. 297(e.g. ``make modules``, or building external modules) 298 299If you intend to build targets unconditionally, always-y (explained 300in the next section) is the correct syntax to use. 301 302Always built goals - always-y 303----------------------------- 304 305always-y specifies targets which are literally always built when 306Kbuild visits the Makefile. 307 308Example:: 309 310 # ./Kbuild 311 offsets-file := include/generated/asm-offsets.h 312 always-y += $(offsets-file) 313 314Compilation flags 315----------------- 316 317ccflags-y, asflags-y and ldflags-y 318 These three flags apply only to the kbuild makefile in which they 319 are assigned. They are used for all the normal cc, as and ld 320 invocations happening during a recursive build. 321 Note: Flags with the same behaviour were previously named: 322 EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS. 323 They are still supported but their usage is deprecated. 324 325 ccflags-y specifies options for compiling with $(CC). 326 327 Example:: 328 329 # drivers/acpi/acpica/Makefile 330 ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA 331 ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT 332 333 This variable is necessary because the top Makefile owns the 334 variable $(KBUILD_CFLAGS) and uses it for compilation flags for the 335 entire tree. 336 337 asflags-y specifies assembler options. 338 339 Example:: 340 341 #arch/sparc/kernel/Makefile 342 asflags-y := -ansi 343 344 ldflags-y specifies options for linking with $(LD). 345 346 Example:: 347 348 #arch/cris/boot/compressed/Makefile 349 ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds 350 351subdir-ccflags-y, subdir-asflags-y 352 The two flags listed above are similar to ccflags-y and asflags-y. 353 The difference is that the subdir- variants have effect for the kbuild 354 file where they are present and all subdirectories. 355 Options specified using subdir-* are added to the commandline before 356 the options specified using the non-subdir variants. 357 358 Example:: 359 360 subdir-ccflags-y := -Werror 361 362ccflags-remove-y, asflags-remove-y 363 These flags are used to remove particular flags for the compiler, 364 assembler invocations. 365 366 Example:: 367 368 ccflags-remove-$(CONFIG_MCOUNT) += -pg 369 370CFLAGS_$@, AFLAGS_$@ 371 CFLAGS_$@ and AFLAGS_$@ only apply to commands in current 372 kbuild makefile. 373 374 $(CFLAGS_$@) specifies per-file options for $(CC). The $@ 375 part has a literal value which specifies the file that it is for. 376 377 CFLAGS_$@ has the higher priority than ccflags-remove-y; CFLAGS_$@ 378 can re-add compiler flags that were removed by ccflags-remove-y. 379 380 Example:: 381 382 # drivers/scsi/Makefile 383 CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF 384 385 This line specify compilation flags for aha152x.o. 386 387 $(AFLAGS_$@) is a similar feature for source files in assembly 388 languages. 389 390 AFLAGS_$@ has the higher priority than asflags-remove-y; AFLAGS_$@ 391 can re-add assembler flags that were removed by asflags-remove-y. 392 393 Example:: 394 395 # arch/arm/kernel/Makefile 396 AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET) 397 AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312 398 AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt 399 400Dependency tracking 401------------------- 402 403Kbuild tracks dependencies on the following: 404 4051) All prerequisite files (both ``*.c`` and ``*.h``) 4062) ``CONFIG_`` options used in all prerequisite files 4073) Command-line used to compile target 408 409Thus, if you change an option to $(CC) all affected files will 410be re-compiled. 411 412Custom Rules 413------------ 414 415Custom rules are used when the kbuild infrastructure does 416not provide the required support. A typical example is 417header files generated during the build process. 418Another example are the architecture-specific Makefiles which 419need custom rules to prepare boot images etc. 420 421Custom rules are written as normal Make rules. 422Kbuild is not executing in the directory where the Makefile is 423located, so all custom rules shall use a relative 424path to prerequisite files and target files. 425 426Two variables are used when defining custom rules: 427 428$(src) 429 $(src) is a relative path which points to the directory 430 where the Makefile is located. Always use $(src) when 431 referring to files located in the src tree. 432 433$(obj) 434 $(obj) is a relative path which points to the directory 435 where the target is saved. Always use $(obj) when 436 referring to generated files. 437 438 Example:: 439 440 #drivers/scsi/Makefile 441 $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl 442 $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl 443 444 This is a custom rule, following the normal syntax 445 required by make. 446 447 The target file depends on two prerequisite files. References 448 to the target file are prefixed with $(obj), references 449 to prerequisites are referenced with $(src) (because they are not 450 generated files). 451 452$(kecho) 453 echoing information to user in a rule is often a good practice 454 but when execution ``make -s`` one does not expect to see any output 455 except for warnings/errors. 456 To support this kbuild defines $(kecho) which will echo out the 457 text following $(kecho) to stdout except if ``make -s`` is used. 458 459 Example:: 460 461 # arch/arm/Makefile 462 $(BOOT_TARGETS): vmlinux 463 $(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@ 464 @$(kecho) ' Kernel: $(boot)/$@ is ready' 465 466 When kbuild is executing with KBUILD_VERBOSE unset, then only a shorthand 467 of a command is normally displayed. 468 To enable this behaviour for custom commands kbuild requires 469 two variables to be set:: 470 471 quiet_cmd_<command> - what shall be echoed 472 cmd_<command> - the command to execute 473 474 Example:: 475 476 # lib/Makefile 477 quiet_cmd_crc32 = GEN $@ 478 cmd_crc32 = $< > $@ 479 480 $(obj)/crc32table.h: $(obj)/gen_crc32table 481 $(call cmd,crc32) 482 483 When updating the $(obj)/crc32table.h target, the line:: 484 485 GEN lib/crc32table.h 486 487 will be displayed with ``make KBUILD_VERBOSE=``. 488 489Command change detection 490------------------------ 491 492When the rule is evaluated, timestamps are compared between the target 493and its prerequisite files. GNU Make updates the target when any of the 494prerequisites is newer than that. 495 496The target should be rebuilt also when the command line has changed 497since the last invocation. This is not supported by Make itself, so 498Kbuild achieves this by a kind of meta-programming. 499 500if_changed is the macro used for this purpose, in the following form:: 501 502 quiet_cmd_<command> = ... 503 cmd_<command> = ... 504 505 <target>: <source(s)> FORCE 506 $(call if_changed,<command>) 507 508Any target that utilizes if_changed must be listed in $(targets), 509otherwise the command line check will fail, and the target will 510always be built. 511 512If the target is already listed in the recognized syntax such as 513obj-y/m, lib-y/m, extra-y/m, always-y/m, hostprogs, userprogs, Kbuild 514automatically adds it to $(targets). Otherwise, the target must be 515explicitly added to $(targets). 516 517Assignments to $(targets) are without $(obj)/ prefix. if_changed may be 518used in conjunction with custom rules as defined in `Custom Rules`_. 519 520Note: It is a typical mistake to forget the FORCE prerequisite. 521Another common pitfall is that whitespace is sometimes significant; for 522instance, the below will fail (note the extra space after the comma):: 523 524 target: source(s) FORCE 525 526**WRONG!** $(call if_changed, objcopy) 527 528Note: 529 if_changed should not be used more than once per target. 530 It stores the executed command in a corresponding .cmd 531 file and multiple calls would result in overwrites and 532 unwanted results when the target is up to date and only the 533 tests on changed commands trigger execution of commands. 534 535$(CC) support functions 536----------------------- 537 538The kernel may be built with several different versions of 539$(CC), each supporting a unique set of features and options. 540kbuild provides basic support to check for valid options for $(CC). 541$(CC) is usually the gcc compiler, but other alternatives are 542available. 543 544as-option 545 as-option is used to check if $(CC) -- when used to compile 546 assembler (``*.S``) files -- supports the given option. An optional 547 second option may be specified if the first option is not supported. 548 549 Example:: 550 551 #arch/sh/Makefile 552 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),) 553 554 In the above example, cflags-y will be assigned the option 555 -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC). 556 The second argument is optional, and if supplied will be used 557 if first argument is not supported. 558 559as-instr 560 as-instr checks if the assembler reports a specific instruction 561 and then outputs either option1 or option2 562 C escapes are supported in the test instruction 563 Note: as-instr-option uses KBUILD_AFLAGS for assembler options 564 565cc-option 566 cc-option is used to check if $(CC) supports a given option, and if 567 not supported to use an optional second option. 568 569 Example:: 570 571 #arch/x86/Makefile 572 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586) 573 574 In the above example, cflags-y will be assigned the option 575 -march=pentium-mmx if supported by $(CC), otherwise -march=i586. 576 The second argument to cc-option is optional, and if omitted, 577 cflags-y will be assigned no value if first option is not supported. 578 Note: cc-option uses KBUILD_CFLAGS for $(CC) options 579 580cc-option-yn 581 cc-option-yn is used to check if gcc supports a given option 582 and return "y" if supported, otherwise "n". 583 584 Example:: 585 586 #arch/ppc/Makefile 587 biarch := $(call cc-option-yn, -m32) 588 aflags-$(biarch) += -a32 589 cflags-$(biarch) += -m32 590 591 In the above example, $(biarch) is set to y if $(CC) supports the -m32 592 option. When $(biarch) equals "y", the expanded variables $(aflags-y) 593 and $(cflags-y) will be assigned the values -a32 and -m32, 594 respectively. 595 596 Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options 597 598cc-disable-warning 599 cc-disable-warning checks if gcc supports a given warning and returns 600 the commandline switch to disable it. This special function is needed, 601 because gcc 4.4 and later accept any unknown -Wno-* option and only 602 warn about it if there is another warning in the source file. 603 604 Example:: 605 606 KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable) 607 608 In the above example, -Wno-unused-but-set-variable will be added to 609 KBUILD_CFLAGS only if gcc really accepts it. 610 611gcc-min-version 612 gcc-min-version tests if the value of $(CONFIG_GCC_VERSION) is greater than 613 or equal to the provided value and evaluates to y if so. 614 615 Example:: 616 617 cflags-$(call gcc-min-version, 70100) := -foo 618 619 In this example, cflags-y will be assigned the value -foo if $(CC) is gcc and 620 $(CONFIG_GCC_VERSION) is >= 7.1. 621 622clang-min-version 623 clang-min-version tests if the value of $(CONFIG_CLANG_VERSION) is greater 624 than or equal to the provided value and evaluates to y if so. 625 626 Example:: 627 628 cflags-$(call clang-min-version, 110000) := -foo 629 630 In this example, cflags-y will be assigned the value -foo if $(CC) is clang 631 and $(CONFIG_CLANG_VERSION) is >= 11.0.0. 632 633cc-cross-prefix 634 cc-cross-prefix is used to check if there exists a $(CC) in path with 635 one of the listed prefixes. The first prefix where there exist a 636 prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found 637 then nothing is returned. 638 639 Additional prefixes are separated by a single space in the 640 call of cc-cross-prefix. 641 642 This functionality is useful for architecture Makefiles that try 643 to set CROSS_COMPILE to well-known values but may have several 644 values to select between. 645 646 It is recommended only to try to set CROSS_COMPILE if it is a cross 647 build (host arch is different from target arch). And if CROSS_COMPILE 648 is already set then leave it with the old value. 649 650 Example:: 651 652 #arch/m68k/Makefile 653 ifneq ($(SUBARCH),$(ARCH)) 654 ifeq ($(CROSS_COMPILE),) 655 CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-) 656 endif 657 endif 658 659$(LD) support functions 660----------------------- 661 662ld-option 663 ld-option is used to check if $(LD) supports the supplied option. 664 ld-option takes two options as arguments. 665 666 The second argument is an optional option that can be used if the 667 first option is not supported by $(LD). 668 669 Example:: 670 671 #Makefile 672 LDFLAGS_vmlinux += $(call ld-option, -X) 673 674Script invocation 675----------------- 676 677Make rules may invoke scripts to build the kernel. The rules shall 678always provide the appropriate interpreter to execute the script. They 679shall not rely on the execute bits being set, and shall not invoke the 680script directly. For the convenience of manual script invocation, such 681as invoking ./scripts/checkpatch.pl, it is recommended to set execute 682bits on the scripts nonetheless. 683 684Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL), 685and $(PYTHON3) to refer to interpreters for the respective 686scripts. 687 688Example:: 689 690 #Makefile 691 cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \ 692 $(KERNELRELEASE) 693 694Host Program support 695==================== 696 697Kbuild supports building executables on the host for use during the 698compilation stage. 699 700Two steps are required in order to use a host executable. 701 702The first step is to tell kbuild that a host program exists. This is 703done utilising the variable ``hostprogs``. 704 705The second step is to add an explicit dependency to the executable. 706This can be done in two ways. Either add the dependency in a rule, 707or utilise the variable ``always-y``. 708Both possibilities are described in the following. 709 710Simple Host Program 711------------------- 712 713In some cases there is a need to compile and run a program on the 714computer where the build is running. 715 716The following line tells kbuild that the program bin2hex shall be 717built on the build host. 718 719Example:: 720 721 hostprogs := bin2hex 722 723Kbuild assumes in the above example that bin2hex is made from a single 724c-source file named bin2hex.c located in the same directory as 725the Makefile. 726 727Composite Host Programs 728----------------------- 729 730Host programs can be made up based on composite objects. 731The syntax used to define composite objects for host programs is 732similar to the syntax used for kernel objects. 733$(<executable>-objs) lists all objects used to link the final 734executable. 735 736Example:: 737 738 #scripts/lxdialog/Makefile 739 hostprogs := lxdialog 740 lxdialog-objs := checklist.o lxdialog.o 741 742Objects with extension .o are compiled from the corresponding .c 743files. In the above example, checklist.c is compiled to checklist.o 744and lxdialog.c is compiled to lxdialog.o. 745 746Finally, the two .o files are linked to the executable, lxdialog. 747Note: The syntax <executable>-y is not permitted for host-programs. 748 749Using C++ for host programs 750--------------------------- 751 752kbuild offers support for host programs written in C++. This was 753introduced solely to support kconfig, and is not recommended 754for general use. 755 756Example:: 757 758 #scripts/kconfig/Makefile 759 hostprogs := qconf 760 qconf-cxxobjs := qconf.o 761 762In the example above the executable is composed of the C++ file 763qconf.cc - identified by $(qconf-cxxobjs). 764 765If qconf is composed of a mixture of .c and .cc files, then an 766additional line can be used to identify this. 767 768Example:: 769 770 #scripts/kconfig/Makefile 771 hostprogs := qconf 772 qconf-cxxobjs := qconf.o 773 qconf-objs := check.o 774 775Using Rust for host programs 776---------------------------- 777 778Kbuild offers support for host programs written in Rust. However, 779since a Rust toolchain is not mandatory for kernel compilation, 780it may only be used in scenarios where Rust is required to be 781available (e.g. when ``CONFIG_RUST`` is enabled). 782 783Example:: 784 785 hostprogs := target 786 target-rust := y 787 788Kbuild will compile ``target`` using ``target.rs`` as the crate root, 789located in the same directory as the ``Makefile``. The crate may 790consist of several source files (see ``samples/rust/hostprogs``). 791 792Controlling compiler options for host programs 793---------------------------------------------- 794 795When compiling host programs, it is possible to set specific flags. 796The programs will always be compiled utilising $(HOSTCC) passed 797the options specified in $(KBUILD_HOSTCFLAGS). 798 799To set flags that will take effect for all host programs created 800in that Makefile, use the variable HOST_EXTRACFLAGS. 801 802Example:: 803 804 #scripts/lxdialog/Makefile 805 HOST_EXTRACFLAGS += -I/usr/include/ncurses 806 807To set specific flags for a single file the following construction 808is used: 809 810Example:: 811 812 #arch/ppc64/boot/Makefile 813 HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE) 814 815It is also possible to specify additional options to the linker. 816 817Example:: 818 819 #scripts/kconfig/Makefile 820 HOSTLDLIBS_qconf := -L$(QTDIR)/lib 821 822When linking qconf, it will be passed the extra option 823``-L$(QTDIR)/lib``. 824 825When host programs are actually built 826------------------------------------- 827 828Kbuild will only build host-programs when they are referenced 829as a prerequisite. 830 831This is possible in two ways: 832 833(1) List the prerequisite explicitly in a custom rule. 834 835 Example:: 836 837 #drivers/pci/Makefile 838 hostprogs := gen-devlist 839 $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist 840 ( cd $(obj); ./gen-devlist ) < $< 841 842 The target $(obj)/devlist.h will not be built before 843 $(obj)/gen-devlist is updated. Note that references to 844 the host programs in custom rules must be prefixed with $(obj). 845 846(2) Use always-y 847 848 When there is no suitable custom rule, and the host program 849 shall be built when a makefile is entered, the always-y 850 variable shall be used. 851 852 Example:: 853 854 #scripts/lxdialog/Makefile 855 hostprogs := lxdialog 856 always-y := $(hostprogs) 857 858 Kbuild provides the following shorthand for this:: 859 860 hostprogs-always-y := lxdialog 861 862 This will tell kbuild to build lxdialog even if not referenced in 863 any rule. 864 865Userspace Program support 866========================= 867 868Just like host programs, Kbuild also supports building userspace executables 869for the target architecture (i.e. the same architecture as you are building 870the kernel for). 871 872The syntax is quite similar. The difference is to use ``userprogs`` instead of 873``hostprogs``. 874 875Simple Userspace Program 876------------------------ 877 878The following line tells kbuild that the program bpf-direct shall be 879built for the target architecture. 880 881Example:: 882 883 userprogs := bpf-direct 884 885Kbuild assumes in the above example that bpf-direct is made from a 886single C source file named bpf-direct.c located in the same directory 887as the Makefile. 888 889Composite Userspace Programs 890---------------------------- 891 892Userspace programs can be made up based on composite objects. 893The syntax used to define composite objects for userspace programs is 894similar to the syntax used for kernel objects. 895$(<executable>-objs) lists all objects used to link the final 896executable. 897 898Example:: 899 900 #samples/seccomp/Makefile 901 userprogs := bpf-fancy 902 bpf-fancy-objs := bpf-fancy.o bpf-helper.o 903 904Objects with extension .o are compiled from the corresponding .c 905files. In the above example, bpf-fancy.c is compiled to bpf-fancy.o 906and bpf-helper.c is compiled to bpf-helper.o. 907 908Finally, the two .o files are linked to the executable, bpf-fancy. 909Note: The syntax <executable>-y is not permitted for userspace programs. 910 911Controlling compiler options for userspace programs 912--------------------------------------------------- 913 914When compiling userspace programs, it is possible to set specific flags. 915The programs will always be compiled utilising $(CC) passed 916the options specified in $(KBUILD_USERCFLAGS). 917 918To set flags that will take effect for all userspace programs created 919in that Makefile, use the variable userccflags. 920 921Example:: 922 923 # samples/seccomp/Makefile 924 userccflags += -I usr/include 925 926To set specific flags for a single file the following construction 927is used: 928 929Example:: 930 931 bpf-helper-userccflags += -I user/include 932 933It is also possible to specify additional options to the linker. 934 935Example:: 936 937 # net/bpfilter/Makefile 938 bpfilter_umh-userldflags += -static 939 940When linking bpfilter_umh, it will be passed the extra option -static. 941 942From command line, :ref:`USERCFLAGS and USERLDFLAGS <userkbuildflags>` will also be used. 943 944When userspace programs are actually built 945------------------------------------------ 946 947Kbuild builds userspace programs only when told to do so. 948There are two ways to do this. 949 950(1) Add it as the prerequisite of another file 951 952 Example:: 953 954 #net/bpfilter/Makefile 955 userprogs := bpfilter_umh 956 $(obj)/bpfilter_umh_blob.o: $(obj)/bpfilter_umh 957 958 $(obj)/bpfilter_umh is built before $(obj)/bpfilter_umh_blob.o 959 960(2) Use always-y 961 962 Example:: 963 964 userprogs := binderfs_example 965 always-y := $(userprogs) 966 967 Kbuild provides the following shorthand for this:: 968 969 userprogs-always-y := binderfs_example 970 971 This will tell Kbuild to build binderfs_example when it visits this 972 Makefile. 973 974Kbuild clean infrastructure 975=========================== 976 977``make clean`` deletes most generated files in the obj tree where the kernel 978is compiled. This includes generated files such as host programs. 979Kbuild knows targets listed in $(hostprogs), $(always-y), $(always-m), 980$(always-), $(extra-y), $(extra-) and $(targets). They are all deleted 981during ``make clean``. Files matching the patterns ``*.[oas]``, ``*.ko``, plus 982some additional files generated by kbuild are deleted all over the kernel 983source tree when ``make clean`` is executed. 984 985Additional files or directories can be specified in kbuild makefiles by use of 986$(clean-files). 987 988Example:: 989 990 #lib/Makefile 991 clean-files := crc32table.h 992 993When executing ``make clean``, the file ``crc32table.h`` will be deleted. 994Kbuild will assume files to be in the same relative directory as the 995Makefile. 996 997To exclude certain files or directories from make clean, use the 998$(no-clean-files) variable. 999 1000Usually kbuild descends down in subdirectories due to ``obj-* := dir/``, 1001but in the architecture makefiles where the kbuild infrastructure 1002is not sufficient this sometimes needs to be explicit. 1003 1004Example:: 1005 1006 #arch/x86/boot/Makefile 1007 subdir- := compressed 1008 1009The above assignment instructs kbuild to descend down in the 1010directory compressed/ when ``make clean`` is executed. 1011 1012Note 1: arch/$(SRCARCH)/Makefile cannot use ``subdir-``, because that file is 1013included in the top level makefile. Instead, arch/$(SRCARCH)/Kbuild can use 1014``subdir-``. 1015 1016Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will 1017be visited during ``make clean``. 1018 1019Architecture Makefiles 1020====================== 1021 1022The top level Makefile sets up the environment and does the preparation, 1023before starting to descend down in the individual directories. 1024 1025The top level makefile contains the generic part, whereas 1026arch/$(SRCARCH)/Makefile contains what is required to set up kbuild 1027for said architecture. 1028 1029To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines 1030a few targets. 1031 1032When kbuild executes, the following steps are followed (roughly): 1033 10341) Configuration of the kernel => produce .config 1035 10362) Store kernel version in include/linux/version.h 1037 10383) Updating all other prerequisites to the target prepare: 1039 1040 - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile 1041 10424) Recursively descend down in all directories listed in 1043 init-* core* drivers-* net-* libs-* and build all targets. 1044 1045 - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile. 1046 10475) All object files are then linked and the resulting file vmlinux is 1048 located at the root of the obj tree. 1049 The very first objects linked are listed in scripts/head-object-list.txt. 1050 10516) Finally, the architecture-specific part does any required post processing 1052 and builds the final bootimage. 1053 1054 - This includes building boot records 1055 - Preparing initrd images and the like 1056 1057Set variables to tweak the build to the architecture 1058---------------------------------------------------- 1059 1060KBUILD_LDFLAGS 1061 Generic $(LD) options 1062 1063 Flags used for all invocations of the linker. 1064 Often specifying the emulation is sufficient. 1065 1066 Example:: 1067 1068 #arch/s390/Makefile 1069 KBUILD_LDFLAGS := -m elf_s390 1070 1071 Note: ldflags-y can be used to further customise 1072 the flags used. See `Non-builtin vmlinux targets - extra-y`_. 1073 1074LDFLAGS_vmlinux 1075 Options for $(LD) when linking vmlinux 1076 1077 LDFLAGS_vmlinux is used to specify additional flags to pass to 1078 the linker when linking the final vmlinux image. 1079 1080 LDFLAGS_vmlinux uses the LDFLAGS_$@ support. 1081 1082 Example:: 1083 1084 #arch/x86/Makefile 1085 LDFLAGS_vmlinux := -e stext 1086 1087OBJCOPYFLAGS 1088 objcopy flags 1089 1090 When $(call if_changed,objcopy) is used to translate a .o file, 1091 the flags specified in OBJCOPYFLAGS will be used. 1092 1093 $(call if_changed,objcopy) is often used to generate raw binaries on 1094 vmlinux. 1095 1096 Example:: 1097 1098 #arch/s390/Makefile 1099 OBJCOPYFLAGS := -O binary 1100 1101 #arch/s390/boot/Makefile 1102 $(obj)/image: vmlinux FORCE 1103 $(call if_changed,objcopy) 1104 1105 In this example, the binary $(obj)/image is a binary version of 1106 vmlinux. The usage of $(call if_changed,xxx) will be described later. 1107 1108KBUILD_AFLAGS 1109 Assembler flags 1110 1111 Default value - see top level Makefile. 1112 1113 Append or modify as required per architecture. 1114 1115 Example:: 1116 1117 #arch/sparc64/Makefile 1118 KBUILD_AFLAGS += -m64 -mcpu=ultrasparc 1119 1120KBUILD_CFLAGS 1121 $(CC) compiler flags 1122 1123 Default value - see top level Makefile. 1124 1125 Append or modify as required per architecture. 1126 1127 Often, the KBUILD_CFLAGS variable depends on the configuration. 1128 1129 Example:: 1130 1131 #arch/x86/boot/compressed/Makefile 1132 cflags-$(CONFIG_X86_32) := -march=i386 1133 cflags-$(CONFIG_X86_64) := -mcmodel=small 1134 KBUILD_CFLAGS += $(cflags-y) 1135 1136 Many arch Makefiles dynamically run the target C compiler to 1137 probe supported options:: 1138 1139 #arch/x86/Makefile 1140 1141 ... 1142 cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\ 1143 -march=pentium2,-march=i686) 1144 ... 1145 # Disable unit-at-a-time mode ... 1146 KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time) 1147 ... 1148 1149 1150 The first example utilises the trick that a config option expands 1151 to "y" when selected. 1152 1153KBUILD_RUSTFLAGS 1154 $(RUSTC) compiler flags 1155 1156 Default value - see top level Makefile. 1157 1158 Append or modify as required per architecture. 1159 1160 Often, the KBUILD_RUSTFLAGS variable depends on the configuration. 1161 1162 Note that target specification file generation (for ``--target``) 1163 is handled in ``scripts/generate_rust_target.rs``. 1164 1165KBUILD_AFLAGS_KERNEL 1166 Assembler options specific for built-in 1167 1168 $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile 1169 resident kernel code. 1170 1171KBUILD_AFLAGS_MODULE 1172 Assembler options specific for modules 1173 1174 $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that 1175 are used for assembler. 1176 1177 From commandline AFLAGS_MODULE shall be used (see kbuild.rst). 1178 1179KBUILD_CFLAGS_KERNEL 1180 $(CC) options specific for built-in 1181 1182 $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile 1183 resident kernel code. 1184 1185KBUILD_CFLAGS_MODULE 1186 Options for $(CC) when building modules 1187 1188 $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that 1189 are used for $(CC). 1190 1191 From commandline CFLAGS_MODULE shall be used (see kbuild.rst). 1192 1193KBUILD_RUSTFLAGS_KERNEL 1194 $(RUSTC) options specific for built-in 1195 1196 $(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to 1197 compile resident kernel code. 1198 1199KBUILD_RUSTFLAGS_MODULE 1200 Options for $(RUSTC) when building modules 1201 1202 $(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that 1203 are used for $(RUSTC). 1204 1205 From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst). 1206 1207KBUILD_LDFLAGS_MODULE 1208 Options for $(LD) when linking modules 1209 1210 $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options 1211 used when linking modules. This is often a linker script. 1212 1213 From commandline LDFLAGS_MODULE shall be used (see kbuild.rst). 1214 1215KBUILD_LDS 1216 The linker script with full path. Assigned by the top-level Makefile. 1217 1218KBUILD_VMLINUX_OBJS 1219 All object files for vmlinux. They are linked to vmlinux in the same 1220 order as listed in KBUILD_VMLINUX_OBJS. 1221 1222 The objects listed in scripts/head-object-list.txt are exceptions; 1223 they are placed before the other objects. 1224 1225KBUILD_VMLINUX_LIBS 1226 All .a ``lib`` files for vmlinux. KBUILD_VMLINUX_OBJS and 1227 KBUILD_VMLINUX_LIBS together specify all the object files used to 1228 link vmlinux. 1229 1230Add prerequisites to archheaders 1231-------------------------------- 1232 1233The archheaders: rule is used to generate header files that 1234may be installed into user space by ``make header_install``. 1235 1236It is run before ``make archprepare`` when run on the 1237architecture itself. 1238 1239Add prerequisites to archprepare 1240-------------------------------- 1241 1242The archprepare: rule is used to list prerequisites that need to be 1243built before starting to descend down in the subdirectories. 1244 1245This is usually used for header files containing assembler constants. 1246 1247Example:: 1248 1249 #arch/arm/Makefile 1250 archprepare: maketools 1251 1252In this example, the file target maketools will be processed 1253before descending down in the subdirectories. 1254 1255See also chapter XXX-TODO that describes how kbuild supports 1256generating offset header files. 1257 1258List directories to visit when descending 1259----------------------------------------- 1260 1261An arch Makefile cooperates with the top Makefile to define variables 1262which specify how to build the vmlinux file. Note that there is no 1263corresponding arch-specific section for modules; the module-building 1264machinery is all architecture-independent. 1265 1266core-y, libs-y, drivers-y 1267 $(libs-y) lists directories where a lib.a archive can be located. 1268 1269 The rest list directories where a built-in.a object file can be 1270 located. 1271 1272 Then the rest follows in this order: 1273 1274 $(core-y), $(libs-y), $(drivers-y) 1275 1276 The top level Makefile defines values for all generic directories, 1277 and arch/$(SRCARCH)/Makefile only adds architecture-specific 1278 directories. 1279 1280 Example:: 1281 1282 # arch/sparc/Makefile 1283 core-y += arch/sparc/ 1284 1285 libs-y += arch/sparc/prom/ 1286 libs-y += arch/sparc/lib/ 1287 1288 drivers-$(CONFIG_PM) += arch/sparc/power/ 1289 1290Architecture-specific boot images 1291--------------------------------- 1292 1293An arch Makefile specifies goals that take the vmlinux file, compress 1294it, wrap it in bootstrapping code, and copy the resulting files 1295somewhere. This includes various kinds of installation commands. 1296The actual goals are not standardized across architectures. 1297 1298It is common to locate any additional processing in a boot/ 1299directory below arch/$(SRCARCH)/. 1300 1301Kbuild does not provide any smart way to support building a 1302target specified in boot/. Therefore arch/$(SRCARCH)/Makefile shall 1303call make manually to build a target in boot/. 1304 1305The recommended approach is to include shortcuts in 1306arch/$(SRCARCH)/Makefile, and use the full path when calling down 1307into the arch/$(SRCARCH)/boot/Makefile. 1308 1309Example:: 1310 1311 #arch/x86/Makefile 1312 boot := arch/x86/boot 1313 bzImage: vmlinux 1314 $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@ 1315 1316``$(Q)$(MAKE) $(build)=<dir>`` is the recommended way to invoke 1317make in a subdirectory. 1318 1319There are no rules for naming architecture-specific targets, 1320but executing ``make help`` will list all relevant targets. 1321To support this, $(archhelp) must be defined. 1322 1323Example:: 1324 1325 #arch/x86/Makefile 1326 define archhelp 1327 echo '* bzImage - Compressed kernel image (arch/x86/boot/bzImage)' 1328 endif 1329 1330When make is executed without arguments, the first goal encountered 1331will be built. In the top level Makefile the first goal present 1332is all:. 1333 1334An architecture shall always, per default, build a bootable image. 1335In ``make help``, the default goal is highlighted with a ``*``. 1336 1337Add a new prerequisite to all: to select a default goal different 1338from vmlinux. 1339 1340Example:: 1341 1342 #arch/x86/Makefile 1343 all: bzImage 1344 1345When ``make`` is executed without arguments, bzImage will be built. 1346 1347Commands useful for building a boot image 1348----------------------------------------- 1349 1350Kbuild provides a few macros that are useful when building a 1351boot image. 1352 1353ld 1354 Link target. Often, LDFLAGS_$@ is used to set specific options to ld. 1355 1356 Example:: 1357 1358 #arch/x86/boot/Makefile 1359 LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary 1360 LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext 1361 1362 targets += setup setup.o bootsect bootsect.o 1363 $(obj)/setup $(obj)/bootsect: %: %.o FORCE 1364 $(call if_changed,ld) 1365 1366 In this example, there are two possible targets, requiring different 1367 options to the linker. The linker options are specified using the 1368 LDFLAGS_$@ syntax - one for each potential target. 1369 1370 $(targets) are assigned all potential targets, by which kbuild knows 1371 the targets and will: 1372 1373 1) check for commandline changes 1374 2) delete target during make clean 1375 1376 The ``: %: %.o`` part of the prerequisite is a shorthand that 1377 frees us from listing the setup.o and bootsect.o files. 1378 1379 Note: 1380 It is a common mistake to forget the ``targets :=`` assignment, 1381 resulting in the target file being recompiled for no 1382 obvious reason. 1383 1384objcopy 1385 Copy binary. Uses OBJCOPYFLAGS usually specified in 1386 arch/$(SRCARCH)/Makefile. 1387 1388 OBJCOPYFLAGS_$@ may be used to set additional options. 1389 1390gzip 1391 Compress target. Use maximum compression to compress target. 1392 1393 Example:: 1394 1395 #arch/x86/boot/compressed/Makefile 1396 $(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE 1397 $(call if_changed,gzip) 1398 1399dtc 1400 Create flattened device tree blob object suitable for linking 1401 into vmlinux. Device tree blobs linked into vmlinux are placed 1402 in an init section in the image. Platform code *must* copy the 1403 blob to non-init memory prior to calling unflatten_device_tree(). 1404 1405 To use this command, simply add ``*.dtb`` into obj-y or targets, or make 1406 some other target depend on ``%.dtb`` 1407 1408 A central rule exists to create ``$(obj)/%.dtb`` from ``$(src)/%.dts``; 1409 architecture Makefiles do no need to explicitly write out that rule. 1410 1411 Example:: 1412 1413 targets += $(dtb-y) 1414 DTC_FLAGS ?= -p 1024 1415 1416Preprocessing linker scripts 1417---------------------------- 1418 1419When the vmlinux image is built, the linker script 1420arch/$(SRCARCH)/kernel/vmlinux.lds is used. 1421 1422The script is a preprocessed variant of the file vmlinux.lds.S 1423located in the same directory. 1424 1425kbuild knows .lds files and includes a rule ``*lds.S`` -> ``*lds``. 1426 1427Example:: 1428 1429 #arch/x86/kernel/Makefile 1430 extra-y := vmlinux.lds 1431 1432The assignment to extra-y is used to tell kbuild to build the 1433target vmlinux.lds. 1434 1435The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the 1436specified options when building the target vmlinux.lds. 1437 1438When building the ``*.lds`` target, kbuild uses the variables:: 1439 1440 KBUILD_CPPFLAGS : Set in top-level Makefile 1441 cppflags-y : May be set in the kbuild makefile 1442 CPPFLAGS_$(@F) : Target-specific flags. 1443 Note that the full filename is used in this 1444 assignment. 1445 1446The kbuild infrastructure for ``*lds`` files is used in several 1447architecture-specific files. 1448 1449Generic header files 1450-------------------- 1451 1452The directory include/asm-generic contains the header files 1453that may be shared between individual architectures. 1454 1455The recommended approach how to use a generic header file is 1456to list the file in the Kbuild file. 1457 1458See `generic-y`_ for further info on syntax etc. 1459 1460Post-link pass 1461-------------- 1462 1463If the file arch/xxx/Makefile.postlink exists, this makefile 1464will be invoked for post-link objects (vmlinux and modules.ko) 1465for architectures to run post-link passes on. Must also handle 1466the clean target. 1467 1468This pass runs after kallsyms generation. If the architecture 1469needs to modify symbol locations, rather than manipulate the 1470kallsyms, it may be easier to add another postlink target for 1471.tmp_vmlinux? targets to be called from link-vmlinux.sh. 1472 1473For example, powerpc uses this to check relocation sanity of 1474the linked vmlinux file. 1475 1476Kbuild syntax for exported headers 1477================================== 1478 1479The kernel includes a set of headers that is exported to userspace. 1480Many headers can be exported as-is but other headers require a 1481minimal pre-processing before they are ready for user-space. 1482 1483The pre-processing does: 1484 1485- drop kernel-specific annotations 1486- drop include of compiler.h 1487- drop all sections that are kernel internal (guarded by ``ifdef __KERNEL__``) 1488 1489All headers under include/uapi/, include/generated/uapi/, 1490arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/ 1491are exported. 1492 1493A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and 1494arch/<arch>/include/asm/ to list asm files coming from asm-generic. 1495 1496See subsequent chapter for the syntax of the Kbuild file. 1497 1498no-export-headers 1499----------------- 1500 1501no-export-headers is essentially used by include/uapi/linux/Kbuild to 1502avoid exporting specific headers (e.g. kvm.h) on architectures that do 1503not support it. It should be avoided as much as possible. 1504 1505generic-y 1506--------- 1507 1508If an architecture uses a verbatim copy of a header from 1509include/asm-generic then this is listed in the file 1510arch/$(SRCARCH)/include/asm/Kbuild like this: 1511 1512Example:: 1513 1514 #arch/x86/include/asm/Kbuild 1515 generic-y += termios.h 1516 generic-y += rtc.h 1517 1518During the prepare phase of the build a wrapper include 1519file is generated in the directory:: 1520 1521 arch/$(SRCARCH)/include/generated/asm 1522 1523When a header is exported where the architecture uses 1524the generic header a similar wrapper is generated as part 1525of the set of exported headers in the directory:: 1526 1527 usr/include/asm 1528 1529The generated wrapper will in both cases look like the following: 1530 1531Example: termios.h:: 1532 1533 #include <asm-generic/termios.h> 1534 1535generated-y 1536----------- 1537 1538If an architecture generates other header files alongside generic-y 1539wrappers, generated-y specifies them. 1540 1541This prevents them being treated as stale asm-generic wrappers and 1542removed. 1543 1544Example:: 1545 1546 #arch/x86/include/asm/Kbuild 1547 generated-y += syscalls_32.h 1548 1549mandatory-y 1550----------- 1551 1552mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild 1553to define the minimum set of ASM headers that all architectures must have. 1554 1555This works like optional generic-y. If a mandatory header is missing 1556in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically 1557generate a wrapper of the asm-generic one. 1558 1559Kbuild Variables 1560================ 1561 1562The top Makefile exports the following variables: 1563 1564VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION 1565 These variables define the current kernel version. A few arch 1566 Makefiles actually use these values directly; they should use 1567 $(KERNELRELEASE) instead. 1568 1569 $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic 1570 three-part version number, such as "2", "4", and "0". These three 1571 values are always numeric. 1572 1573 $(EXTRAVERSION) defines an even tinier sublevel for pre-patches 1574 or additional patches. It is usually some non-numeric string 1575 such as "-pre4", and is often blank. 1576 1577KERNELRELEASE 1578 $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable 1579 for constructing installation directory names or showing in 1580 version strings. Some arch Makefiles use it for this purpose. 1581 1582ARCH 1583 This variable defines the target architecture, such as "i386", 1584 "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to 1585 determine which files to compile. 1586 1587 By default, the top Makefile sets $(ARCH) to be the same as the 1588 host system architecture. For a cross build, a user may 1589 override the value of $(ARCH) on the command line:: 1590 1591 make ARCH=m68k ... 1592 1593SRCARCH 1594 This variable specifies the directory in arch/ to build. 1595 1596 ARCH and SRCARCH may not necessarily match. A couple of arch 1597 directories are biarch, that is, a single ``arch/*/`` directory supports 1598 both 32-bit and 64-bit. 1599 1600 For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86. 1601 For all of them, SRCARCH=x86 because arch/x86/ supports both i386 and 1602 x86_64. 1603 1604INSTALL_PATH 1605 This variable defines a place for the arch Makefiles to install 1606 the resident kernel image and System.map file. 1607 Use this for architecture-specific install targets. 1608 1609INSTALL_MOD_PATH, MODLIB 1610 $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module 1611 installation. This variable is not defined in the Makefile but 1612 may be passed in by the user if desired. 1613 1614 $(MODLIB) specifies the directory for module installation. 1615 The top Makefile defines $(MODLIB) to 1616 $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may 1617 override this value on the command line if desired. 1618 1619INSTALL_MOD_STRIP 1620 If this variable is specified, it will cause modules to be stripped 1621 after they are installed. If INSTALL_MOD_STRIP is "1", then the 1622 default option --strip-debug will be used. Otherwise, the 1623 INSTALL_MOD_STRIP value will be used as the option(s) to the strip 1624 command. 1625 1626Makefile language 1627================= 1628 1629The kernel Makefiles are designed to be run with GNU Make. The Makefiles 1630use only the documented features of GNU Make, but they do use many 1631GNU extensions. 1632 1633GNU Make supports elementary list-processing functions. The kernel 1634Makefiles use a novel style of list building and manipulation with few 1635``if`` statements. 1636 1637GNU Make has two assignment operators, ``:=`` and ``=``. ``:=`` performs 1638immediate evaluation of the right-hand side and stores an actual string 1639into the left-hand side. ``=`` is like a formula definition; it stores the 1640right-hand side in an unevaluated form and then evaluates this form each 1641time the left-hand side is used. 1642 1643There are some cases where ``=`` is appropriate. Usually, though, ``:=`` 1644is the right choice. 1645 1646Credits 1647======= 1648 1649- Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net> 1650- Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de> 1651- Updates by Sam Ravnborg <sam@ravnborg.org> 1652- Language QA by Jan Engelhardt <jengelh@gmx.de> 1653 1654TODO 1655==== 1656 1657- Describe how kbuild supports shipped files with _shipped. 1658- Generating offset header files. 1659- Add more variables to chapters 7 or 9? 1660