1Linux Kernel Makefiles 22000-September-14 3Michael Elizabeth Chastain, <mec@shout.net> 4 5 6 7=== Table of Contents 8 9This document describes the Linux kernel Makefiles. 10 11 1 Overview 12 2 Who does what 13 3 Makefile language 14 4 Variables passed down from the top 15 5 The structure of an arch Makefile 16 5.1 Architecture-specific variables 17 5.2 Vmlinux build variables 18 5.3 Post-vmlinux goals 19 5.4 Mandatory arch-specific goals 20 6 The structure of a subdirectory Makefile 21 6.1 Comments 22 6.2 Goal definitions 23 6.3 Rules.make section 24 6.4 Special rules 25 7 Rules.make variables 26 7.1 Subdirectories 27 7.2 Object file goals 28 7.3 Library file goals 29 7.4 Loadable module goals 30 7.5 Multi-part modules 31 7.6 Compilation flags 32 7.7 Miscellaneous variables 33 8 New-style variables 34 8.1 New variables 35 8.2 Converting to old-style 36 9 Credits 37 38 39=== 1 Overview 40 41The Makefiles have five parts: 42 43 Makefile: the top Makefile. 44 .config: the kernel configuration file. 45 arch/*/Makefile: the arch Makefiles. 46 Subdirectory Makefiles: there are about 300 of these. 47 Rules.make: the common rules for all subdirectory Makefiles. 48 49The top Makefile reads the .config file, which comes from the 50kernel configuration process. 51 52The top Makefile is responsible for building two major products: vmlinux 53(the resident kernel image) and modules (any module files). It builds 54these goals by recursively descending into the subdirectories of the 55kernel source tree. The list of subdirectories which are visited depends 56upon the kernel configuration. 57 58The top Makefile textually includes an arch Makefile with the name 59arch/$(ARCH)/Makefile. The arch Makefile supplies architecture-specific 60information to the top Makefile. 61 62Each subdirectory has a Makefile which carries out the commands passed 63down from above. The subdirectory Makefile uses information from the 64.config file to construct various file lists, and then it textually 65includes the common rules in Rules.make. 66 67Rules.make defines rules which are common to all the subdirectory 68Makefiles. It has a public interface in the form of certain variable 69lists. It then declares rules based on those lists. 70 71 72 73=== 2 Who does what 74 75People have four different relationships with the kernel Makefiles. 76 77*Users* are people who build kernels. These people type commands such as 78"make menuconfig" or "make bzImage". They usually do not read or edit 79any kernel Makefiles (or any other source files). 80 81*Normal developers* are people who work on features such as device 82drivers, file systems, and network protocols. These people need to 83maintain the subdirectory Makefiles for the subsystem that they are 84working on. In order to do this effectively, they need some overall 85knowledge about the kernel Makefiles, plus detailed knowledge about the 86public interface for Rules.make. 87 88*Arch developers* are people who work on an entire architecture, such 89as sparc or ia64. Arch developers need to know about the arch Makefiles 90as well as subdirectory Makefiles. 91 92*Kbuild developers* are people who work on the kernel build system itself. 93These people need to know about all aspects of the kernel Makefiles. 94 95This document is aimed towards normal developers and arch developers. 96 97 98 99=== 3 Makefile language 100 101The kernel Makefiles are designed to run with GNU Make. The Makefiles 102use only the documented features of GNU Make, but they do use many 103GNU extensions. 104 105GNU Make supports elementary list-processing functions. The kernel 106Makefiles use a novel style of list building and manipulation with few 107"if" statements. 108 109GNU Make has two assignment operators, ":=" and "=". ":=" performs 110immediate evaluation of the right-hand side and stores an actual string 111into the left-hand side. "=" is like a formula definition; it stores the 112right-hand side in an unevaluated form and then evaluates this form each 113time the left-hand side is used. 114 115There are some cases where "=" is appropriate. Usually, though, ":=" 116is the right choice. 117 118All of the examples in this document were drawn from actual kernel 119sources. The examples have been reformatted (white space changed, lines 120split), but are otherwise exactly the same. 121 122 123 124=== 4 Variables passed down from the top 125 126The top Makefile exports the following variables: 127 128 VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION 129 130 These variables define the current kernel version. A few arch 131 Makefiles actually use these values directly; they should use 132 $(KERNELRELEASE) instead. 133 134 $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic 135 three-part version number, such as "2", "4", and "0". These three 136 values are always numeric. 137 138 $(EXTRAVERSION) defines an even tinier sublevel for pre-patches 139 or additional patches. It is usually some non-numeric string 140 such as "-pre4", and is often blank. 141 142 KERNELRELEASE 143 144 $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable 145 for constructing installation directory names or showing in 146 version strings. Some arch Makefiles use it for this purpose. 147 148 ARCH 149 150 This variable defines the target architecture, such as "i386", 151 "arm", or "sparc". Many subdirectory Makefiles test $(ARCH) 152 to determine which files to compile. 153 154 By default, the top Makefile sets $(ARCH) to be the same as the 155 host system system architecture. For a cross build, a user may 156 override the value of $(ARCH) on the command line: 157 158 make ARCH=m68k ... 159 160 TOPDIR, HPATH 161 162 $(TOPDIR) is the path to the top of the kernel source tree. 163 Subdirectory Makefiles need this so that they can include 164 $(TOPDIR)/Rules.make. 165 166 $(HPATH) is equal to $(TOPDIR)/include. A few arch Makefiles 167 need to use this to do special things using include files. 168 169 SUBDIRS 170 171 $(SUBDIRS) is a list of directories which the top Makefile 172 enters in order to build either vmlinux or modules. The actual 173 directories in $(SUBDIRS) depend on the kernel configuration. 174 The top Makefile defines this variable, and the arch Makefile 175 extends it. 176 177 HEAD, CORE_FILES, NETWORKS, DRIVERS, LIBS 178 LINKFLAGS 179 180 $(HEAD), $(CORE_FILES), $(NETWORKS), $(DRIVERS), and $(LIBS) 181 specify lists of object files and libraries to be linked into 182 vmlinux. 183 184 The files in $(HEAD) are linked first in vmlinux. 185 186 $(LINKFLAGS) specifies the flags to build vmlinux. 187 188 The top Makefile and the arch Makefile jointly define these 189 variables. The top Makefile defines $(CORE_FILES), $(NETWORKS), 190 $(DRIVERS), and $(LIBS). The arch Makefile defines $(HEAD) 191 and $(LINKFLAGS), and extends $(CORE_FILES) and $(LIBS). 192 193 Note: there are more variables here than necessary. $(NETWORKS), 194 $(DRIVERS), and even $(LIBS) could be subsumed into $(CORE_FILES). 195 196 CPP, CC, AS, LD, AR, NM, STRIP, OBJCOPY, OBJDUMP 197 CPPFLAGS, CFLAGS, CFLAGS_KERNEL, MODFLAGS, AFLAGS, LDFLAGS 198 PERL 199 GENKSYMS 200 201 These variables specify the commands and flags that Rules.make 202 uses to build goal files from source files. 203 204 $(CFLAGS_KERNEL) contains extra C compiler flags used to compile 205 resident kernel code. 206 207 $(MODFLAGS) contains extra C compiler flags used to compile code 208 for loadable kernel modules. In the future, this flag may be 209 renamed to the more regular name $(CFLAGS_MODULE). 210 211 $(AFLAGS) contains assembler flags. 212 213 $(GENKSYMS) contains the command used to generate kernel symbol 214 signatures when CONFIG_MODVERSIONS is enabled. The genksyms 215 command comes from the modutils package. 216 217 CROSS_COMPILE 218 219 This variable is a prefix path for other variables such as $(CC), 220 $(AS), and $(LD). The arch Makefiles sometimes use and set this 221 variable explicitly. Subdirectory Makefiles don't need to worry 222 about it. 223 224 The user may override $(CROSS_COMPILE) on the command line if 225 desired. 226 227 HOSTCC, HOSTCFLAGS 228 229 These variables define the C compiler and C compiler flags to 230 be used for compiling host side programs. These are separate 231 variables because the target architecture can be different from 232 the host architecture. 233 234 If your Makefile compiles and runs a program that is executed 235 during the course of building the kernel, then it should use 236 $(HOSTCC) and $(HOSTCFLAGS). 237 238 For example, the subdirectory drivers/pci has a helper program 239 named gen-devlist.c. This program reads a list of PCI ID's and 240 generates C code in the output files classlist.h and devlist.h. 241 242 Suppose that a user has an i386 computer and wants to build a 243 kernel for an ia64 machine. Then the user would use an ia64 244 cross-compiler for most of the compilation, but would use a 245 native i386 host compiler to compile drivers/pci/gen-devlist.c. 246 247 For another example, kbuild helper programs such as 248 scripts/mkdep.c and scripts/lxdialog/*.c are compiled with 249 $(HOSTCC) rather than $(CC). 250 251 ROOT_DEV, SVGA_MODE, RAMDISK 252 253 End users edit these variables to specify certain information 254 about the configuration of their kernel. These variables 255 are ancient! They are also specific to the i386 architecture. 256 They really should be replaced with CONFIG_* options. 257 258 MAKEBOOT 259 260 This variable is defined and used only inside the main arch 261 Makefiles. The top Makefile should not export it. 262 263 INSTALL_PATH 264 265 This variable defines a place for the arch Makefiles to install 266 the resident kernel image and System.map file. 267 268 INSTALL_MOD_PATH, MODLIB 269 270 $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module 271 installation. This variable is not defined in the Makefile but 272 may be passed in by the user if desired. 273 274 $(MODLIB) specifies the directory for module installation. 275 The top Makefile defines $(MODLIB) to 276 $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may 277 override this value on the command line if desired. 278 279 CONFIG_SHELL 280 281 This variable is private between Makefile and Rules.make. 282 Arch makefiles and subdirectory Makefiles should never use this. 283 284 MODVERFILE 285 286 An internal variable. This doesn't need to be exported, as it 287 is never used outside of the top Makefile. 288 289 MAKE, MAKEFILES 290 291 Some variables internal to GNU Make. 292 293 $(MAKEFILES) in particular is used to force the arch Makefiles 294 and subdirectory Makefiles to read $(TOPDIR)/.config without 295 including it explicitly. (This was an implementational hack 296 and could be fixed). 297 298 299 300=== 5 The structure of an arch Makefile 301 302 303 304--- 5.1 Architecture-specific variables 305 306The top Makefile includes one arch Makefile file, arch/$(ARCH)/Makefile. 307This section describes the functions of the arch Makefile. 308 309An arch Makefile extends some of the top Makefile's variables with 310architecture-specific values. 311 312 SUBDIRS 313 314 The top Makefile defines $(SUBDIRS). The arch Makefile extends 315 $(SUBDIRS) with a list of architecture-specific directories. 316 317 Example: 318 319 # arch/alpha/Makefile 320 321 SUBDIRS := $(SUBDIRS) arch/alpha/kernel arch/alpha/mm \ 322 arch/alpha/lib arch/alpha/math-emu 323 324 This list may depend on the configuration: 325 326 # arch/arm/Makefile 327 328 ifeq ($(CONFIG_ARCH_ACORN),y) 329 SUBDIRS += drivers/acorn 330 ... 331 endif 332 333 CPP, CC, AS, LD, AR, NM, STRIP, OBJCOPY, OBJDUMP 334 CPPFLAGS, CFLAGS, CFLAGS_KERNEL, MODFLAGS, AFLAGS, LDFLAGS 335 336 The top Makefile defines these variables, and the arch Makefile 337 extends them. 338 339 Many arch Makefiles dynamically run the target C compiler to 340 probe supported options: 341 342 # arch/i386/Makefile 343 344 # prevent gcc from keeping the stack 16 byte aligned 345 CFLAGS += $(shell if $(CC) -mpreferred-stack-boundary=2 \ 346 -S -o /dev/null -xc /dev/null >/dev/null 2>&1; \ 347 then echo "-mpreferred-stack-boundary=2"; fi) 348 349 And, of course, $(CFLAGS) can depend on the configuration: 350 351 # arch/i386/Makefile 352 353 ifdef CONFIG_M386 354 CFLAGS += -march=i386 355 endif 356 357 ifdef CONFIG_M486 358 CFLAGS += -march=i486 359 endif 360 361 ifdef CONFIG_M586 362 CFLAGS += -march=i586 363 endif 364 365 Some arch Makefiles redefine the compilation commands in order 366 to add architecture-specific flags: 367 368 # arch/s390/Makefile 369 370 LD=$(CROSS_COMPILE)ld -m elf_s390 371 OBJCOPY=$(CROSS_COMPILE)objcopy -O binary -R .note -R .comment -S 372 373 374 375--- 5.2 Vmlinux build variables 376 377An arch Makefile cooperates with the top Makefile to define variables 378which specify how to build the vmlinux file. Note that there is no 379corresponding arch-specific section for modules; the module-building 380machinery is all architecture-independent. 381 382 HEAD, CORE_FILES, LIBS 383 LINKFLAGS 384 385 The top Makefile defines the architecture-independent core of 386 thse variables, and the arch Makefile extends them. Note that the 387 arch Makefile defines (not just extends) $(HEAD) and $(LINKFLAGS). 388 389 Example: 390 391 # arch/m68k/Makefile 392 393 ifndef CONFIG_SUN3 394 LINKFLAGS = -T $(TOPDIR)/arch/m68k/vmlinux.lds 395 else 396 LINKFLAGS = -T $(TOPDIR)/arch/m68k/vmlinux-sun3.lds -N 397 endif 398 399 ... 400 401 ifndef CONFIG_SUN3 402 HEAD := arch/m68k/kernel/head.o 403 else 404 HEAD := arch/m68k/kernel/sun3-head.o 405 endif 406 407 SUBDIRS += arch/m68k/kernel arch/m68k/mm arch/m68k/lib 408 CORE_FILES := arch/m68k/kernel/kernel.o arch/m68k/mm/mm.o $(CORE_FILES) 409 LIBS += arch/m68k/lib/lib.a 410 411 412 413--- 5.3 Post-vmlinux goals 414 415An arch Makefile specifies goals that take the vmlinux file, compress 416it, wrap it in bootstrapping code, and copy the resulting files somewhere. 417This includes various kinds of installation commands. 418 419These post-vmlinux goals are not standardized across different 420architectures. Here is a list of these goals and the architectures 421that support each of them (as of kernel version 2.4.0-test6-pre5): 422 423 balo mips 424 bootimage alpha 425 bootpfile alpha, ia64 426 bzImage i386, m68k 427 bzdisk i386 428 bzlilo i386 429 compressed i386, m68k, mips, mips64, sh 430 dasdfmt s390 431 Image arm 432 image s390 433 install arm, i386 434 lilo m68k 435 msb alpha, ia64 436 my-special-boot alpha, ia64 437 orionboot mips 438 rawboot alpha 439 silo s390 440 srmboot alpha 441 tftpboot.img sparc, sparc64 442 vmlinux.64 mips64 443 vmlinux.aout sparc64 444 zImage arm, i386, m68k, mips, mips64, ppc, sh 445 zImage.initrd ppc 446 zdisk i386, mips, mips64, sh 447 zinstall arm 448 zlilo i386 449 znetboot.initrd ppc 450 451 452 453--- 5.4 Mandatory arch-specific goals 454 455An arch Makefile must define the following arch-specific goals. 456These goals provide arch-specific actions for the corresponding goals 457in the top Makefile: 458 459 archclean clean 460 archdep dep 461 archmrproper mrproper 462 463 464 465=== 6 The structure of a subdirectory Makefile 466 467A subdirectory Makefile has four sections. 468 469 470 471--- 6.1 Comments 472 473The first section is a comment header. Historically, many anonymous 474people have edited kernel Makefiles without leaving any change 475histories in the header; comments from them would have been valuable. 476 477 478 479--- 6.2 Goal definitions 480 481The second section is a bunch of definitions that are the heart of the 482subdirectory Makefile. These lines define the files to be built, any 483special compilation options, and any subdirectories to be recursively 484entered. The declarations in these lines depend heavily on the kernel 485configuration variables (CONFIG_* symbols). 486 487The second section looks like this: 488 489 # drivers/block/Makefile 490 obj-$(CONFIG_MAC_FLOPPY) += swim3.o 491 obj-$(CONFIG_BLK_DEV_FD) += floppy.o 492 obj-$(CONFIG_AMIGA_FLOPPY) += amiflop.o 493 obj-$(CONFIG_ATARI_FLOPPY) += ataflop.o 494 495 496--- 6.3 Rules.make section 497 498The third section is the single line: 499 500 include $(TOPDIR)/Rules.make 501 502 503 504--- 6.4 Special rules 505 506The fourth section contains any special Makefile rules needed that are 507not available through the common rules in Rules.make. 508 509 510 511=== 7 Rules.make variables 512 513The public interface of Rules.make consists of the following variables: 514 515 516 517--- 7.1 Subdirectories 518 519A Makefile is only responsible for building objects in its own 520directory. Files in subdirectories should be taken care of by 521Makefiles in the these subdirs. The build system will automatically 522invoke make recursively in subdirectories, provided you let it know of 523them. 524 525To do so, use the subdir-{y,m,n,} variables: 526 527 subdir-$(CONFIG_ISDN) += i4l 528 subdir-$(CONFIG_ISDN_CAPI) += capi 529 530When building the actual kernel, i.e. vmlinux ("make 531{vmlinux,bzImage,...}"), make will recursively descend into 532directories listed in $(subdir-y). 533 534When building modules ("make modules"), make will recursively descend 535into directories listed in $(subdir-m). 536 537When building the dependencies ("make dep") make needs to visit every 538subdir, so it'll descend into every directory listed in 539$(subdir-y), $(subdir-m), $(subdir-n), $(subdir-). 540 541You may encounter the case where a config option may be set to "y", but 542you still want to possibly build modules in that subdirectory. 543 544For example, drivers/isdn/capi/Makefile has 545 546 obj-$(CONFIG_ISDN_CAPI) += kernelcapi.o capiutil.o 547 obj-$(CONFIG_ISDN_CAPI_CAPI20) += capi.o 548 549where it's possible that CONFIG_ISDN_CAPI=y, but 550CONFIG_ISDN_CAPI_CAPI20=m. 551 552This is expressed by the following construct in the parent Makefile 553drivers/isdn/Makefile: 554 555 mod-subdirs := i4l hisax capi eicon 556 subdir-$(CONFIG_ISDN_CAPI) += capi 557 558Having a subdir ("capi") listed in the variable $(mod-subdirs) will 559make the build system enter the specified subdirectory during "make 560modules" also, even though the subdir ("capi") is listed only in 561$(subdir-y), not $(subdir-m). 562 563 564--- 7.2 Object file goals 565 566 O_TARGET, obj-y 567 568 The subdirectory Makefile specifies object files for vmlinux 569 in the lists $(obj-y). These lists depend on the kernel 570 configuration. 571 572 Rules.make compiles all the $(obj-y) files. It then calls 573 "$(LD) -r" to merge these files into one .o file with the name 574 $(O_TARGET). This $(O_TARGET) is later linked into vmlinux by 575 a parent Makefile. 576 577 The order of files in $(obj-y) is significant. Duplicates in 578 the lists are allowed: the first instance will be linked into 579 $(O_TARGET) and succeeding instances will be ignored. 580 581 Link order is significant, because certain functions 582 (module_init() / __initcall) will be called during boot in the 583 order they appear. So keep in mind that changing the link 584 order may e.g. change the order in which your SCSI 585 controllers are detected, and thus you disks are renumbered. 586 587 Example: 588 589 # Makefile for the kernel ISDN subsystem and device drivers. 590 591 # The target object and module list name. 592 593 O_TARGET := vmlinux-obj.o 594 595 # Each configuration option enables a list of files. 596 597 obj-$(CONFIG_ISDN) += isdn.o 598 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o 599 600 # The global Rules.make. 601 602 include $(TOPDIR)/Rules.make 603 604--- 7.3 Library file goals 605 606 L_TARGET 607 608 Instead of building an O_TARGET object file, you may also 609 build an archive which again contains objects listed in 610 $(obj-y). This is normally not necessary and only used in 611 the lib, arch/$(ARCH)/lib directories. 612 613 614--- 7.4 Loadable module goals 615 616 obj-m 617 618 $(obj-m) specify object files which are built as loadable 619 kernel modules. 620 621 A module may be built from one source file or several source 622 files. In the case of one source file, the subdirectory 623 Makefile simply adds the file to $(obj-m) 624 625 Example: 626 627 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o 628 629 If a kernel module is built from several source files, you specify 630 that you want to build a module in the same way as above. 631 632 However, the build system of course needs to know which the parts 633 are that you want to build your module of, so you have to tell it 634 by setting an $(<module_name>-objs) variable. 635 636 Example: 637 638 obj-$(CONFIG_ISDN) += isdn.o 639 640 isdn-objs := isdn_net.o isdn_tty.o isdn_v110.o isdn_common.o 641 642 In this example, the module name will be isdn.o. Rules.make 643 will compile the objects listed in $(isdn-objs) and then run 644 "$(LD) -r" on the list of these files to generate isdn.o 645 646 Note: Of course, when you are building objects into the kernel, 647 the syntax above will also work. So, if you have CONFIG_ISDN=y, 648 the build system will build an isdn.o for you out of the individual 649 parts and then link this into the $(O_TARGET), as you'd expect. 650 651 652--- 7.5 Objects which export symbols 653 654 export-objs 655 656 When using loadable modules, not every global symbol in the 657 kernel / other modules is automatically available, only those 658 explicitly exported are available for your module. 659 660 To make a symbol available for use in modules, to "export" it, 661 use the EXPORT_SYMBOL(<symbol>) directive in your source. In 662 addition, you need to list all object files which export symbols 663 (i.e. their source contains an EXPORT_SYMBOL() directive) in the 664 Makefile variable $(export-objs). 665 666 Example: 667 668 # Objects that export symbols. 669 670 export-objs := isdn_common.o 671 672 since isdn_common.c contains 673 674 EXPORT_SYMBOL(register_isdn); 675 676 which makes the function register_isdn available to 677 low-level ISDN drivers. 678 679 680--- 7.6 Compilation flags 681 682 EXTRA_CFLAGS, EXTRA_AFLAGS, EXTRA_LDFLAGS, EXTRA_ARFLAGS 683 684 $(EXTRA_CFLAGS) specifies options for compiling C files with 685 $(CC). The options in this variable apply to all $(CC) commands 686 for files in the current directory. 687 688 Example: 689 690 # drivers/sound/emu10k1/Makefile 691 EXTRA_CFLAGS += -I. 692 ifdef DEBUG 693 EXTRA_CFLAGS += -DEMU10K1_DEBUG 694 endif 695 696 $(EXTRA_CFLAGS) does not apply to subdirectories of the current 697 directory. Also, it does not apply to files compiled with 698 $(HOSTCC). 699 700 This variable is necessary because the top Makefile owns the 701 variable $(CFLAGS) and uses it for compilation flags for the 702 entire tree. 703 704 $(EXTRA_AFLAGS) is a similar string for per-directory options 705 when compiling assembly language source. 706 707 Example: at the time of writing, there were no examples of 708 $(EXTRA_AFLAGS) in the kernel corpus. 709 710 $(EXTRA_LDFLAGS) and $(EXTRA_ARFLAGS) are similar strings for 711 per-directory options to $(LD) and $(AR). 712 713 Example: at the time of writing, there were no examples of 714 $(EXTRA_LDFLAGS) or $(EXTRA_ARFLAGS) in the kernel corpus. 715 716 CFLAGS_$@, AFLAGS_$@ 717 718 $(CFLAGS_$@) specifies per-file options for $(CC). The $@ 719 part has a literal value which specifies the file that it's for. 720 721 Example: 722 723 # drivers/scsi/Makefile 724 CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF 725 CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \ 726 -DGDTH_STATISTICS 727 CFLAGS_seagate.o = -DARBITRATE -DPARITY -DSEAGATE_USE_ASM 728 729 These three lines specify compilation flags for aha152x.o, 730 gdth.o, and seagate.o 731 732 $(AFLAGS_$@) is a similar feature for source files in assembly 733 languages. 734 735 Example: 736 737 # arch/arm/kernel/Makefile 738 AFLAGS_head-armv.o := -DTEXTADDR=$(TEXTADDR) -traditional 739 AFLAGS_head-armo.o := -DTEXTADDR=$(TEXTADDR) -traditional 740 741 Rules.make has a feature where an object file depends on the 742 value of $(CFLAGS_$@) that was used to compile it. (It also 743 depends on the values of $(CFLAGS) and $(EXTRA_CFLAGS)). Thus, 744 if you change the value of $(CFLAGS_$@) for a file, either by 745 editing the Makefile or overriding the value some other way, 746 Rules.make will do the right thing and re-compile your source 747 file with the new options. 748 749 Note: because of a deficiency in Rules.make, assembly language 750 files do not have flag dependencies. If you edit $(AFLAGS_$@) 751 for such a file, you will have to remove the object file in order 752 to re-build from source. 753 754 LD_RFLAG 755 756 This variable is used, but never defined. It appears to be a 757 vestige of some abandoned experiment. 758 759 760 761--- 7.7 Miscellaneous variables 762 763 IGNORE_FLAGS_OBJS 764 765 $(IGNORE_FLAGS_OBJS) is a list of object files which will not have 766 their flag dependencies automatically tracked. This is a hackish 767 feature, used to kludge around a problem in the implementation 768 of flag dependencies. (The problem is that flag dependencies 769 assume that a %.o file is built from a matching %.S or %.c file. 770 This is sometimes not true). 771 772 USE_STANDARD_AS_RULE 773 774 This is a transition variable. If $(USE_STANDARD_AS_RULE) 775 is defined, then Rules.make will provide standard rules for 776 assembling %.S files into %.o files or %.s files (%.s files 777 are useful only to developers). 778 779 If $(USE_STANDARD_AS_RULE) is not defined, then Rules.make 780 will not provide these standard rules. In this case, the 781 subdirectory Makefile must provide its own private rules for 782 assembling %.S files. 783 784 In the past, all Makefiles provided private %.S rules. Newer 785 Makefiles should define USE_STANDARD_AS_RULE and use the standard 786 Rules.make rules. As soon as all the Makefiles across all 787 architectures have been converted to USE_STANDARD_AS_RULE, then 788 Rules.make can drop the conditional test on USE_STANDARD_AS_RULE. 789 After that, all the other Makefiles can drop the definition of 790 USE_STANDARD_AS_RULE. 791 792 793 794=== 8 New-style variables 795 796[ This sections dates back from a time where the way to write Makefiles 797 described above was "new-style". I'm leaving it in as it describes the 798 same thing in other words, so it may be of some use ] 799 800The "new-style variables" are simpler and more powerful than the 801"old-style variables". As a result, many subdirectory Makefiles shrank 802more than 60%. This author hopes that, in time, all arch Makefiles and 803subdirectory Makefiles will convert to the new style. 804 805Rules.make does not understand new-style variables. Thus, each new-style 806Makefile has a section of boilerplate code that converts the new-style 807variables into old-style variables. There is also some mixing, where 808people define most variables using "new style" but then fall back to 809"old style" for a few lines. 810 811--- 8.1 New variables 812 813 obj-y obj-m obj-n obj- 814 815 These variables replace $(O_OBJS), $(OX_OBJS), $(M_OBJS), 816 and $(MX_OBJS). 817 818 Example: 819 820 # drivers/block/Makefile 821 obj-$(CONFIG_MAC_FLOPPY) += swim3.o 822 obj-$(CONFIG_BLK_DEV_FD) += floppy.o 823 obj-$(CONFIG_AMIGA_FLOPPY) += amiflop.o 824 obj-$(CONFIG_ATARI_FLOPPY) += ataflop.o 825 826 Notice the use of $(CONFIG_...) substitutions on the left hand 827 side of an assignment operator. This gives GNU Make the power 828 of associative indexing! Each of these assignments replaces 829 eight lines of code in an old-style Makefile. 830 831 After executing all of the assignments, the subdirectory 832 Makefile has built up four lists: $(obj-y), $(obj-m), $(obj-n), 833 and $(obj-). 834 835 $(obj-y) is a list of files to include in vmlinux. 836 $(obj-m) is a list of files to build as single-file modules. 837 $(obj-n) and $(obj-) are ignored. 838 839 Each list may contain duplicates items; duplicates are 840 automatically removed later. Duplicates in both $(obj-y) and 841 $(obj-m) will automatically be removed from the $(obj-m) list. 842 843 Example: 844 845 # drivers/net/Makefile 846 847 ... 848 obj-$(CONFIG_OAKNET) += oaknet.o 8390.o 849 ... 850 obj-$(CONFIG_NE2K_PCI) += ne2k-pci.o 8390.o 851 ... 852 obj-$(CONFIG_STNIC) += stnic.o 8390.o 853 ... 854 obj-$(CONFIG_MAC8390) += daynaport.o 8390.o 855 ... 856 857 In this example, four different drivers require the code in 858 8390.o. If one or more of these four drivers are built into 859 vmlinux, then 8390.o will also be built into vmlinux, and will 860 *not* be built as a module -- even if another driver which needs 861 8390.o is built as a module. (The modular driver is able to 862 use services of the 8390.o code in the resident vmlinux image). 863 864 export-objs 865 866 $(export-objs) is a list of all the files in the subdirectory 867 which potentially export symbols. The canonical way to construct 868 this list is: 869 870 grep -l EXPORT_SYMBOL *.c 871 872 (but watch out for sneaky files that call EXPORT_SYMBOL from an 873 included header file!) 874 875 This is a potential list, independent of the kernel configuration. 876 All files that export symbols go into $(export-objs). The 877 boilerplate code then uses the $(export-objs) list to separate 878 the real file lists into $(*_OBJS) and $(*X_OBJS). 879 880 Experience has shown that maintaining the proper X's in an 881 old-style Makefile is difficult and error-prone. Maintaining the 882 $(export-objs) list in a new-style Makefile is simpler and easier 883 to audit. 884 885 $(foo)-objs 886 887 Some kernel modules are composed of multiple object files linked 888 together. 889 890 For each multi-part kernel modul there is a list of all the 891 object files which make up that module. For a kernel module 892 named foo.o, its object file list is foo-objs. 893 894 Example: 895 896 # drivers/scsi/Makefile 897 list-multi := scsi_mod.o sr_mod.o initio.o a100u2w.o 898 899 ... 900 901 scsi_mod-objs := hosts.o scsi.o scsi_ioctl.o constants.o \ 902 scsicam.o scsi_proc.o scsi_error.o \ 903 scsi_obsolete.o scsi_queue.o scsi_lib.o \ 904 scsi_merge.o scsi_dma.o scsi_scan.o \ 905 scsi_syms.o 906 sr_mod-objs := sr.o sr_ioctl.o sr_vendor.o 907 initio-objs := ini9100u.o i91uscsi.o 908 a100u2w-objs := inia100.o i60uscsi.o 909 910 The subdirectory Makefile puts the modules onto obj-* lists in 911 the usual configuration-dependent way: 912 913 obj-$(CONFIG_SCSI) += scsi_mod.o 914 obj-$(CONFIG_BLK_DEV_SR) += sr_mod.o 915 obj-$(CONFIG_SCSI_INITIO) += initio.o 916 obj-$(CONFIG_SCSI_INIA100) += a100u2w.o 917 918 Suppose that CONFIG_SCSI=y. Then vmlinux needs to link in all 919 14 components of scsi_mod.o. 920 921 Suppose that CONFIG_BLK_DEV_SR=m. Then the 3 components 922 of sr_mod.o will be linked together with "$(LD) -r" to make the 923 kernel module sr_mod.o. 924 925 Also suppose CONFIG_SCSI_INITIO=n. Then initio.o goes onto 926 the $(obj-n) list and that's the end of it. Its component 927 files are not compiled, and the composite file is not created. 928 929 930 subdir-y subdir-m subdir-n subdir- 931 932 These variables replace $(ALL_SUB_DIRS), $(SUB_DIRS) and 933 $(MOD_SUB_DIRS). 934 935 Example: 936 937 # drivers/Makefile 938 subdir-$(CONFIG_PCI) += pci 939 subdir-$(CONFIG_PCMCIA) += pcmcia 940 subdir-$(CONFIG_MTD) += mtd 941 subdir-$(CONFIG_SBUS) += sbus 942 943 These variables work similar to obj-*, but are used for 944 subdirectories instead of object files. 945 946 After executing all assignments, the subdirectory Makefile has 947 built up four lists: $(subdir-y), $(subdir-m), $(subdir-n), 948 and $(subdir-). 949 950 $(subdir-y) is a list of directories that should be entered 951 for making vmlinux. 952 $(subdir-m) is a list of directories that should be entered 953 for making modules. 954 $(subdir-n) and $(subdir-) are only used for collecting a list 955 of all subdirectories of this directory. 956 957 Each list besides subdir-y may contain duplicates items; duplicates 958 are automatically removed later. 959 960 mod-subdirs 961 962 $(mod-subdirs) is a list of all the subdirectories that should 963 be added to $(subdir-m), too if they appear in $(subdir-y) 964 965 Example: 966 967 # fs/Makefile 968 mod-subdirs := nls 969 970 This means nls should be added to (subdir-y) and $(subdir-m) if 971 CONFIG_NFS = y. 972 973=== 9 Credits 974 975Thanks to the members of the linux-kbuild mailing list for reviewing 976drafts of this document, with particular thanks to Peter Samuelson 977and Thomas Molina. 978