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 assembler options. 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 388 1) All prerequisite files (both `*.c` and `*.h`) 389 2) `CONFIG_` options used in all prerequisite files 390 3) Command-line used to compile target 391 392 Thus, if you change an option to $(CC) all affected files will 393 be re-compiled. 394 3953.10 Special Rules 396------------------ 397 398 Special rules are used when the kbuild infrastructure does 399 not provide the required support. A typical example is 400 header files generated during the build process. 401 Another example are the architecture-specific Makefiles which 402 need special rules to prepare boot images etc. 403 404 Special rules are written as normal Make rules. 405 Kbuild is not executing in the directory where the Makefile is 406 located, so all special rules shall provide a relative 407 path to prerequisite files and target files. 408 409 Two variables are used when defining special rules: 410 411 $(src) 412 $(src) is a relative path which points to the directory 413 where the Makefile is located. Always use $(src) when 414 referring to files located in the src tree. 415 416 $(obj) 417 $(obj) is a relative path which points to the directory 418 where the target is saved. Always use $(obj) when 419 referring to generated files. 420 421 Example:: 422 423 #drivers/scsi/Makefile 424 $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl 425 $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl 426 427 This is a special rule, following the normal syntax 428 required by make. 429 430 The target file depends on two prerequisite files. References 431 to the target file are prefixed with $(obj), references 432 to prerequisites are referenced with $(src) (because they are not 433 generated files). 434 435 $(kecho) 436 echoing information to user in a rule is often a good practice 437 but when execution "make -s" one does not expect to see any output 438 except for warnings/errors. 439 To support this kbuild defines $(kecho) which will echo out the 440 text following $(kecho) to stdout except if "make -s" is used. 441 442 Example:: 443 444 #arch/blackfin/boot/Makefile 445 $(obj)/vmImage: $(obj)/vmlinux.gz 446 $(call if_changed,uimage) 447 @$(kecho) 'Kernel: $@ is ready' 448 449 4503.11 $(CC) support functions 451---------------------------- 452 453 The kernel may be built with several different versions of 454 $(CC), each supporting a unique set of features and options. 455 kbuild provides basic support to check for valid options for $(CC). 456 $(CC) is usually the gcc compiler, but other alternatives are 457 available. 458 459 as-option 460 as-option is used to check if $(CC) -- when used to compile 461 assembler (`*.S`) files -- supports the given option. An optional 462 second option may be specified if the first option is not supported. 463 464 Example:: 465 466 #arch/sh/Makefile 467 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),) 468 469 In the above example, cflags-y will be assigned the option 470 -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC). 471 The second argument is optional, and if supplied will be used 472 if first argument is not supported. 473 474 cc-ldoption 475 cc-ldoption is used to check if $(CC) when used to link object files 476 supports the given option. An optional second option may be 477 specified if first option are not supported. 478 479 Example:: 480 481 #arch/x86/kernel/Makefile 482 vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv) 483 484 In the above example, vsyscall-flags will be assigned the option 485 -Wl$(comma)--hash-style=sysv 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-y. 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). 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-y := 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-y := 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-y := 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-y := 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-y := 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) 727 728 When there is no suitable special rule, and the host program 729 shall be built when a makefile is entered, the $(always) 730 variable shall be used. 731 732 Example:: 733 734 #scripts/lxdialog/Makefile 735 hostprogs-y := lxdialog 736 always := $(hostprogs-y) 737 738 This will tell kbuild to build lxdialog even if not referenced in 739 any rule. 740 7414.6 Using hostprogs-$(CONFIG_FOO) 742--------------------------------- 743 744 A typical pattern in a Kbuild file looks like this: 745 746 Example:: 747 748 #scripts/Makefile 749 hostprogs-$(CONFIG_KALLSYMS) += kallsyms 750 751 Kbuild knows about both 'y' for built-in and 'm' for module. 752 So if a config symbol evaluates to 'm', kbuild will still build 753 the binary. In other words, Kbuild handles hostprogs-m exactly 754 like hostprogs-y. But only hostprogs-y is recommended to be used 755 when no CONFIG symbols are involved. 756 7575 Kbuild clean infrastructure 758============================= 759 760"make clean" deletes most generated files in the obj tree where the kernel 761is compiled. This includes generated files such as host programs. 762Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always), 763$(extra-y) and $(targets). They are all deleted during "make clean". 764Files matching the patterns "*.[oas]", "*.ko", plus some additional files 765generated by kbuild are deleted all over the kernel src tree when 766"make clean" is executed. 767 768Additional files can be specified in kbuild makefiles by use of $(clean-files). 769 770 Example:: 771 772 #lib/Makefile 773 clean-files := crc32table.h 774 775When executing "make clean", the file "crc32table.h" will be deleted. 776Kbuild will assume files to be in the same relative directory as the 777Makefile, except if prefixed with $(objtree). 778 779To delete a directory hierarchy use: 780 781 Example:: 782 783 #scripts/package/Makefile 784 clean-dirs := $(objtree)/debian/ 785 786This will delete the directory debian in the toplevel directory, including all 787subdirectories. 788 789To exclude certain files from make clean, use the $(no-clean-files) variable. 790This is only a special case used in the top level Kbuild file: 791 792 Example:: 793 794 #Kbuild 795 no-clean-files := $(bounds-file) $(offsets-file) 796 797Usually kbuild descends down in subdirectories due to "obj-* := dir/", 798but in the architecture makefiles where the kbuild infrastructure 799is not sufficient this sometimes needs to be explicit. 800 801 Example:: 802 803 #arch/x86/boot/Makefile 804 subdir- := compressed/ 805 806The above assignment instructs kbuild to descend down in the 807directory compressed/ when "make clean" is executed. 808 809To support the clean infrastructure in the Makefiles that build the 810final bootimage there is an optional target named archclean: 811 812 Example:: 813 814 #arch/x86/Makefile 815 archclean: 816 $(Q)$(MAKE) $(clean)=arch/x86/boot 817 818When "make clean" is executed, make will descend down in arch/x86/boot, 819and clean as usual. The Makefile located in arch/x86/boot/ may use 820the subdir- trick to descend further down. 821 822Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is 823included in the top level makefile, and the kbuild infrastructure 824is not operational at that point. 825 826Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will 827be visited during "make clean". 828 8296 Architecture Makefiles 830======================== 831 832The top level Makefile sets up the environment and does the preparation, 833before starting to descend down in the individual directories. 834The top level makefile contains the generic part, whereas 835arch/$(ARCH)/Makefile contains what is required to set up kbuild 836for said architecture. 837To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines 838a few targets. 839 840When kbuild executes, the following steps are followed (roughly): 841 8421) Configuration of the kernel => produce .config 8432) Store kernel version in include/linux/version.h 8443) Updating all other prerequisites to the target prepare: 845 - Additional prerequisites are specified in arch/$(ARCH)/Makefile 8464) Recursively descend down in all directories listed in 847 init-* core* drivers-* net-* libs-* and build all targets. 848 - The values of the above variables are expanded in arch/$(ARCH)/Makefile. 8495) All object files are then linked and the resulting file vmlinux is 850 located at the root of the obj tree. 851 The very first objects linked are listed in head-y, assigned by 852 arch/$(ARCH)/Makefile. 8536) Finally, the architecture-specific part does any required post processing 854 and builds the final bootimage. 855 - This includes building boot records 856 - Preparing initrd images and the like 857 858 8596.1 Set variables to tweak the build to the architecture 860-------------------------------------------------------- 861 862 LDFLAGS 863 Generic $(LD) options 864 865 Flags used for all invocations of the linker. 866 Often specifying the emulation is sufficient. 867 868 Example:: 869 870 #arch/s390/Makefile 871 LDFLAGS := -m elf_s390 872 873 Note: ldflags-y can be used to further customise 874 the flags used. See chapter 3.7. 875 876 LDFLAGS_vmlinux 877 Options for $(LD) when linking vmlinux 878 879 LDFLAGS_vmlinux is used to specify additional flags to pass to 880 the linker when linking the final vmlinux image. 881 LDFLAGS_vmlinux uses the LDFLAGS_$@ support. 882 883 Example:: 884 885 #arch/x86/Makefile 886 LDFLAGS_vmlinux := -e stext 887 888 OBJCOPYFLAGS 889 objcopy flags 890 891 When $(call if_changed,objcopy) is used to translate a .o file, 892 the flags specified in OBJCOPYFLAGS will be used. 893 $(call if_changed,objcopy) is often used to generate raw binaries on 894 vmlinux. 895 896 Example:: 897 898 #arch/s390/Makefile 899 OBJCOPYFLAGS := -O binary 900 901 #arch/s390/boot/Makefile 902 $(obj)/image: vmlinux FORCE 903 $(call if_changed,objcopy) 904 905 In this example, the binary $(obj)/image is a binary version of 906 vmlinux. The usage of $(call if_changed,xxx) will be described later. 907 908 KBUILD_AFLAGS 909 Assembler flags 910 911 Default value - see top level Makefile 912 Append or modify as required per architecture. 913 914 Example:: 915 916 #arch/sparc64/Makefile 917 KBUILD_AFLAGS += -m64 -mcpu=ultrasparc 918 919 KBUILD_CFLAGS 920 $(CC) compiler flags 921 922 Default value - see top level Makefile 923 Append or modify as required per architecture. 924 925 Often, the KBUILD_CFLAGS variable depends on the configuration. 926 927 Example:: 928 929 #arch/x86/boot/compressed/Makefile 930 cflags-$(CONFIG_X86_32) := -march=i386 931 cflags-$(CONFIG_X86_64) := -mcmodel=small 932 KBUILD_CFLAGS += $(cflags-y) 933 934 Many arch Makefiles dynamically run the target C compiler to 935 probe supported options:: 936 937 #arch/x86/Makefile 938 939 ... 940 cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\ 941 -march=pentium2,-march=i686) 942 ... 943 # Disable unit-at-a-time mode ... 944 KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time) 945 ... 946 947 948 The first example utilises the trick that a config option expands 949 to 'y' when selected. 950 951 KBUILD_AFLAGS_KERNEL 952 Assembler options specific for built-in 953 954 $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile 955 resident kernel code. 956 957 KBUILD_AFLAGS_MODULE 958 Assembler options specific for modules 959 960 $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that 961 are used for assembler. 962 963 From commandline AFLAGS_MODULE shall be used (see kbuild.txt). 964 965 KBUILD_CFLAGS_KERNEL 966 $(CC) options specific for built-in 967 968 $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile 969 resident kernel code. 970 971 KBUILD_CFLAGS_MODULE 972 Options for $(CC) when building modules 973 974 $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that 975 are used for $(CC). 976 From commandline CFLAGS_MODULE shall be used (see kbuild.txt). 977 978 KBUILD_LDFLAGS_MODULE 979 Options for $(LD) when linking modules 980 981 $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options 982 used when linking modules. This is often a linker script. 983 984 From commandline LDFLAGS_MODULE shall be used (see kbuild.txt). 985 986 KBUILD_ARFLAGS Options for $(AR) when creating archives 987 988 $(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic 989 mode) if this option is supported by $(AR). 990 991 ARCH_CPPFLAGS, ARCH_AFLAGS, ARCH_CFLAGS Overrides the kbuild defaults 992 993 These variables are appended to the KBUILD_CPPFLAGS, 994 KBUILD_AFLAGS, and KBUILD_CFLAGS, respectively, after the 995 top-level Makefile has set any other flags. This provides a 996 means for an architecture to override the defaults. 997 998 9996.2 Add prerequisites to archheaders 1000------------------------------------ 1001 1002 The archheaders: rule is used to generate header files that 1003 may be installed into user space by "make header_install". 1004 1005 It is run before "make archprepare" when run on the 1006 architecture itself. 1007 1008 10096.3 Add prerequisites to archprepare 1010------------------------------------ 1011 1012 The archprepare: rule is used to list prerequisites that need to be 1013 built before starting to descend down in the subdirectories. 1014 This is usually used for header files containing assembler constants. 1015 1016 Example:: 1017 1018 #arch/arm/Makefile 1019 archprepare: maketools 1020 1021 In this example, the file target maketools will be processed 1022 before descending down in the subdirectories. 1023 See also chapter XXX-TODO that describe how kbuild supports 1024 generating offset header files. 1025 1026 10276.4 List directories to visit when descending 1028--------------------------------------------- 1029 1030 An arch Makefile cooperates with the top Makefile to define variables 1031 which specify how to build the vmlinux file. Note that there is no 1032 corresponding arch-specific section for modules; the module-building 1033 machinery is all architecture-independent. 1034 1035 1036 head-y, init-y, core-y, libs-y, drivers-y, net-y 1037 $(head-y) lists objects to be linked first in vmlinux. 1038 1039 $(libs-y) lists directories where a lib.a archive can be located. 1040 1041 The rest list directories where a built-in.a object file can be 1042 located. 1043 1044 $(init-y) objects will be located after $(head-y). 1045 1046 Then the rest follows in this order: 1047 1048 $(core-y), $(libs-y), $(drivers-y) and $(net-y). 1049 1050 The top level Makefile defines values for all generic directories, 1051 and arch/$(ARCH)/Makefile only adds architecture-specific 1052 directories. 1053 1054 Example:: 1055 1056 #arch/sparc64/Makefile 1057 core-y += arch/sparc64/kernel/ 1058 libs-y += arch/sparc64/prom/ arch/sparc64/lib/ 1059 drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/ 1060 1061 10626.5 Architecture-specific boot images 1063------------------------------------- 1064 1065 An arch Makefile specifies goals that take the vmlinux file, compress 1066 it, wrap it in bootstrapping code, and copy the resulting files 1067 somewhere. This includes various kinds of installation commands. 1068 The actual goals are not standardized across architectures. 1069 1070 It is common to locate any additional processing in a boot/ 1071 directory below arch/$(ARCH)/. 1072 1073 Kbuild does not provide any smart way to support building a 1074 target specified in boot/. Therefore arch/$(ARCH)/Makefile shall 1075 call make manually to build a target in boot/. 1076 1077 The recommended approach is to include shortcuts in 1078 arch/$(ARCH)/Makefile, and use the full path when calling down 1079 into the arch/$(ARCH)/boot/Makefile. 1080 1081 Example:: 1082 1083 #arch/x86/Makefile 1084 boot := arch/x86/boot 1085 bzImage: vmlinux 1086 $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@ 1087 1088 "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke 1089 make in a subdirectory. 1090 1091 There are no rules for naming architecture-specific targets, 1092 but executing "make help" will list all relevant targets. 1093 To support this, $(archhelp) must be defined. 1094 1095 Example:: 1096 1097 #arch/x86/Makefile 1098 define archhelp 1099 echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)' 1100 endif 1101 1102 When make is executed without arguments, the first goal encountered 1103 will be built. In the top level Makefile the first goal present 1104 is all:. 1105 An architecture shall always, per default, build a bootable image. 1106 In "make help", the default goal is highlighted with a '*'. 1107 Add a new prerequisite to all: to select a default goal different 1108 from vmlinux. 1109 1110 Example:: 1111 1112 #arch/x86/Makefile 1113 all: bzImage 1114 1115 When "make" is executed without arguments, bzImage will be built. 1116 11176.6 Building non-kbuild targets 1118------------------------------- 1119 1120 extra-y 1121 extra-y specifies additional targets created in the current 1122 directory, in addition to any targets specified by `obj-*`. 1123 1124 Listing all targets in extra-y is required for two purposes: 1125 1126 1) Enable kbuild to check changes in command lines 1127 1128 - When $(call if_changed,xxx) is used 1129 1130 2) kbuild knows what files to delete during "make clean" 1131 1132 Example:: 1133 1134 #arch/x86/kernel/Makefile 1135 extra-y := head.o init_task.o 1136 1137 In this example, extra-y is used to list object files that 1138 shall be built, but shall not be linked as part of built-in.a. 1139 1140 header-test-y 1141 1142 header-test-y specifies headers (*.h) in the current directory that 1143 should be compile tested to ensure they are self-contained, 1144 i.e. compilable as standalone units. If CONFIG_HEADER_TEST is enabled, 1145 this builds them as part of extra-y. 1146 1147 header-test-pattern-y 1148 1149 This works as a weaker version of header-test-y, and accepts wildcard 1150 patterns. The typical usage is: 1151 1152 header-test-pattern-y += *.h 1153 1154 This specifies all the files that matches to '*.h' in the current 1155 directory, but the files in 'header-test-' are excluded. 1156 11576.7 Commands useful for building a boot image 1158--------------------------------------------- 1159 1160 Kbuild provides a few macros that are useful when building a 1161 boot image. 1162 1163 if_changed 1164 if_changed is the infrastructure used for the following commands. 1165 1166 Usage:: 1167 1168 target: source(s) FORCE 1169 $(call if_changed,ld/objcopy/gzip/...) 1170 1171 When the rule is evaluated, it is checked to see if any files 1172 need an update, or the command line has changed since the last 1173 invocation. The latter will force a rebuild if any options 1174 to the executable have changed. 1175 Any target that utilises if_changed must be listed in $(targets), 1176 otherwise the command line check will fail, and the target will 1177 always be built. 1178 Assignments to $(targets) are without $(obj)/ prefix. 1179 if_changed may be used in conjunction with custom commands as 1180 defined in 6.8 "Custom kbuild commands". 1181 1182 Note: It is a typical mistake to forget the FORCE prerequisite. 1183 Another common pitfall is that whitespace is sometimes 1184 significant; for instance, the below will fail (note the extra space 1185 after the comma):: 1186 1187 target: source(s) FORCE 1188 1189 **WRONG!** $(call if_changed, ld/objcopy/gzip/...) 1190 1191 Note: 1192 if_changed should not be used more than once per target. 1193 It stores the executed command in a corresponding .cmd 1194 1195 file and multiple calls would result in overwrites and 1196 unwanted results when the target is up to date and only the 1197 tests on changed commands trigger execution of commands. 1198 1199 ld 1200 Link target. Often, LDFLAGS_$@ is used to set specific options to ld. 1201 1202 Example:: 1203 1204 #arch/x86/boot/Makefile 1205 LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary 1206 LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext 1207 1208 targets += setup setup.o bootsect bootsect.o 1209 $(obj)/setup $(obj)/bootsect: %: %.o FORCE 1210 $(call if_changed,ld) 1211 1212 In this example, there are two possible targets, requiring different 1213 options to the linker. The linker options are specified using the 1214 LDFLAGS_$@ syntax - one for each potential target. 1215 $(targets) are assigned all potential targets, by which kbuild knows 1216 the targets and will: 1217 1218 1) check for commandline changes 1219 2) delete target during make clean 1220 1221 The ": %: %.o" part of the prerequisite is a shorthand that 1222 frees us from listing the setup.o and bootsect.o files. 1223 1224 Note: 1225 It is a common mistake to forget the "targets :=" assignment, 1226 resulting in the target file being recompiled for no 1227 obvious reason. 1228 1229 objcopy 1230 Copy binary. Uses OBJCOPYFLAGS usually specified in 1231 arch/$(ARCH)/Makefile. 1232 OBJCOPYFLAGS_$@ may be used to set additional options. 1233 1234 gzip 1235 Compress target. Use maximum compression to compress target. 1236 1237 Example:: 1238 1239 #arch/x86/boot/compressed/Makefile 1240 $(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE 1241 $(call if_changed,gzip) 1242 1243 dtc 1244 Create flattened device tree blob object suitable for linking 1245 into vmlinux. Device tree blobs linked into vmlinux are placed 1246 in an init section in the image. Platform code *must* copy the 1247 blob to non-init memory prior to calling unflatten_device_tree(). 1248 1249 To use this command, simply add `*.dtb` into obj-y or targets, or make 1250 some other target depend on `%.dtb` 1251 1252 A central rule exists to create `$(obj)/%.dtb` from `$(src)/%.dts`; 1253 architecture Makefiles do no need to explicitly write out that rule. 1254 1255 Example:: 1256 1257 targets += $(dtb-y) 1258 DTC_FLAGS ?= -p 1024 1259 12606.8 Custom kbuild commands 1261-------------------------- 1262 1263 When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand 1264 of a command is normally displayed. 1265 To enable this behaviour for custom commands kbuild requires 1266 two variables to be set:: 1267 1268 quiet_cmd_<command> - what shall be echoed 1269 cmd_<command> - the command to execute 1270 1271 Example:: 1272 1273 # 1274 quiet_cmd_image = BUILD $@ 1275 cmd_image = $(obj)/tools/build $(BUILDFLAGS) \ 1276 $(obj)/vmlinux.bin > $@ 1277 1278 targets += bzImage 1279 $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE 1280 $(call if_changed,image) 1281 @echo 'Kernel: $@ is ready' 1282 1283 When updating the $(obj)/bzImage target, the line: 1284 1285 BUILD arch/x86/boot/bzImage 1286 1287 will be displayed with "make KBUILD_VERBOSE=0". 1288 1289 1290--- 6.9 Preprocessing linker scripts 1291 1292 When the vmlinux image is built, the linker script 1293 arch/$(ARCH)/kernel/vmlinux.lds is used. 1294 The script is a preprocessed variant of the file vmlinux.lds.S 1295 located in the same directory. 1296 kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`. 1297 1298 Example:: 1299 1300 #arch/x86/kernel/Makefile 1301 always := vmlinux.lds 1302 1303 #Makefile 1304 export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH) 1305 1306 The assignment to $(always) is used to tell kbuild to build the 1307 target vmlinux.lds. 1308 The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the 1309 specified options when building the target vmlinux.lds. 1310 1311 When building the `*.lds` target, kbuild uses the variables:: 1312 1313 KBUILD_CPPFLAGS : Set in top-level Makefile 1314 cppflags-y : May be set in the kbuild makefile 1315 CPPFLAGS_$(@F) : Target-specific flags. 1316 Note that the full filename is used in this 1317 assignment. 1318 1319 The kbuild infrastructure for `*lds` files is used in several 1320 architecture-specific files. 1321 13226.10 Generic header files 1323------------------------- 1324 1325 The directory include/asm-generic contains the header files 1326 that may be shared between individual architectures. 1327 The recommended approach how to use a generic header file is 1328 to list the file in the Kbuild file. 1329 See "7.2 generic-y" for further info on syntax etc. 1330 13316.11 Post-link pass 1332------------------- 1333 1334 If the file arch/xxx/Makefile.postlink exists, this makefile 1335 will be invoked for post-link objects (vmlinux and modules.ko) 1336 for architectures to run post-link passes on. Must also handle 1337 the clean target. 1338 1339 This pass runs after kallsyms generation. If the architecture 1340 needs to modify symbol locations, rather than manipulate the 1341 kallsyms, it may be easier to add another postlink target for 1342 .tmp_vmlinux? targets to be called from link-vmlinux.sh. 1343 1344 For example, powerpc uses this to check relocation sanity of 1345 the linked vmlinux file. 1346 13477 Kbuild syntax for exported headers 1348------------------------------------ 1349 1350The kernel includes a set of headers that is exported to userspace. 1351Many headers can be exported as-is but other headers require a 1352minimal pre-processing before they are ready for user-space. 1353The pre-processing does: 1354 1355- drop kernel-specific annotations 1356- drop include of compiler.h 1357- drop all sections that are kernel internal (guarded by `ifdef __KERNEL__`) 1358 1359All headers under include/uapi/, include/generated/uapi/, 1360arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/ 1361are exported. 1362 1363A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and 1364arch/<arch>/include/asm/ to list asm files coming from asm-generic. 1365See subsequent chapter for the syntax of the Kbuild file. 1366 13677.1 no-export-headers 1368--------------------- 1369 1370 no-export-headers is essentially used by include/uapi/linux/Kbuild to 1371 avoid exporting specific headers (e.g. kvm.h) on architectures that do 1372 not support it. It should be avoided as much as possible. 1373 13747.2 generic-y 1375------------- 1376 1377 If an architecture uses a verbatim copy of a header from 1378 include/asm-generic then this is listed in the file 1379 arch/$(ARCH)/include/asm/Kbuild like this: 1380 1381 Example:: 1382 1383 #arch/x86/include/asm/Kbuild 1384 generic-y += termios.h 1385 generic-y += rtc.h 1386 1387 During the prepare phase of the build a wrapper include 1388 file is generated in the directory:: 1389 1390 arch/$(ARCH)/include/generated/asm 1391 1392 When a header is exported where the architecture uses 1393 the generic header a similar wrapper is generated as part 1394 of the set of exported headers in the directory:: 1395 1396 usr/include/asm 1397 1398 The generated wrapper will in both cases look like the following: 1399 1400 Example: termios.h:: 1401 1402 #include <asm-generic/termios.h> 1403 14047.3 generated-y 1405--------------- 1406 1407 If an architecture generates other header files alongside generic-y 1408 wrappers, generated-y specifies them. 1409 1410 This prevents them being treated as stale asm-generic wrappers and 1411 removed. 1412 1413 Example:: 1414 1415 #arch/x86/include/asm/Kbuild 1416 generated-y += syscalls_32.h 1417 14187.4 mandatory-y 1419--------------- 1420 1421 mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild 1422 to define the minimum set of ASM headers that all architectures must have. 1423 1424 This works like optional generic-y. If a mandatory header is missing 1425 in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate 1426 a wrapper of the asm-generic one. 1427 1428 The convention is to list one subdir per line and 1429 preferably in alphabetic order. 1430 14318 Kbuild Variables 1432================== 1433 1434The top Makefile exports the following variables: 1435 1436 VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION 1437 These variables define the current kernel version. A few arch 1438 Makefiles actually use these values directly; they should use 1439 $(KERNELRELEASE) instead. 1440 1441 $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic 1442 three-part version number, such as "2", "4", and "0". These three 1443 values are always numeric. 1444 1445 $(EXTRAVERSION) defines an even tinier sublevel for pre-patches 1446 or additional patches. It is usually some non-numeric string 1447 such as "-pre4", and is often blank. 1448 1449 KERNELRELEASE 1450 $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable 1451 for constructing installation directory names or showing in 1452 version strings. Some arch Makefiles use it for this purpose. 1453 1454 ARCH 1455 This variable defines the target architecture, such as "i386", 1456 "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to 1457 determine which files to compile. 1458 1459 By default, the top Makefile sets $(ARCH) to be the same as the 1460 host system architecture. For a cross build, a user may 1461 override the value of $(ARCH) on the command line:: 1462 1463 make ARCH=m68k ... 1464 1465 1466 INSTALL_PATH 1467 This variable defines a place for the arch Makefiles to install 1468 the resident kernel image and System.map file. 1469 Use this for architecture-specific install targets. 1470 1471 INSTALL_MOD_PATH, MODLIB 1472 $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module 1473 installation. This variable is not defined in the Makefile but 1474 may be passed in by the user if desired. 1475 1476 $(MODLIB) specifies the directory for module installation. 1477 The top Makefile defines $(MODLIB) to 1478 $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may 1479 override this value on the command line if desired. 1480 1481 INSTALL_MOD_STRIP 1482 If this variable is specified, it will cause modules to be stripped 1483 after they are installed. If INSTALL_MOD_STRIP is '1', then the 1484 default option --strip-debug will be used. Otherwise, the 1485 INSTALL_MOD_STRIP value will be used as the option(s) to the strip 1486 command. 1487 1488 14899 Makefile language 1490=================== 1491 1492The kernel Makefiles are designed to be run with GNU Make. The Makefiles 1493use only the documented features of GNU Make, but they do use many 1494GNU extensions. 1495 1496GNU Make supports elementary list-processing functions. The kernel 1497Makefiles use a novel style of list building and manipulation with few 1498"if" statements. 1499 1500GNU Make has two assignment operators, ":=" and "=". ":=" performs 1501immediate evaluation of the right-hand side and stores an actual string 1502into the left-hand side. "=" is like a formula definition; it stores the 1503right-hand side in an unevaluated form and then evaluates this form each 1504time the left-hand side is used. 1505 1506There are some cases where "=" is appropriate. Usually, though, ":=" 1507is the right choice. 1508 150910 Credits 1510========== 1511 1512- Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net> 1513- Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de> 1514- Updates by Sam Ravnborg <sam@ravnborg.org> 1515- Language QA by Jan Engelhardt <jengelh@gmx.de> 1516 151711 TODO 1518======= 1519 1520- Describe how kbuild supports shipped files with _shipped. 1521- Generating offset header files. 1522- Add more variables to section 7? 1523