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