aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/kbuild/makefiles.txt
diff options
context:
space:
mode:
authorJan Engelhardt <jengelh@linux01.gwdg.de>2006-07-27 16:14:29 -0400
committerSam Ravnborg <sam@neptun.ravnborg.org>2006-09-25 03:00:01 -0400
commita07f6033ca135a94a69c6874d028f01338e2535c (patch)
tree3bc12ec93df18de8eb6475c5f4b27c637575c190 /Documentation/kbuild/makefiles.txt
parentd9a7ff664667e1991652db0bb0cb0abea96ec716 (diff)
kbuild: linguistic fixes for Documentation/kbuild/makefiles.txt
I have done a look-through through Documentation/kbuild/ and my corrections (proposed) are attached. Cc'ed are original author Michael (responsible for comitting changes to these files?), Sam (kbuild maintainer), Adrian (-trivial maintainer). Signed-off-by: Jan Engelhardt <jengelh@gmx.de> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Diffstat (limited to 'Documentation/kbuild/makefiles.txt')
-rw-r--r--Documentation/kbuild/makefiles.txt184
1 files changed, 94 insertions, 90 deletions
diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt
index 0706699c9da9..3d2f88ea14a5 100644
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -86,7 +86,7 @@ any kernel Makefiles (or any other source files).
86 86
87*Normal developers* are people who work on features such as device 87*Normal developers* are people who work on features such as device
88drivers, file systems, and network protocols. These people need to 88drivers, file systems, and network protocols. These people need to
89maintain the kbuild Makefiles for the subsystem that they are 89maintain the kbuild Makefiles for the subsystem they are
90working on. In order to do this effectively, they need some overall 90working on. In order to do this effectively, they need some overall
91knowledge about the kernel Makefiles, plus detailed knowledge about the 91knowledge about the kernel Makefiles, plus detailed knowledge about the
92public interface for kbuild. 92public interface for kbuild.
@@ -104,10 +104,10 @@ This document is aimed towards normal developers and arch developers.
104=== 3 The kbuild files 104=== 3 The kbuild files
105 105
106Most Makefiles within the kernel are kbuild Makefiles that use the 106Most Makefiles within the kernel are kbuild Makefiles that use the
107kbuild infrastructure. This chapter introduce the syntax used in the 107kbuild infrastructure. This chapter introduces the syntax used in the
108kbuild makefiles. 108kbuild makefiles.
109The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can 109The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
110be used and if both a 'Makefile' and a 'Kbuild' file exists then the 'Kbuild' 110be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
111file will be used. 111file will be used.
112 112
113Section 3.1 "Goal definitions" is a quick intro, further chapters provide 113Section 3.1 "Goal definitions" is a quick intro, further chapters provide
@@ -124,7 +124,7 @@ more details, with real examples.
124 Example: 124 Example:
125 obj-y += foo.o 125 obj-y += foo.o
126 126
127 This tell kbuild that there is one object in that directory named 127 This tell kbuild that there is one object in that directory, named
128 foo.o. foo.o will be built from foo.c or foo.S. 128 foo.o. foo.o will be built from foo.c or foo.S.
129 129
130 If foo.o shall be built as a module, the variable obj-m is used. 130 If foo.o shall be built as a module, the variable obj-m is used.
@@ -140,7 +140,7 @@ more details, with real examples.
140--- 3.2 Built-in object goals - obj-y 140--- 3.2 Built-in object goals - obj-y
141 141
142 The kbuild Makefile specifies object files for vmlinux 142 The kbuild Makefile specifies object files for vmlinux
143 in the lists $(obj-y). These lists depend on the kernel 143 in the $(obj-y) lists. These lists depend on the kernel
144 configuration. 144 configuration.
145 145
146 Kbuild compiles all the $(obj-y) files. It then calls 146 Kbuild compiles all the $(obj-y) files. It then calls
@@ -154,8 +154,8 @@ more details, with real examples.
154 Link order is significant, because certain functions 154 Link order is significant, because certain functions
155 (module_init() / __initcall) will be called during boot in the 155 (module_init() / __initcall) will be called during boot in the
156 order they appear. So keep in mind that changing the link 156 order they appear. So keep in mind that changing the link
157 order may e.g. change the order in which your SCSI 157 order may e.g. change the order in which your SCSI
158 controllers are detected, and thus you disks are renumbered. 158 controllers are detected, and thus your disks are renumbered.
159 159
160 Example: 160 Example:
161 #drivers/isdn/i4l/Makefile 161 #drivers/isdn/i4l/Makefile
@@ -206,8 +206,8 @@ more details, with real examples.
206 ext2-y := balloc.o bitmap.o 206 ext2-y := balloc.o bitmap.o
207 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o 207 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
208 208
209 In this example xattr.o is only part of the composite object 209 In this example, xattr.o is only part of the composite object
210 ext2.o, if $(CONFIG_EXT2_FS_XATTR) evaluates to 'y'. 210 ext2.o if $(CONFIG_EXT2_FS_XATTR) evaluates to 'y'.
211 211
212 Note: Of course, when you are building objects into the kernel, 212 Note: Of course, when you are building objects into the kernel,
213 the syntax above will also work. So, if you have CONFIG_EXT2_FS=y, 213 the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
@@ -221,16 +221,16 @@ more details, with real examples.
221 221
222--- 3.5 Library file goals - lib-y 222--- 3.5 Library file goals - lib-y
223 223
224 Objects listed with obj-* are used for modules or 224 Objects listed with obj-* are used for modules, or
225 combined in a built-in.o for that specific directory. 225 combined in a built-in.o for that specific directory.
226 There is also the possibility to list objects that will 226 There is also the possibility to list objects that will
227 be included in a library, lib.a. 227 be included in a library, lib.a.
228 All objects listed with lib-y are combined in a single 228 All objects listed with lib-y are combined in a single
229 library for that directory. 229 library for that directory.
230 Objects that are listed in obj-y and additional listed in 230 Objects that are listed in obj-y and additionaly listed in
231 lib-y will not be included in the library, since they will anyway 231 lib-y will not be included in the library, since they will anyway
232 be accessible. 232 be accessible.
233 For consistency objects listed in lib-m will be included in lib.a. 233 For consistency, objects listed in lib-m will be included in lib.a.
234 234
235 Note that the same kbuild makefile may list files to be built-in 235 Note that the same kbuild makefile may list files to be built-in
236 and to be part of a library. Therefore the same directory 236 and to be part of a library. Therefore the same directory
@@ -241,11 +241,11 @@ more details, with real examples.
241 lib-y := checksum.o delay.o 241 lib-y := checksum.o delay.o
242 242
243 This will create a library lib.a based on checksum.o and delay.o. 243 This will create a library lib.a based on checksum.o and delay.o.
244 For kbuild to actually recognize that there is a lib.a being build 244 For kbuild to actually recognize that there is a lib.a being built,
245 the directory shall be listed in libs-y. 245 the directory shall be listed in libs-y.
246 See also "6.3 List directories to visit when descending". 246 See also "6.3 List directories to visit when descending".
247 247
248 Usage of lib-y is normally restricted to lib/ and arch/*/lib. 248 Use of lib-y is normally restricted to lib/ and arch/*/lib.
249 249
250--- 3.6 Descending down in directories 250--- 3.6 Descending down in directories
251 251
@@ -255,7 +255,7 @@ more details, with real examples.
255 invoke make recursively in subdirectories, provided you let it know of 255 invoke make recursively in subdirectories, provided you let it know of
256 them. 256 them.
257 257
258 To do so obj-y and obj-m are used. 258 To do so, obj-y and obj-m are used.
259 ext2 lives in a separate directory, and the Makefile present in fs/ 259 ext2 lives in a separate directory, and the Makefile present in fs/
260 tells kbuild to descend down using the following assignment. 260 tells kbuild to descend down using the following assignment.
261 261
@@ -353,8 +353,8 @@ more details, with real examples.
353 Special rules are used when the kbuild infrastructure does 353 Special rules are used when the kbuild infrastructure does
354 not provide the required support. A typical example is 354 not provide the required support. A typical example is
355 header files generated during the build process. 355 header files generated during the build process.
356 Another example is the architecture specific Makefiles which 356 Another example are the architecture specific Makefiles which
357 needs special rules to prepare boot images etc. 357 need special rules to prepare boot images etc.
358 358
359 Special rules are written as normal Make rules. 359 Special rules are written as normal Make rules.
360 Kbuild is not executing in the directory where the Makefile is 360 Kbuild is not executing in the directory where the Makefile is
@@ -387,22 +387,22 @@ more details, with real examples.
387 387
388--- 3.11 $(CC) support functions 388--- 3.11 $(CC) support functions
389 389
390 The kernel may be build with several different versions of 390 The kernel may be built with several different versions of
391 $(CC), each supporting a unique set of features and options. 391 $(CC), each supporting a unique set of features and options.
392 kbuild provide basic support to check for valid options for $(CC). 392 kbuild provide basic support to check for valid options for $(CC).
393 $(CC) is useally the gcc compiler, but other alternatives are 393 $(CC) is useally the gcc compiler, but other alternatives are
394 available. 394 available.
395 395
396 as-option 396 as-option
397 as-option is used to check if $(CC) when used to compile 397 as-option is used to check if $(CC) -- when used to compile
398 assembler (*.S) files supports the given option. An optional 398 assembler (*.S) files -- supports the given option. An optional
399 second option may be specified if first option are not supported. 399 second option may be specified if the first option is not supported.
400 400
401 Example: 401 Example:
402 #arch/sh/Makefile 402 #arch/sh/Makefile
403 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),) 403 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
404 404
405 In the above example cflags-y will be assinged the the option 405 In the above example, cflags-y will be assigned the option
406 -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC). 406 -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
407 The second argument is optional, and if supplied will be used 407 The second argument is optional, and if supplied will be used
408 if first argument is not supported. 408 if first argument is not supported.
@@ -422,7 +422,7 @@ more details, with real examples.
422 if first argument is not supported. 422 if first argument is not supported.
423 423
424 cc-option 424 cc-option
425 cc-option is used to check if $(CC) support a given option, and not 425 cc-option is used to check if $(CC) supports a given option, and not
426 supported to use an optional second option. 426 supported to use an optional second option.
427 427
428 Example: 428 Example:
@@ -430,8 +430,8 @@ more details, with real examples.
430 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586) 430 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
431 431
432 In the above example cflags-y will be assigned the option 432 In the above example cflags-y will be assigned the option
433 -march=pentium-mmx if supported by $(CC), otherwise -march-i586. 433 -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
434 The second argument to cc-option is optional, and if omitted 434 The second argument to cc-option is optional, and if omitted,
435 cflags-y will be assigned no value if first option is not supported. 435 cflags-y will be assigned no value if first option is not supported.
436 436
437 cc-option-yn 437 cc-option-yn
@@ -444,14 +444,15 @@ more details, with real examples.
444 aflags-$(biarch) += -a32 444 aflags-$(biarch) += -a32
445 cflags-$(biarch) += -m32 445 cflags-$(biarch) += -m32
446 446
447 In the above example $(biarch) is set to y if $(CC) supports the -m32 447 In the above example, $(biarch) is set to y if $(CC) supports the -m32
448 option. When $(biarch) equals to y the expanded variables $(aflags-y) 448 option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
449 and $(cflags-y) will be assigned the values -a32 and -m32. 449 and $(cflags-y) will be assigned the values -a32 and -m32,
450 respectively.
450 451
451 cc-option-align 452 cc-option-align
452 gcc version >= 3.0 shifted type of options used to speify 453 gcc versions >= 3.0 changed the type of options used to specify
453 alignment of functions, loops etc. $(cc-option-align) whrn used 454 alignment of functions, loops etc. $(cc-option-align), when used
454 as prefix to the align options will select the right prefix: 455 as prefix to the align options, will select the right prefix:
455 gcc < 3.00 456 gcc < 3.00
456 cc-option-align = -malign 457 cc-option-align = -malign
457 gcc >= 3.00 458 gcc >= 3.00
@@ -460,15 +461,15 @@ more details, with real examples.
460 Example: 461 Example:
461 CFLAGS += $(cc-option-align)-functions=4 462 CFLAGS += $(cc-option-align)-functions=4
462 463
463 In the above example the option -falign-functions=4 is used for 464 In the above example, the option -falign-functions=4 is used for
464 gcc >= 3.00. For gcc < 3.00 -malign-functions=4 is used. 465 gcc >= 3.00. For gcc < 3.00, -malign-functions=4 is used.
465 466
466 cc-version 467 cc-version
467 cc-version return a numerical version of the $(CC) compiler version. 468 cc-version returns a numerical version of the $(CC) compiler version.
468 The format is <major><minor> where both are two digits. So for example 469 The format is <major><minor> where both are two digits. So for example
469 gcc 3.41 would return 0341. 470 gcc 3.41 would return 0341.
470 cc-version is useful when a specific $(CC) version is faulty in one 471 cc-version is useful when a specific $(CC) version is faulty in one
471 area, for example the -mregparm=3 were broken in some gcc version 472 area, for example -mregparm=3 was broken in some gcc versions
472 even though the option was accepted by gcc. 473 even though the option was accepted by gcc.
473 474
474 Example: 475 Example:
@@ -477,18 +478,18 @@ more details, with real examples.
477 if [ $(call cc-version) -ge 0300 ] ; then \ 478 if [ $(call cc-version) -ge 0300 ] ; then \
478 echo "-mregparm=3"; fi ;) 479 echo "-mregparm=3"; fi ;)
479 480
480 In the above example -mregparm=3 is only used for gcc version greater 481 In the above example, -mregparm=3 is only used for gcc version greater
481 than or equal to gcc 3.0. 482 than or equal to gcc 3.0.
482 483
483 cc-ifversion 484 cc-ifversion
484 cc-ifversion test the version of $(CC) and equals last argument if 485 cc-ifversion tests the version of $(CC) and equals last argument if
485 version expression is true. 486 version expression is true.
486 487
487 Example: 488 Example:
488 #fs/reiserfs/Makefile 489 #fs/reiserfs/Makefile
489 EXTRA_CFLAGS := $(call cc-ifversion, -lt, 0402, -O1) 490 EXTRA_CFLAGS := $(call cc-ifversion, -lt, 0402, -O1)
490 491
491 In this example EXTRA_CFLAGS will be assigned the value -O1 if the 492 In this example, EXTRA_CFLAGS will be assigned the value -O1 if the
492 $(CC) version is less than 4.2. 493 $(CC) version is less than 4.2.
493 cc-ifversion takes all the shell operators: 494 cc-ifversion takes all the shell operators:
494 -eq, -ne, -lt, -le, -gt, and -ge 495 -eq, -ne, -lt, -le, -gt, and -ge
@@ -529,7 +530,7 @@ Both possibilities are described in the following.
529 Host programs can be made up based on composite objects. 530 Host programs can be made up based on composite objects.
530 The syntax used to define composite objects for host programs is 531 The syntax used to define composite objects for host programs is
531 similar to the syntax used for kernel objects. 532 similar to the syntax used for kernel objects.
532 $(<executeable>-objs) list all objects used to link the final 533 $(<executeable>-objs) lists all objects used to link the final
533 executable. 534 executable.
534 535
535 Example: 536 Example:
@@ -538,9 +539,9 @@ Both possibilities are described in the following.
538 lxdialog-objs := checklist.o lxdialog.o 539 lxdialog-objs := checklist.o lxdialog.o
539 540
540 Objects with extension .o are compiled from the corresponding .c 541 Objects with extension .o are compiled from the corresponding .c
541 files. In the above example checklist.c is compiled to checklist.o 542 files. In the above example, checklist.c is compiled to checklist.o
542 and lxdialog.c is compiled to lxdialog.o. 543 and lxdialog.c is compiled to lxdialog.o.
543 Finally the two .o files are linked to the executable, lxdialog. 544 Finally, the two .o files are linked to the executable, lxdialog.
544 Note: The syntax <executable>-y is not permitted for host-programs. 545 Note: The syntax <executable>-y is not permitted for host-programs.
545 546
546--- 4.3 Defining shared libraries 547--- 4.3 Defining shared libraries
@@ -594,7 +595,7 @@ Both possibilities are described in the following.
594 The programs will always be compiled utilising $(HOSTCC) passed 595 The programs will always be compiled utilising $(HOSTCC) passed
595 the options specified in $(HOSTCFLAGS). 596 the options specified in $(HOSTCFLAGS).
596 To set flags that will take effect for all host programs created 597 To set flags that will take effect for all host programs created
597 in that Makefile use the variable HOST_EXTRACFLAGS. 598 in that Makefile, use the variable HOST_EXTRACFLAGS.
598 599
599 Example: 600 Example:
600 #scripts/lxdialog/Makefile 601 #scripts/lxdialog/Makefile
@@ -613,7 +614,8 @@ Both possibilities are described in the following.
613 #scripts/kconfig/Makefile 614 #scripts/kconfig/Makefile
614 HOSTLOADLIBES_qconf := -L$(QTDIR)/lib 615 HOSTLOADLIBES_qconf := -L$(QTDIR)/lib
615 616
616 When linking qconf it will be passed the extra option "-L$(QTDIR)/lib". 617 When linking qconf, it will be passed the extra option
618 "-L$(QTDIR)/lib".
617 619
618--- 4.6 When host programs are actually built 620--- 4.6 When host programs are actually built
619 621
@@ -648,7 +650,7 @@ Both possibilities are described in the following.
648 650
649--- 4.7 Using hostprogs-$(CONFIG_FOO) 651--- 4.7 Using hostprogs-$(CONFIG_FOO)
650 652
651 A typcal pattern in a Kbuild file lok like this: 653 A typcal pattern in a Kbuild file looks like this:
652 654
653 Example: 655 Example:
654 #scripts/Makefile 656 #scripts/Makefile
@@ -656,13 +658,13 @@ Both possibilities are described in the following.
656 658
657 Kbuild knows about both 'y' for built-in and 'm' for module. 659 Kbuild knows about both 'y' for built-in and 'm' for module.
658 So if a config symbol evaluate to 'm', kbuild will still build 660 So if a config symbol evaluate to 'm', kbuild will still build
659 the binary. In other words Kbuild handle hostprogs-m exactly 661 the binary. In other words, Kbuild handles hostprogs-m exactly
660 like hostprogs-y. But only hostprogs-y is recommend used 662 like hostprogs-y. But only hostprogs-y is recommended to be used
661 when no CONFIG symbol are involved. 663 when no CONFIG symbols are involved.
662 664
663=== 5 Kbuild clean infrastructure 665=== 5 Kbuild clean infrastructure
664 666
665"make clean" deletes most generated files in the src tree where the kernel 667"make clean" deletes most generated files in the obj tree where the kernel
666is compiled. This includes generated files such as host programs. 668is compiled. This includes generated files such as host programs.
667Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always), 669Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
668$(extra-y) and $(targets). They are all deleted during "make clean". 670$(extra-y) and $(targets). They are all deleted during "make clean".
@@ -723,29 +725,29 @@ be visited during "make clean".
723 725
724The top level Makefile sets up the environment and does the preparation, 726The top level Makefile sets up the environment and does the preparation,
725before starting to descend down in the individual directories. 727before starting to descend down in the individual directories.
726The top level makefile contains the generic part, whereas the 728The top level makefile contains the generic part, whereas
727arch/$(ARCH)/Makefile contains what is required to set-up kbuild 729arch/$(ARCH)/Makefile contains what is required to set up kbuild
728to the said architecture. 730for said architecture.
729To do so arch/$(ARCH)/Makefile sets a number of variables, and defines 731To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
730a few targets. 732a few targets.
731 733
732When kbuild executes the following steps are followed (roughly): 734When kbuild executes, the following steps are followed (roughly):
7331) Configuration of the kernel => produced .config 7351) Configuration of the kernel => produce .config
7342) Store kernel version in include/linux/version.h 7362) Store kernel version in include/linux/version.h
7353) Symlink include/asm to include/asm-$(ARCH) 7373) Symlink include/asm to include/asm-$(ARCH)
7364) Updating all other prerequisites to the target prepare: 7384) Updating all other prerequisites to the target prepare:
737 - Additional prerequisites are specified in arch/$(ARCH)/Makefile 739 - Additional prerequisites are specified in arch/$(ARCH)/Makefile
7385) Recursively descend down in all directories listed in 7405) Recursively descend down in all directories listed in
739 init-* core* drivers-* net-* libs-* and build all targets. 741 init-* core* drivers-* net-* libs-* and build all targets.
740 - The value of the above variables are extended in arch/$(ARCH)/Makefile. 742 - The values of the above variables are expanded in arch/$(ARCH)/Makefile.
7416) All object files are then linked and the resulting file vmlinux is 7436) All object files are then linked and the resulting file vmlinux is
742 located at the root of the src tree. 744 located at the root of the obj tree.
743 The very first objects linked are listed in head-y, assigned by 745 The very first objects linked are listed in head-y, assigned by
744 arch/$(ARCH)/Makefile. 746 arch/$(ARCH)/Makefile.
7457) Finally the architecture specific part does any required post processing 7477) Finally, the architecture specific part does any required post processing
746 and builds the final bootimage. 748 and builds the final bootimage.
747 - This includes building boot records 749 - This includes building boot records
748 - Preparing initrd images and the like 750 - Preparing initrd images and thelike
749 751
750 752
751--- 6.1 Set variables to tweak the build to the architecture 753--- 6.1 Set variables to tweak the build to the architecture
@@ -770,7 +772,7 @@ When kbuild executes the following steps are followed (roughly):
770 LDFLAGS_vmlinux Options for $(LD) when linking vmlinux 772 LDFLAGS_vmlinux Options for $(LD) when linking vmlinux
771 773
772 LDFLAGS_vmlinux is used to specify additional flags to pass to 774 LDFLAGS_vmlinux is used to specify additional flags to pass to
773 the linker when linking the final vmlinux. 775 the linker when linking the final vmlinux image.
774 LDFLAGS_vmlinux uses the LDFLAGS_$@ support. 776 LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
775 777
776 Example: 778 Example:
@@ -780,7 +782,7 @@ When kbuild executes the following steps are followed (roughly):
780 OBJCOPYFLAGS objcopy flags 782 OBJCOPYFLAGS objcopy flags
781 783
782 When $(call if_changed,objcopy) is used to translate a .o file, 784 When $(call if_changed,objcopy) is used to translate a .o file,
783 then the flags specified in OBJCOPYFLAGS will be used. 785 the flags specified in OBJCOPYFLAGS will be used.
784 $(call if_changed,objcopy) is often used to generate raw binaries on 786 $(call if_changed,objcopy) is often used to generate raw binaries on
785 vmlinux. 787 vmlinux.
786 788
@@ -792,7 +794,7 @@ When kbuild executes the following steps are followed (roughly):
792 $(obj)/image: vmlinux FORCE 794 $(obj)/image: vmlinux FORCE
793 $(call if_changed,objcopy) 795 $(call if_changed,objcopy)
794 796
795 In this example the binary $(obj)/image is a binary version of 797 In this example, the binary $(obj)/image is a binary version of
796 vmlinux. The usage of $(call if_changed,xxx) will be described later. 798 vmlinux. The usage of $(call if_changed,xxx) will be described later.
797 799
798 AFLAGS $(AS) assembler flags 800 AFLAGS $(AS) assembler flags
@@ -809,7 +811,7 @@ When kbuild executes the following steps are followed (roughly):
809 Default value - see top level Makefile 811 Default value - see top level Makefile
810 Append or modify as required per architecture. 812 Append or modify as required per architecture.
811 813
812 Often the CFLAGS variable depends on the configuration. 814 Often, the CFLAGS variable depends on the configuration.
813 815
814 Example: 816 Example:
815 #arch/i386/Makefile 817 #arch/i386/Makefile
@@ -830,7 +832,7 @@ When kbuild executes the following steps are followed (roughly):
830 ... 832 ...
831 833
832 834
833 The first examples utilises the trick that a config option expands 835 The first example utilises the trick that a config option expands
834 to 'y' when selected. 836 to 'y' when selected.
835 837
836 CFLAGS_KERNEL $(CC) options specific for built-in 838 CFLAGS_KERNEL $(CC) options specific for built-in
@@ -846,15 +848,15 @@ When kbuild executes the following steps are followed (roughly):
846 848
847--- 6.2 Add prerequisites to archprepare: 849--- 6.2 Add prerequisites to archprepare:
848 850
849 The archprepare: rule is used to list prerequisites that needs to be 851 The archprepare: rule is used to list prerequisites that need to be
850 built before starting to descend down in the subdirectories. 852 built before starting to descend down in the subdirectories.
851 This is usual header files containing assembler constants. 853 This is usually used for header files containing assembler constants.
852 854
853 Example: 855 Example:
854 #arch/arm/Makefile 856 #arch/arm/Makefile
855 archprepare: maketools 857 archprepare: maketools
856 858
857 In this example the file target maketools will be processed 859 In this example, the file target maketools will be processed
858 before descending down in the subdirectories. 860 before descending down in the subdirectories.
859 See also chapter XXX-TODO that describe how kbuild supports 861 See also chapter XXX-TODO that describe how kbuild supports
860 generating offset header files. 862 generating offset header files.
@@ -870,15 +872,16 @@ When kbuild executes the following steps are followed (roughly):
870 872
871 head-y, init-y, core-y, libs-y, drivers-y, net-y 873 head-y, init-y, core-y, libs-y, drivers-y, net-y
872 874
873 $(head-y) list objects to be linked first in vmlinux. 875 $(head-y) lists objects to be linked first in vmlinux.
874 $(libs-y) list directories where a lib.a archive can be located. 876 $(libs-y) lists directories where a lib.a archive can be located.
875 The rest list directories where a built-in.o object file can be located. 877 The rest lists directories where a built-in.o object file can be
878 located.
876 879
877 $(init-y) objects will be located after $(head-y). 880 $(init-y) objects will be located after $(head-y).
878 Then the rest follows in this order: 881 Then the rest follows in this order:
879 $(core-y), $(libs-y), $(drivers-y) and $(net-y). 882 $(core-y), $(libs-y), $(drivers-y) and $(net-y).
880 883
881 The top level Makefile define values for all generic directories, 884 The top level Makefile defines values for all generic directories,
882 and arch/$(ARCH)/Makefile only adds architecture specific directories. 885 and arch/$(ARCH)/Makefile only adds architecture specific directories.
883 886
884 Example: 887 Example:
@@ -915,9 +918,9 @@ When kbuild executes the following steps are followed (roughly):
915 "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke 918 "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
916 make in a subdirectory. 919 make in a subdirectory.
917 920
918 There are no rules for naming of the architecture specific targets, 921 There are no rules for naming architecture specific targets,
919 but executing "make help" will list all relevant targets. 922 but executing "make help" will list all relevant targets.
920 To support this $(archhelp) must be defined. 923 To support this, $(archhelp) must be defined.
921 924
922 Example: 925 Example:
923 #arch/i386/Makefile 926 #arch/i386/Makefile
@@ -928,8 +931,8 @@ When kbuild executes the following steps are followed (roughly):
928 When make is executed without arguments, the first goal encountered 931 When make is executed without arguments, the first goal encountered
929 will be built. In the top level Makefile the first goal present 932 will be built. In the top level Makefile the first goal present
930 is all:. 933 is all:.
931 An architecture shall always per default build a bootable image. 934 An architecture shall always, per default, build a bootable image.
932 In "make help" the default goal is highlighted with a '*'. 935 In "make help", the default goal is highlighted with a '*'.
933 Add a new prerequisite to all: to select a default goal different 936 Add a new prerequisite to all: to select a default goal different
934 from vmlinux. 937 from vmlinux.
935 938
@@ -955,7 +958,7 @@ When kbuild executes the following steps are followed (roughly):
955 #arch/i386/kernel/Makefile 958 #arch/i386/kernel/Makefile
956 extra-y := head.o init_task.o 959 extra-y := head.o init_task.o
957 960
958 In this example extra-y is used to list object files that 961 In this example, extra-y is used to list object files that
959 shall be built, but shall not be linked as part of built-in.o. 962 shall be built, but shall not be linked as part of built-in.o.
960 963
961 964
@@ -972,8 +975,8 @@ When kbuild executes the following steps are followed (roughly):
972 target: source(s) FORCE 975 target: source(s) FORCE
973 $(call if_changed,ld/objcopy/gzip) 976 $(call if_changed,ld/objcopy/gzip)
974 977
975 When the rule is evaluated it is checked to see if any files 978 When the rule is evaluated, it is checked to see if any files
976 needs an update, or the commandline has changed since last 979 needs an update, or the command line has changed since the last
977 invocation. The latter will force a rebuild if any options 980 invocation. The latter will force a rebuild if any options
978 to the executable have changed. 981 to the executable have changed.
979 Any target that utilises if_changed must be listed in $(targets), 982 Any target that utilises if_changed must be listed in $(targets),
@@ -991,7 +994,7 @@ When kbuild executes the following steps are followed (roughly):
991 #WRONG!# $(call if_changed, ld/objcopy/gzip) 994 #WRONG!# $(call if_changed, ld/objcopy/gzip)
992 995
993 ld 996 ld
994 Link target. Often LDFLAGS_$@ is used to set specific options to ld. 997 Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
995 998
996 objcopy 999 objcopy
997 Copy binary. Uses OBJCOPYFLAGS usually specified in 1000 Copy binary. Uses OBJCOPYFLAGS usually specified in
@@ -1010,10 +1013,10 @@ When kbuild executes the following steps are followed (roughly):
1010 $(obj)/setup $(obj)/bootsect: %: %.o FORCE 1013 $(obj)/setup $(obj)/bootsect: %: %.o FORCE
1011 $(call if_changed,ld) 1014 $(call if_changed,ld)
1012 1015
1013 In this example there are two possible targets, requiring different 1016 In this example, there are two possible targets, requiring different
1014 options to the linker. the linker options are specified using the 1017 options to the linker. The linker options are specified using the
1015 LDFLAGS_$@ syntax - one for each potential target. 1018 LDFLAGS_$@ syntax - one for each potential target.
1016 $(targets) are assinged all potential targets, herby kbuild knows 1019 $(targets) are assinged all potential targets, by which kbuild knows
1017 the targets and will: 1020 the targets and will:
1018 1) check for commandline changes 1021 1) check for commandline changes
1019 2) delete target during make clean 1022 2) delete target during make clean
@@ -1027,7 +1030,7 @@ When kbuild executes the following steps are followed (roughly):
1027 1030
1028--- 6.7 Custom kbuild commands 1031--- 6.7 Custom kbuild commands
1029 1032
1030 When kbuild is executing with KBUILD_VERBOSE=0 then only a shorthand 1033 When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
1031 of a command is normally displayed. 1034 of a command is normally displayed.
1032 To enable this behaviour for custom commands kbuild requires 1035 To enable this behaviour for custom commands kbuild requires
1033 two variables to be set: 1036 two variables to be set:
@@ -1045,7 +1048,7 @@ When kbuild executes the following steps are followed (roughly):
1045 $(call if_changed,image) 1048 $(call if_changed,image)
1046 @echo 'Kernel: $@ is ready' 1049 @echo 'Kernel: $@ is ready'
1047 1050
1048 When updating the $(obj)/bzImage target the line: 1051 When updating the $(obj)/bzImage target, the line
1049 1052
1050 BUILD arch/i386/boot/bzImage 1053 BUILD arch/i386/boot/bzImage
1051 1054
@@ -1054,11 +1057,11 @@ When kbuild executes the following steps are followed (roughly):
1054 1057
1055--- 6.8 Preprocessing linker scripts 1058--- 6.8 Preprocessing linker scripts
1056 1059
1057 When the vmlinux image is build the linker script: 1060 When the vmlinux image is built, the linker script
1058 arch/$(ARCH)/kernel/vmlinux.lds is used. 1061 arch/$(ARCH)/kernel/vmlinux.lds is used.
1059 The script is a preprocessed variant of the file vmlinux.lds.S 1062 The script is a preprocessed variant of the file vmlinux.lds.S
1060 located in the same directory. 1063 located in the same directory.
1061 kbuild knows .lds file and includes a rule *lds.S -> *lds. 1064 kbuild knows .lds files and includes a rule *lds.S -> *lds.
1062 1065
1063 Example: 1066 Example:
1064 #arch/i386/kernel/Makefile 1067 #arch/i386/kernel/Makefile
@@ -1068,11 +1071,11 @@ When kbuild executes the following steps are followed (roughly):
1068 export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH) 1071 export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
1069 1072
1070 The assigment to $(always) is used to tell kbuild to build the 1073 The assigment to $(always) is used to tell kbuild to build the
1071 target: vmlinux.lds. 1074 target vmlinux.lds.
1072 The assignment to $(CPPFLAGS_vmlinux.lds) tell kbuild to use the 1075 The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
1073 specified options when building the target vmlinux.lds. 1076 specified options when building the target vmlinux.lds.
1074 1077
1075 When building the *.lds target kbuild used the variakles: 1078 When building the *.lds target, kbuild uses the variables:
1076 CPPFLAGS : Set in top-level Makefile 1079 CPPFLAGS : Set in top-level Makefile
1077 EXTRA_CPPFLAGS : May be set in the kbuild makefile 1080 EXTRA_CPPFLAGS : May be set in the kbuild makefile
1078 CPPFLAGS_$(@F) : Target specific flags. 1081 CPPFLAGS_$(@F) : Target specific flags.
@@ -1147,7 +1150,7 @@ The top Makefile exports the following variables:
1147 1150
1148=== 8 Makefile language 1151=== 8 Makefile language
1149 1152
1150The kernel Makefiles are designed to run with GNU Make. The Makefiles 1153The kernel Makefiles are designed to be run with GNU Make. The Makefiles
1151use only the documented features of GNU Make, but they do use many 1154use only the documented features of GNU Make, but they do use many
1152GNU extensions. 1155GNU extensions.
1153 1156
@@ -1169,10 +1172,11 @@ is the right choice.
1169Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net> 1172Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1170Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de> 1173Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1171Updates by Sam Ravnborg <sam@ravnborg.org> 1174Updates by Sam Ravnborg <sam@ravnborg.org>
1175Language QA by Jan Engelhardt <jengelh@gmx.de>
1172 1176
1173=== 10 TODO 1177=== 10 TODO
1174 1178
1175- Describe how kbuild support shipped files with _shipped. 1179- Describe how kbuild supports shipped files with _shipped.
1176- Generating offset header files. 1180- Generating offset header files.
1177- Add more variables to section 7? 1181- Add more variables to section 7?
1178 1182