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