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