Back to home page

LXR

 
 

    


0001 Linux Kernel Makefiles
0002 
0003 This document describes the Linux kernel Makefiles.
0004 
0005 === Table of Contents
0006 
0007         === 1 Overview
0008         === 2 Who does what
0009         === 3 The kbuild files
0010            --- 3.1 Goal definitions
0011            --- 3.2 Built-in object goals - obj-y
0012            --- 3.3 Loadable module goals - obj-m
0013            --- 3.4 Objects which export symbols
0014            --- 3.5 Library file goals - lib-y
0015            --- 3.6 Descending down in directories
0016            --- 3.7 Compilation flags
0017            --- 3.8 Command line dependency
0018            --- 3.9 Dependency tracking
0019            --- 3.10 Special Rules
0020            --- 3.11 $(CC) support functions
0021            --- 3.12 $(LD) support functions
0022 
0023         === 4 Host Program support
0024            --- 4.1 Simple Host Program
0025            --- 4.2 Composite Host Programs
0026            --- 4.3 Using C++ for host programs
0027            --- 4.4 Controlling compiler options for host programs
0028            --- 4.5 When host programs are actually built
0029            --- 4.6 Using hostprogs-$(CONFIG_FOO)
0030 
0031         === 5 Kbuild clean infrastructure
0032 
0033         === 6 Architecture Makefiles
0034            --- 6.1 Set variables to tweak the build to the architecture
0035            --- 6.2 Add prerequisites to archheaders:
0036            --- 6.3 Add prerequisites to archprepare:
0037            --- 6.4 List directories to visit when descending
0038            --- 6.5 Architecture-specific boot images
0039            --- 6.6 Building non-kbuild targets
0040            --- 6.7 Commands useful for building a boot image
0041            --- 6.8 Custom kbuild commands
0042            --- 6.9 Preprocessing linker scripts
0043            --- 6.10 Generic header files
0044            --- 6.11 Post-link pass
0045 
0046         === 7 Kbuild syntax for exported headers
0047                 --- 7.1 header-y
0048                 --- 7.2 genhdr-y
0049                 --- 7.3 destination-y
0050                 --- 7.4 generic-y
0051                 --- 7.5 generated-y
0052 
0053         === 8 Kbuild Variables
0054         === 9 Makefile language
0055         === 10 Credits
0056         === 11 TODO
0057 
0058 === 1 Overview
0059 
0060 The Makefiles have five parts:
0061 
0062         Makefile                the top Makefile.
0063         .config                 the kernel configuration file.
0064         arch/$(ARCH)/Makefile   the arch Makefile.
0065         scripts/Makefile.*      common rules etc. for all kbuild Makefiles.
0066         kbuild Makefiles        there are about 500 of these.
0067 
0068 The top Makefile reads the .config file, which comes from the kernel
0069 configuration process.
0070 
0071 The top Makefile is responsible for building two major products: vmlinux
0072 (the resident kernel image) and modules (any module files).
0073 It builds these goals by recursively descending into the subdirectories of
0074 the kernel source tree.
0075 The list of subdirectories which are visited depends upon the kernel
0076 configuration. The top Makefile textually includes an arch Makefile
0077 with the name arch/$(ARCH)/Makefile. The arch Makefile supplies
0078 architecture-specific information to the top Makefile.
0079 
0080 Each subdirectory has a kbuild Makefile which carries out the commands
0081 passed down from above. The kbuild Makefile uses information from the
0082 .config file to construct various file lists used by kbuild to build
0083 any built-in or modular targets.
0084 
0085 scripts/Makefile.* contains all the definitions/rules etc. that
0086 are used to build the kernel based on the kbuild makefiles.
0087 
0088 
0089 === 2 Who does what
0090 
0091 People have four different relationships with the kernel Makefiles.
0092 
0093 *Users* are people who build kernels.  These people type commands such as
0094 "make menuconfig" or "make".  They usually do not read or edit
0095 any kernel Makefiles (or any other source files).
0096 
0097 *Normal developers* are people who work on features such as device
0098 drivers, file systems, and network protocols.  These people need to
0099 maintain the kbuild Makefiles for the subsystem they are
0100 working on.  In order to do this effectively, they need some overall
0101 knowledge about the kernel Makefiles, plus detailed knowledge about the
0102 public interface for kbuild.
0103 
0104 *Arch developers* are people who work on an entire architecture, such
0105 as sparc or ia64.  Arch developers need to know about the arch Makefile
0106 as well as kbuild Makefiles.
0107 
0108 *Kbuild developers* are people who work on the kernel build system itself.
0109 These people need to know about all aspects of the kernel Makefiles.
0110 
0111 This document is aimed towards normal developers and arch developers.
0112 
0113 
0114 === 3 The kbuild files
0115 
0116 Most Makefiles within the kernel are kbuild Makefiles that use the
0117 kbuild infrastructure. This chapter introduces the syntax used in the
0118 kbuild makefiles.
0119 The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
0120 be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
0121 file will be used.
0122 
0123 Section 3.1 "Goal definitions" is a quick intro, further chapters provide
0124 more details, with real examples.
0125 
0126 --- 3.1 Goal definitions
0127 
0128         Goal definitions are the main part (heart) of the kbuild Makefile.
0129         These lines define the files to be built, any special compilation
0130         options, and any subdirectories to be entered recursively.
0131 
0132         The most simple kbuild makefile contains one line:
0133 
0134         Example:
0135                 obj-y += foo.o
0136 
0137         This tells kbuild that there is one object in that directory, named
0138         foo.o. foo.o will be built from foo.c or foo.S.
0139 
0140         If foo.o shall be built as a module, the variable obj-m is used.
0141         Therefore the following pattern is often used:
0142 
0143         Example:
0144                 obj-$(CONFIG_FOO) += foo.o
0145 
0146         $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
0147         If CONFIG_FOO is neither y nor m, then the file will not be compiled
0148         nor linked.
0149 
0150 --- 3.2 Built-in object goals - obj-y
0151 
0152         The kbuild Makefile specifies object files for vmlinux
0153         in the $(obj-y) lists.  These lists depend on the kernel
0154         configuration.
0155 
0156         Kbuild compiles all the $(obj-y) files.  It then calls
0157         "$(LD) -r" to merge these files into one built-in.o file.
0158         built-in.o is later linked into vmlinux by the parent Makefile.
0159 
0160         The order of files in $(obj-y) is significant.  Duplicates in
0161         the lists are allowed: the first instance will be linked into
0162         built-in.o and succeeding instances will be ignored.
0163 
0164         Link order is significant, because certain functions
0165         (module_init() / __initcall) will be called during boot in the
0166         order they appear. So keep in mind that changing the link
0167         order may e.g. change the order in which your SCSI
0168         controllers are detected, and thus your disks are renumbered.
0169 
0170         Example:
0171                 #drivers/isdn/i4l/Makefile
0172                 # Makefile for the kernel ISDN subsystem and device drivers.
0173                 # Each configuration option enables a list of files.
0174                 obj-$(CONFIG_ISDN_I4L)         += isdn.o
0175                 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
0176 
0177 --- 3.3 Loadable module goals - obj-m
0178 
0179         $(obj-m) specifies object files which are built as loadable
0180         kernel modules.
0181 
0182         A module may be built from one source file or several source
0183         files. In the case of one source file, the kbuild makefile
0184         simply adds the file to $(obj-m).
0185 
0186         Example:
0187                 #drivers/isdn/i4l/Makefile
0188                 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
0189 
0190         Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
0191 
0192         If a kernel module is built from several source files, you specify
0193         that you want to build a module in the same way as above; however,
0194         kbuild needs to know which object files you want to build your
0195         module from, so you have to tell it by setting a $(<module_name>-y)
0196         variable.
0197 
0198         Example:
0199                 #drivers/isdn/i4l/Makefile
0200                 obj-$(CONFIG_ISDN_I4L) += isdn.o
0201                 isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
0202 
0203         In this example, the module name will be isdn.o. Kbuild will
0204         compile the objects listed in $(isdn-y) and then run
0205         "$(LD) -r" on the list of these files to generate isdn.o.
0206 
0207         Due to kbuild recognizing $(<module_name>-y) for composite objects,
0208         you can use the value of a CONFIG_ symbol to optionally include an
0209         object file as part of a composite object.
0210 
0211         Example:
0212                 #fs/ext2/Makefile
0213                 obj-$(CONFIG_EXT2_FS) += ext2.o
0214                 ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
0215                           namei.o super.o symlink.o
0216                 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \
0217                                                 xattr_trusted.o
0218 
0219         In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
0220         part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
0221         evaluates to 'y'.
0222 
0223         Note: Of course, when you are building objects into the kernel,
0224         the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
0225         kbuild will build an ext2.o file for you out of the individual
0226         parts and then link this into built-in.o, as you would expect.
0227 
0228 --- 3.4 Objects which export symbols
0229 
0230         No special notation is required in the makefiles for
0231         modules exporting symbols.
0232 
0233 --- 3.5 Library file goals - lib-y
0234 
0235         Objects listed with obj-* are used for modules, or
0236         combined in a built-in.o for that specific directory.
0237         There is also the possibility to list objects that will
0238         be included in a library, lib.a.
0239         All objects listed with lib-y are combined in a single
0240         library for that directory.
0241         Objects that are listed in obj-y and additionally listed in
0242         lib-y will not be included in the library, since they will
0243         be accessible anyway.
0244         For consistency, objects listed in lib-m will be included in lib.a.
0245 
0246         Note that the same kbuild makefile may list files to be built-in
0247         and to be part of a library. Therefore the same directory
0248         may contain both a built-in.o and a lib.a file.
0249 
0250         Example:
0251                 #arch/x86/lib/Makefile
0252                 lib-y    := delay.o
0253 
0254         This will create a library lib.a based on delay.o. For kbuild to
0255         actually recognize that there is a lib.a being built, the directory
0256         shall be listed in libs-y.
0257         See also "6.4 List directories to visit when descending".
0258 
0259         Use of lib-y is normally restricted to lib/ and arch/*/lib.
0260 
0261 --- 3.6 Descending down in directories
0262 
0263         A Makefile is only responsible for building objects in its own
0264         directory. Files in subdirectories should be taken care of by
0265         Makefiles in these subdirs. The build system will automatically
0266         invoke make recursively in subdirectories, provided you let it know of
0267         them.
0268 
0269         To do so, obj-y and obj-m are used.
0270         ext2 lives in a separate directory, and the Makefile present in fs/
0271         tells kbuild to descend down using the following assignment.
0272 
0273         Example:
0274                 #fs/Makefile
0275                 obj-$(CONFIG_EXT2_FS) += ext2/
0276 
0277         If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
0278         the corresponding obj- variable will be set, and kbuild will descend
0279         down in the ext2 directory.
0280         Kbuild only uses this information to decide that it needs to visit
0281         the directory, it is the Makefile in the subdirectory that
0282         specifies what is modular and what is built-in.
0283 
0284         It is good practice to use a CONFIG_ variable when assigning directory
0285         names. This allows kbuild to totally skip the directory if the
0286         corresponding CONFIG_ option is neither 'y' nor 'm'.
0287 
0288 --- 3.7 Compilation flags
0289 
0290     ccflags-y, asflags-y and ldflags-y
0291         These three flags apply only to the kbuild makefile in which they
0292         are assigned. They are used for all the normal cc, as and ld
0293         invocations happening during a recursive build.
0294         Note: Flags with the same behaviour were previously named:
0295         EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
0296         They are still supported but their usage is deprecated.
0297 
0298         ccflags-y specifies options for compiling with $(CC).
0299 
0300         Example:
0301                 # drivers/acpi/Makefile
0302                 ccflags-y := -Os
0303                 ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT
0304 
0305         This variable is necessary because the top Makefile owns the
0306         variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
0307         entire tree.
0308 
0309         asflags-y specifies options for assembling with $(AS).
0310 
0311         Example:
0312                 #arch/sparc/kernel/Makefile
0313                 asflags-y := -ansi
0314 
0315         ldflags-y specifies options for linking with $(LD).
0316 
0317         Example:
0318                 #arch/cris/boot/compressed/Makefile
0319                 ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
0320 
0321     subdir-ccflags-y, subdir-asflags-y
0322         The two flags listed above are similar to ccflags-y and asflags-y.
0323         The difference is that the subdir- variants have effect for the kbuild
0324         file where they are present and all subdirectories.
0325         Options specified using subdir-* are added to the commandline before
0326         the options specified using the non-subdir variants.
0327 
0328         Example:
0329                 subdir-ccflags-y := -Werror
0330 
0331     CFLAGS_$@, AFLAGS_$@
0332 
0333         CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
0334         kbuild makefile.
0335 
0336         $(CFLAGS_$@) specifies per-file options for $(CC).  The $@
0337         part has a literal value which specifies the file that it is for.
0338 
0339         Example:
0340                 # drivers/scsi/Makefile
0341                 CFLAGS_aha152x.o =   -DAHA152X_STAT -DAUTOCONF
0342                 CFLAGS_gdth.o    = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
0343                                      -DGDTH_STATISTICS
0344 
0345         These two lines specify compilation flags for aha152x.o and gdth.o.
0346 
0347         $(AFLAGS_$@) is a similar feature for source files in assembly
0348         languages.
0349 
0350         Example:
0351                 # arch/arm/kernel/Makefile
0352                 AFLAGS_head.o        := -DTEXT_OFFSET=$(TEXT_OFFSET)
0353                 AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
0354                 AFLAGS_iwmmxt.o      := -Wa,-mcpu=iwmmxt
0355 
0356 
0357 --- 3.9 Dependency tracking
0358 
0359         Kbuild tracks dependencies on the following:
0360         1) All prerequisite files (both *.c and *.h)
0361         2) CONFIG_ options used in all prerequisite files
0362         3) Command-line used to compile target
0363 
0364         Thus, if you change an option to $(CC) all affected files will
0365         be re-compiled.
0366 
0367 --- 3.10 Special Rules
0368 
0369         Special rules are used when the kbuild infrastructure does
0370         not provide the required support. A typical example is
0371         header files generated during the build process.
0372         Another example are the architecture-specific Makefiles which
0373         need special rules to prepare boot images etc.
0374 
0375         Special rules are written as normal Make rules.
0376         Kbuild is not executing in the directory where the Makefile is
0377         located, so all special rules shall provide a relative
0378         path to prerequisite files and target files.
0379 
0380         Two variables are used when defining special rules:
0381 
0382     $(src)
0383         $(src) is a relative path which points to the directory
0384         where the Makefile is located. Always use $(src) when
0385         referring to files located in the src tree.
0386 
0387     $(obj)
0388         $(obj) is a relative path which points to the directory
0389         where the target is saved. Always use $(obj) when
0390         referring to generated files.
0391 
0392         Example:
0393                 #drivers/scsi/Makefile
0394                 $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
0395                         $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
0396 
0397         This is a special rule, following the normal syntax
0398         required by make.
0399         The target file depends on two prerequisite files. References
0400         to the target file are prefixed with $(obj), references
0401         to prerequisites are referenced with $(src) (because they are not
0402         generated files).
0403 
0404     $(kecho)
0405         echoing information to user in a rule is often a good practice
0406         but when execution "make -s" one does not expect to see any output
0407         except for warnings/errors.
0408         To support this kbuild defines $(kecho) which will echo out the
0409         text following $(kecho) to stdout except if "make -s" is used.
0410 
0411         Example:
0412                 #arch/blackfin/boot/Makefile
0413                 $(obj)/vmImage: $(obj)/vmlinux.gz
0414                         $(call if_changed,uimage)
0415                         @$(kecho) 'Kernel: $@ is ready'
0416 
0417 
0418 --- 3.11 $(CC) support functions
0419 
0420         The kernel may be built with several different versions of
0421         $(CC), each supporting a unique set of features and options.
0422         kbuild provides basic support to check for valid options for $(CC).
0423         $(CC) is usually the gcc compiler, but other alternatives are
0424         available.
0425 
0426     as-option
0427         as-option is used to check if $(CC) -- when used to compile
0428         assembler (*.S) files -- supports the given option. An optional
0429         second option may be specified if the first option is not supported.
0430 
0431         Example:
0432                 #arch/sh/Makefile
0433                 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
0434 
0435         In the above example, cflags-y will be assigned the option
0436         -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
0437         The second argument is optional, and if supplied will be used
0438         if first argument is not supported.
0439 
0440     cc-ldoption
0441         cc-ldoption is used to check if $(CC) when used to link object files
0442         supports the given option.  An optional second option may be
0443         specified if first option are not supported.
0444 
0445         Example:
0446                 #arch/x86/kernel/Makefile
0447                 vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
0448 
0449         In the above example, vsyscall-flags will be assigned the option
0450         -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
0451         The second argument is optional, and if supplied will be used
0452         if first argument is not supported.
0453 
0454     as-instr
0455         as-instr checks if the assembler reports a specific instruction
0456         and then outputs either option1 or option2
0457         C escapes are supported in the test instruction
0458         Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options
0459 
0460     cc-option
0461         cc-option is used to check if $(CC) supports a given option, and if
0462         not supported to use an optional second option.
0463 
0464         Example:
0465                 #arch/x86/Makefile
0466                 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
0467 
0468         In the above example, cflags-y will be assigned the option
0469         -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
0470         The second argument to cc-option is optional, and if omitted,
0471         cflags-y will be assigned no value if first option is not supported.
0472         Note: cc-option uses KBUILD_CFLAGS for $(CC) options
0473 
0474    cc-option-yn
0475         cc-option-yn is used to check if gcc supports a given option
0476         and return 'y' if supported, otherwise 'n'.
0477 
0478         Example:
0479                 #arch/ppc/Makefile
0480                 biarch := $(call cc-option-yn, -m32)
0481                 aflags-$(biarch) += -a32
0482                 cflags-$(biarch) += -m32
0483 
0484         In the above example, $(biarch) is set to y if $(CC) supports the -m32
0485         option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
0486         and $(cflags-y) will be assigned the values -a32 and -m32,
0487         respectively.
0488         Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
0489 
0490     cc-option-align
0491         gcc versions >= 3.0 changed the type of options used to specify
0492         alignment of functions, loops etc. $(cc-option-align), when used
0493         as prefix to the align options, will select the right prefix:
0494         gcc < 3.00
0495                 cc-option-align = -malign
0496         gcc >= 3.00
0497                 cc-option-align = -falign
0498 
0499         Example:
0500                 KBUILD_CFLAGS += $(cc-option-align)-functions=4
0501 
0502         In the above example, the option -falign-functions=4 is used for
0503         gcc >= 3.00. For gcc < 3.00, -malign-functions=4 is used.
0504         Note: cc-option-align uses KBUILD_CFLAGS for $(CC) options
0505 
0506     cc-disable-warning
0507         cc-disable-warning checks if gcc supports a given warning and returns
0508         the commandline switch to disable it. This special function is needed,
0509         because gcc 4.4 and later accept any unknown -Wno-* option and only
0510         warn about it if there is another warning in the source file.
0511 
0512         Example:
0513                 KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)
0514 
0515         In the above example, -Wno-unused-but-set-variable will be added to
0516         KBUILD_CFLAGS only if gcc really accepts it.
0517 
0518     cc-version
0519         cc-version returns a numerical version of the $(CC) compiler version.
0520         The format is <major><minor> where both are two digits. So for example
0521         gcc 3.41 would return 0341.
0522         cc-version is useful when a specific $(CC) version is faulty in one
0523         area, for example -mregparm=3 was broken in some gcc versions
0524         even though the option was accepted by gcc.
0525 
0526         Example:
0527                 #arch/x86/Makefile
0528                 cflags-y += $(shell \
0529                 if [ $(cc-version) -ge 0300 ] ; then \
0530                         echo "-mregparm=3"; fi ;)
0531 
0532         In the above example, -mregparm=3 is only used for gcc version greater
0533         than or equal to gcc 3.0.
0534 
0535     cc-ifversion
0536         cc-ifversion tests the version of $(CC) and equals the fourth parameter
0537         if version expression is true, or the fifth (if given) if the version
0538         expression is false.
0539 
0540         Example:
0541                 #fs/reiserfs/Makefile
0542                 ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
0543 
0544         In this example, ccflags-y will be assigned the value -O1 if the
0545         $(CC) version is less than 4.2.
0546         cc-ifversion takes all the shell operators:
0547         -eq, -ne, -lt, -le, -gt, and -ge
0548         The third parameter may be a text as in this example, but it may also
0549         be an expanded variable or a macro.
0550 
0551     cc-fullversion
0552         cc-fullversion is useful when the exact version of gcc is needed.
0553         One typical use-case is when a specific GCC version is broken.
0554         cc-fullversion points out a more specific version than cc-version does.
0555 
0556         Example:
0557                 #arch/powerpc/Makefile
0558                 $(Q)if test "$(cc-fullversion)" = "040200" ; then \
0559                         echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ; \
0560                         false ; \
0561                 fi
0562 
0563         In this example for a specific GCC version the build will error out
0564         explaining to the user why it stops.
0565 
0566     cc-cross-prefix
0567         cc-cross-prefix is used to check if there exists a $(CC) in path with
0568         one of the listed prefixes. The first prefix where there exist a
0569         prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
0570         then nothing is returned.
0571         Additional prefixes are separated by a single space in the
0572         call of cc-cross-prefix.
0573         This functionality is useful for architecture Makefiles that try
0574         to set CROSS_COMPILE to well-known values but may have several
0575         values to select between.
0576         It is recommended only to try to set CROSS_COMPILE if it is a cross
0577         build (host arch is different from target arch). And if CROSS_COMPILE
0578         is already set then leave it with the old value.
0579 
0580         Example:
0581                 #arch/m68k/Makefile
0582                 ifneq ($(SUBARCH),$(ARCH))
0583                         ifeq ($(CROSS_COMPILE),)
0584                                CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
0585                         endif
0586                 endif
0587 
0588 --- 3.12 $(LD) support functions
0589 
0590     ld-option
0591         ld-option is used to check if $(LD) supports the supplied option.
0592         ld-option takes two options as arguments.
0593         The second argument is an optional option that can be used if the
0594         first option is not supported by $(LD).
0595 
0596         Example:
0597                 #Makefile
0598                 LDFLAGS_vmlinux += $(call ld-option, -X)
0599 
0600 
0601 === 4 Host Program support
0602 
0603 Kbuild supports building executables on the host for use during the
0604 compilation stage.
0605 Two steps are required in order to use a host executable.
0606 
0607 The first step is to tell kbuild that a host program exists. This is
0608 done utilising the variable hostprogs-y.
0609 
0610 The second step is to add an explicit dependency to the executable.
0611 This can be done in two ways. Either add the dependency in a rule,
0612 or utilise the variable $(always).
0613 Both possibilities are described in the following.
0614 
0615 --- 4.1 Simple Host Program
0616 
0617         In some cases there is a need to compile and run a program on the
0618         computer where the build is running.
0619         The following line tells kbuild that the program bin2hex shall be
0620         built on the build host.
0621 
0622         Example:
0623                 hostprogs-y := bin2hex
0624 
0625         Kbuild assumes in the above example that bin2hex is made from a single
0626         c-source file named bin2hex.c located in the same directory as
0627         the Makefile.
0628 
0629 --- 4.2 Composite Host Programs
0630 
0631         Host programs can be made up based on composite objects.
0632         The syntax used to define composite objects for host programs is
0633         similar to the syntax used for kernel objects.
0634         $(<executable>-objs) lists all objects used to link the final
0635         executable.
0636 
0637         Example:
0638                 #scripts/lxdialog/Makefile
0639                 hostprogs-y   := lxdialog
0640                 lxdialog-objs := checklist.o lxdialog.o
0641 
0642         Objects with extension .o are compiled from the corresponding .c
0643         files. In the above example, checklist.c is compiled to checklist.o
0644         and lxdialog.c is compiled to lxdialog.o.
0645         Finally, the two .o files are linked to the executable, lxdialog.
0646         Note: The syntax <executable>-y is not permitted for host-programs.
0647 
0648 --- 4.3 Using C++ for host programs
0649 
0650         kbuild offers support for host programs written in C++. This was
0651         introduced solely to support kconfig, and is not recommended
0652         for general use.
0653 
0654         Example:
0655                 #scripts/kconfig/Makefile
0656                 hostprogs-y   := qconf
0657                 qconf-cxxobjs := qconf.o
0658 
0659         In the example above the executable is composed of the C++ file
0660         qconf.cc - identified by $(qconf-cxxobjs).
0661 
0662         If qconf is composed of a mixture of .c and .cc files, then an
0663         additional line can be used to identify this.
0664 
0665         Example:
0666                 #scripts/kconfig/Makefile
0667                 hostprogs-y   := qconf
0668                 qconf-cxxobjs := qconf.o
0669                 qconf-objs    := check.o
0670 
0671 --- 4.4 Controlling compiler options for host programs
0672 
0673         When compiling host programs, it is possible to set specific flags.
0674         The programs will always be compiled utilising $(HOSTCC) passed
0675         the options specified in $(HOSTCFLAGS).
0676         To set flags that will take effect for all host programs created
0677         in that Makefile, use the variable HOST_EXTRACFLAGS.
0678 
0679         Example:
0680                 #scripts/lxdialog/Makefile
0681                 HOST_EXTRACFLAGS += -I/usr/include/ncurses
0682 
0683         To set specific flags for a single file the following construction
0684         is used:
0685 
0686         Example:
0687                 #arch/ppc64/boot/Makefile
0688                 HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
0689 
0690         It is also possible to specify additional options to the linker.
0691 
0692         Example:
0693                 #scripts/kconfig/Makefile
0694                 HOSTLOADLIBES_qconf := -L$(QTDIR)/lib
0695 
0696         When linking qconf, it will be passed the extra option
0697         "-L$(QTDIR)/lib".
0698 
0699 --- 4.5 When host programs are actually built
0700 
0701         Kbuild will only build host-programs when they are referenced
0702         as a prerequisite.
0703         This is possible in two ways:
0704 
0705         (1) List the prerequisite explicitly in a special rule.
0706 
0707         Example:
0708                 #drivers/pci/Makefile
0709                 hostprogs-y := gen-devlist
0710                 $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
0711                         ( cd $(obj); ./gen-devlist ) < $<
0712 
0713         The target $(obj)/devlist.h will not be built before
0714         $(obj)/gen-devlist is updated. Note that references to
0715         the host programs in special rules must be prefixed with $(obj).
0716 
0717         (2) Use $(always)
0718         When there is no suitable special rule, and the host program
0719         shall be built when a makefile is entered, the $(always)
0720         variable shall be used.
0721 
0722         Example:
0723                 #scripts/lxdialog/Makefile
0724                 hostprogs-y   := lxdialog
0725                 always        := $(hostprogs-y)
0726 
0727         This will tell kbuild to build lxdialog even if not referenced in
0728         any rule.
0729 
0730 --- 4.6 Using hostprogs-$(CONFIG_FOO)
0731 
0732         A typical pattern in a Kbuild file looks like this:
0733 
0734         Example:
0735                 #scripts/Makefile
0736                 hostprogs-$(CONFIG_KALLSYMS) += kallsyms
0737 
0738         Kbuild knows about both 'y' for built-in and 'm' for module.
0739         So if a config symbol evaluates to 'm', kbuild will still build
0740         the binary. In other words, Kbuild handles hostprogs-m exactly
0741         like hostprogs-y. But only hostprogs-y is recommended to be used
0742         when no CONFIG symbols are involved.
0743 
0744 === 5 Kbuild clean infrastructure
0745 
0746 "make clean" deletes most generated files in the obj tree where the kernel
0747 is compiled. This includes generated files such as host programs.
0748 Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
0749 $(extra-y) and $(targets). They are all deleted during "make clean".
0750 Files matching the patterns "*.[oas]", "*.ko", plus some additional files
0751 generated by kbuild are deleted all over the kernel src tree when
0752 "make clean" is executed.
0753 
0754 Additional files can be specified in kbuild makefiles by use of $(clean-files).
0755 
0756         Example:
0757                 #lib/Makefile
0758                 clean-files := crc32table.h
0759 
0760 When executing "make clean", the file "crc32table.h" will be deleted.
0761 Kbuild will assume files to be in the same relative directory as the
0762 Makefile, except if prefixed with $(objtree).
0763 
0764 To delete a directory hierarchy use:
0765 
0766         Example:
0767                 #scripts/package/Makefile
0768                 clean-dirs := $(objtree)/debian/
0769 
0770 This will delete the directory debian in the toplevel directory, including all
0771 subdirectories.
0772 
0773 To exclude certain files from make clean, use the $(no-clean-files) variable.
0774 This is only a special case used in the top level Kbuild file:
0775 
0776         Example:
0777                 #Kbuild
0778                 no-clean-files := $(bounds-file) $(offsets-file)
0779 
0780 Usually kbuild descends down in subdirectories due to "obj-* := dir/",
0781 but in the architecture makefiles where the kbuild infrastructure
0782 is not sufficient this sometimes needs to be explicit.
0783 
0784         Example:
0785                 #arch/x86/boot/Makefile
0786                 subdir- := compressed/
0787 
0788 The above assignment instructs kbuild to descend down in the
0789 directory compressed/ when "make clean" is executed.
0790 
0791 To support the clean infrastructure in the Makefiles that build the
0792 final bootimage there is an optional target named archclean:
0793 
0794         Example:
0795                 #arch/x86/Makefile
0796                 archclean:
0797                         $(Q)$(MAKE) $(clean)=arch/x86/boot
0798 
0799 When "make clean" is executed, make will descend down in arch/x86/boot,
0800 and clean as usual. The Makefile located in arch/x86/boot/ may use
0801 the subdir- trick to descend further down.
0802 
0803 Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is
0804 included in the top level makefile, and the kbuild infrastructure
0805 is not operational at that point.
0806 
0807 Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
0808 be visited during "make clean".
0809 
0810 === 6 Architecture Makefiles
0811 
0812 The top level Makefile sets up the environment and does the preparation,
0813 before starting to descend down in the individual directories.
0814 The top level makefile contains the generic part, whereas
0815 arch/$(ARCH)/Makefile contains what is required to set up kbuild
0816 for said architecture.
0817 To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
0818 a few targets.
0819 
0820 When kbuild executes, the following steps are followed (roughly):
0821 1) Configuration of the kernel => produce .config
0822 2) Store kernel version in include/linux/version.h
0823 3) Updating all other prerequisites to the target prepare:
0824    - Additional prerequisites are specified in arch/$(ARCH)/Makefile
0825 4) Recursively descend down in all directories listed in
0826    init-* core* drivers-* net-* libs-* and build all targets.
0827    - The values of the above variables are expanded in arch/$(ARCH)/Makefile.
0828 5) All object files are then linked and the resulting file vmlinux is
0829    located at the root of the obj tree.
0830    The very first objects linked are listed in head-y, assigned by
0831    arch/$(ARCH)/Makefile.
0832 6) Finally, the architecture-specific part does any required post processing
0833    and builds the final bootimage.
0834    - This includes building boot records
0835    - Preparing initrd images and the like
0836 
0837 
0838 --- 6.1 Set variables to tweak the build to the architecture
0839 
0840     LDFLAGS             Generic $(LD) options
0841 
0842         Flags used for all invocations of the linker.
0843         Often specifying the emulation is sufficient.
0844 
0845         Example:
0846                 #arch/s390/Makefile
0847                 LDFLAGS         := -m elf_s390
0848         Note: ldflags-y can be used to further customise
0849         the flags used. See chapter 3.7.
0850 
0851     LDFLAGS_MODULE      Options for $(LD) when linking modules
0852 
0853         LDFLAGS_MODULE is used to set specific flags for $(LD) when
0854         linking the .ko files used for modules.
0855         Default is "-r", for relocatable output.
0856 
0857     LDFLAGS_vmlinux     Options for $(LD) when linking vmlinux
0858 
0859         LDFLAGS_vmlinux is used to specify additional flags to pass to
0860         the linker when linking the final vmlinux image.
0861         LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
0862 
0863         Example:
0864                 #arch/x86/Makefile
0865                 LDFLAGS_vmlinux := -e stext
0866 
0867     OBJCOPYFLAGS        objcopy flags
0868 
0869         When $(call if_changed,objcopy) is used to translate a .o file,
0870         the flags specified in OBJCOPYFLAGS will be used.
0871         $(call if_changed,objcopy) is often used to generate raw binaries on
0872         vmlinux.
0873 
0874         Example:
0875                 #arch/s390/Makefile
0876                 OBJCOPYFLAGS := -O binary
0877 
0878                 #arch/s390/boot/Makefile
0879                 $(obj)/image: vmlinux FORCE
0880                         $(call if_changed,objcopy)
0881 
0882         In this example, the binary $(obj)/image is a binary version of
0883         vmlinux. The usage of $(call if_changed,xxx) will be described later.
0884 
0885     KBUILD_AFLAGS               $(AS) assembler flags
0886 
0887         Default value - see top level Makefile
0888         Append or modify as required per architecture.
0889 
0890         Example:
0891                 #arch/sparc64/Makefile
0892                 KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
0893 
0894     KBUILD_CFLAGS               $(CC) compiler flags
0895 
0896         Default value - see top level Makefile
0897         Append or modify as required per architecture.
0898 
0899         Often, the KBUILD_CFLAGS variable depends on the configuration.
0900 
0901         Example:
0902                 #arch/x86/boot/compressed/Makefile
0903                 cflags-$(CONFIG_X86_32) := -march=i386
0904                 cflags-$(CONFIG_X86_64) := -mcmodel=small
0905                 KBUILD_CFLAGS += $(cflags-y)
0906 
0907         Many arch Makefiles dynamically run the target C compiler to
0908         probe supported options:
0909 
0910                 #arch/x86/Makefile
0911 
0912                 ...
0913                 cflags-$(CONFIG_MPENTIUMII)     += $(call cc-option,\
0914                                                 -march=pentium2,-march=i686)
0915                 ...
0916                 # Disable unit-at-a-time mode ...
0917                 KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
0918                 ...
0919 
0920 
0921         The first example utilises the trick that a config option expands
0922         to 'y' when selected.
0923 
0924     KBUILD_AFLAGS_KERNEL        $(AS) options specific for built-in
0925 
0926         $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
0927         resident kernel code.
0928 
0929     KBUILD_AFLAGS_MODULE   Options for $(AS) when building modules
0930 
0931         $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
0932         are used for $(AS).
0933         From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
0934 
0935     KBUILD_CFLAGS_KERNEL        $(CC) options specific for built-in
0936 
0937         $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
0938         resident kernel code.
0939 
0940     KBUILD_CFLAGS_MODULE   Options for $(CC) when building modules
0941 
0942         $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
0943         are used for $(CC).
0944         From commandline CFLAGS_MODULE shall be used (see kbuild.txt).
0945 
0946     KBUILD_LDFLAGS_MODULE   Options for $(LD) when linking modules
0947 
0948         $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options
0949         used when linking modules. This is often a linker script.
0950         From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).
0951 
0952     KBUILD_ARFLAGS   Options for $(AR) when creating archives
0953 
0954         $(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic
0955         mode) if this option is supported by $(AR).
0956 
0957     ARCH_CPPFLAGS, ARCH_AFLAGS, ARCH_CFLAGS   Overrides the kbuild defaults
0958 
0959         These variables are appended to the KBUILD_CPPFLAGS,
0960         KBUILD_AFLAGS, and KBUILD_CFLAGS, respectively, after the
0961         top-level Makefile has set any other flags. This provides a
0962         means for an architecture to override the defaults.
0963 
0964 
0965 --- 6.2 Add prerequisites to archheaders:
0966 
0967         The archheaders: rule is used to generate header files that
0968         may be installed into user space by "make header_install" or
0969         "make headers_install_all".  In order to support
0970         "make headers_install_all", this target has to be able to run
0971         on an unconfigured tree, or a tree configured for another
0972         architecture.
0973 
0974         It is run before "make archprepare" when run on the
0975         architecture itself.
0976 
0977 
0978 --- 6.3 Add prerequisites to archprepare:
0979 
0980         The archprepare: rule is used to list prerequisites that need to be
0981         built before starting to descend down in the subdirectories.
0982         This is usually used for header files containing assembler constants.
0983 
0984                 Example:
0985                 #arch/arm/Makefile
0986                 archprepare: maketools
0987 
0988         In this example, the file target maketools will be processed
0989         before descending down in the subdirectories.
0990         See also chapter XXX-TODO that describe how kbuild supports
0991         generating offset header files.
0992 
0993 
0994 --- 6.4 List directories to visit when descending
0995 
0996         An arch Makefile cooperates with the top Makefile to define variables
0997         which specify how to build the vmlinux file.  Note that there is no
0998         corresponding arch-specific section for modules; the module-building
0999         machinery is all architecture-independent.
1000 
1001 
1002     head-y, init-y, core-y, libs-y, drivers-y, net-y
1003 
1004         $(head-y) lists objects to be linked first in vmlinux.
1005         $(libs-y) lists directories where a lib.a archive can be located.
1006         The rest list directories where a built-in.o object file can be
1007         located.
1008 
1009         $(init-y) objects will be located after $(head-y).
1010         Then the rest follows in this order:
1011         $(core-y), $(libs-y), $(drivers-y) and $(net-y).
1012 
1013         The top level Makefile defines values for all generic directories,
1014         and arch/$(ARCH)/Makefile only adds architecture-specific directories.
1015 
1016         Example:
1017                 #arch/sparc64/Makefile
1018                 core-y += arch/sparc64/kernel/
1019                 libs-y += arch/sparc64/prom/ arch/sparc64/lib/
1020                 drivers-$(CONFIG_OPROFILE)  += arch/sparc64/oprofile/
1021 
1022 
1023 --- 6.5 Architecture-specific boot images
1024 
1025         An arch Makefile specifies goals that take the vmlinux file, compress
1026         it, wrap it in bootstrapping code, and copy the resulting files
1027         somewhere. This includes various kinds of installation commands.
1028         The actual goals are not standardized across architectures.
1029 
1030         It is common to locate any additional processing in a boot/
1031         directory below arch/$(ARCH)/.
1032 
1033         Kbuild does not provide any smart way to support building a
1034         target specified in boot/. Therefore arch/$(ARCH)/Makefile shall
1035         call make manually to build a target in boot/.
1036 
1037         The recommended approach is to include shortcuts in 
1038         arch/$(ARCH)/Makefile, and use the full path when calling down
1039         into the arch/$(ARCH)/boot/Makefile.
1040 
1041         Example:
1042                 #arch/x86/Makefile
1043                 boot := arch/x86/boot
1044                 bzImage: vmlinux
1045                         $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@
1046 
1047         "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
1048         make in a subdirectory.
1049 
1050         There are no rules for naming architecture-specific targets,
1051         but executing "make help" will list all relevant targets.
1052         To support this, $(archhelp) must be defined.
1053 
1054         Example:
1055                 #arch/x86/Makefile
1056                 define archhelp
1057                   echo  '* bzImage      - Image (arch/$(ARCH)/boot/bzImage)'
1058                 endif
1059 
1060         When make is executed without arguments, the first goal encountered
1061         will be built. In the top level Makefile the first goal present
1062         is all:.
1063         An architecture shall always, per default, build a bootable image.
1064         In "make help", the default goal is highlighted with a '*'.
1065         Add a new prerequisite to all: to select a default goal different
1066         from vmlinux.
1067 
1068         Example:
1069                 #arch/x86/Makefile
1070                 all: bzImage
1071 
1072         When "make" is executed without arguments, bzImage will be built.
1073 
1074 --- 6.6 Building non-kbuild targets
1075 
1076     extra-y
1077 
1078         extra-y specifies additional targets created in the current
1079         directory, in addition to any targets specified by obj-*.
1080 
1081         Listing all targets in extra-y is required for two purposes:
1082         1) Enable kbuild to check changes in command lines
1083            - When $(call if_changed,xxx) is used
1084         2) kbuild knows what files to delete during "make clean"
1085 
1086         Example:
1087                 #arch/x86/kernel/Makefile
1088                 extra-y := head.o init_task.o
1089 
1090         In this example, extra-y is used to list object files that
1091         shall be built, but shall not be linked as part of built-in.o.
1092 
1093 
1094 --- 6.7 Commands useful for building a boot image
1095 
1096         Kbuild provides a few macros that are useful when building a
1097         boot image.
1098 
1099     if_changed
1100 
1101         if_changed is the infrastructure used for the following commands.
1102 
1103         Usage:
1104                 target: source(s) FORCE
1105                         $(call if_changed,ld/objcopy/gzip/...)
1106 
1107         When the rule is evaluated, it is checked to see if any files
1108         need an update, or the command line has changed since the last
1109         invocation. The latter will force a rebuild if any options
1110         to the executable have changed.
1111         Any target that utilises if_changed must be listed in $(targets),
1112         otherwise the command line check will fail, and the target will
1113         always be built.
1114         Assignments to $(targets) are without $(obj)/ prefix.
1115         if_changed may be used in conjunction with custom commands as
1116         defined in 6.8 "Custom kbuild commands".
1117 
1118         Note: It is a typical mistake to forget the FORCE prerequisite.
1119         Another common pitfall is that whitespace is sometimes
1120         significant; for instance, the below will fail (note the extra space
1121         after the comma):
1122                 target: source(s) FORCE
1123         #WRONG!#        $(call if_changed, ld/objcopy/gzip/...)
1124 
1125     ld
1126         Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1127 
1128     objcopy
1129         Copy binary. Uses OBJCOPYFLAGS usually specified in
1130         arch/$(ARCH)/Makefile.
1131         OBJCOPYFLAGS_$@ may be used to set additional options.
1132 
1133     gzip
1134         Compress target. Use maximum compression to compress target.
1135 
1136         Example:
1137                 #arch/x86/boot/Makefile
1138                 LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
1139                 LDFLAGS_setup    := -Ttext 0x0 -s --oformat binary -e begtext
1140 
1141                 targets += setup setup.o bootsect bootsect.o
1142                 $(obj)/setup $(obj)/bootsect: %: %.o FORCE
1143                         $(call if_changed,ld)
1144 
1145         In this example, there are two possible targets, requiring different
1146         options to the linker. The linker options are specified using the
1147         LDFLAGS_$@ syntax - one for each potential target.
1148         $(targets) are assigned all potential targets, by which kbuild knows
1149         the targets and will:
1150                 1) check for commandline changes
1151                 2) delete target during make clean
1152 
1153         The ": %: %.o" part of the prerequisite is a shorthand that
1154         frees us from listing the setup.o and bootsect.o files.
1155         Note: It is a common mistake to forget the "targets :=" assignment,
1156               resulting in the target file being recompiled for no
1157               obvious reason.
1158 
1159     dtc
1160         Create flattened device tree blob object suitable for linking
1161         into vmlinux. Device tree blobs linked into vmlinux are placed
1162         in an init section in the image. Platform code *must* copy the
1163         blob to non-init memory prior to calling unflatten_device_tree().
1164 
1165         To use this command, simply add *.dtb into obj-y or targets, or make
1166         some other target depend on %.dtb
1167 
1168         A central rule exists to create $(obj)/%.dtb from $(src)/%.dts;
1169         architecture Makefiles do no need to explicitly write out that rule.
1170 
1171         Example:
1172                 targets += $(dtb-y)
1173                 clean-files += *.dtb
1174                 DTC_FLAGS ?= -p 1024
1175 
1176 --- 6.8 Custom kbuild commands
1177 
1178         When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
1179         of a command is normally displayed.
1180         To enable this behaviour for custom commands kbuild requires
1181         two variables to be set:
1182         quiet_cmd_<command>     - what shall be echoed
1183               cmd_<command>     - the command to execute
1184 
1185         Example:
1186                 #
1187                 quiet_cmd_image = BUILD   $@
1188                       cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
1189                                                      $(obj)/vmlinux.bin > $@
1190 
1191                 targets += bzImage
1192                 $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
1193                         $(call if_changed,image)
1194                         @echo 'Kernel: $@ is ready'
1195 
1196         When updating the $(obj)/bzImage target, the line
1197 
1198         BUILD    arch/x86/boot/bzImage
1199 
1200         will be displayed with "make KBUILD_VERBOSE=0".
1201 
1202 
1203 --- 6.9 Preprocessing linker scripts
1204 
1205         When the vmlinux image is built, the linker script
1206         arch/$(ARCH)/kernel/vmlinux.lds is used.
1207         The script is a preprocessed variant of the file vmlinux.lds.S
1208         located in the same directory.
1209         kbuild knows .lds files and includes a rule *lds.S -> *lds.
1210 
1211         Example:
1212                 #arch/x86/kernel/Makefile
1213                 always := vmlinux.lds
1214 
1215                 #Makefile
1216                 export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
1217 
1218         The assignment to $(always) is used to tell kbuild to build the
1219         target vmlinux.lds.
1220         The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
1221         specified options when building the target vmlinux.lds.
1222 
1223         When building the *.lds target, kbuild uses the variables:
1224         KBUILD_CPPFLAGS : Set in top-level Makefile
1225         cppflags-y      : May be set in the kbuild makefile
1226         CPPFLAGS_$(@F)  : Target-specific flags.
1227                           Note that the full filename is used in this
1228                           assignment.
1229 
1230         The kbuild infrastructure for *lds files is used in several
1231         architecture-specific files.
1232 
1233 --- 6.10 Generic header files
1234 
1235         The directory include/asm-generic contains the header files
1236         that may be shared between individual architectures.
1237         The recommended approach how to use a generic header file is
1238         to list the file in the Kbuild file.
1239         See "7.4 generic-y" for further info on syntax etc.
1240 
1241 --- 6.11 Post-link pass
1242 
1243         If the file arch/xxx/Makefile.postlink exists, this makefile
1244         will be invoked for post-link objects (vmlinux and modules.ko)
1245         for architectures to run post-link passes on. Must also handle
1246         the clean target.
1247 
1248         This pass runs after kallsyms generation. If the architecture
1249         needs to modify symbol locations, rather than manipulate the
1250         kallsyms, it may be easier to add another postlink target for
1251         .tmp_vmlinux? targets to be called from link-vmlinux.sh.
1252 
1253         For example, powerpc uses this to check relocation sanity of
1254         the linked vmlinux file.
1255 
1256 === 7 Kbuild syntax for exported headers
1257 
1258 The kernel includes a set of headers that is exported to userspace.
1259 Many headers can be exported as-is but other headers require a
1260 minimal pre-processing before they are ready for user-space.
1261 The pre-processing does:
1262 - drop kernel-specific annotations
1263 - drop include of compiler.h 
1264 - drop all sections that are kernel internal (guarded by ifdef __KERNEL__)
1265 
1266 Each relevant directory contains a file name "Kbuild" which specifies the
1267 headers to be exported.
1268 See subsequent chapter for the syntax of the Kbuild file.
1269 
1270         --- 7.1 header-y
1271 
1272         header-y specifies header files to be exported.
1273 
1274                 Example:
1275                         #include/linux/Kbuild
1276                         header-y += usb/
1277                         header-y += aio_abi.h
1278 
1279         The convention is to list one file per line and
1280         preferably in alphabetic order.
1281 
1282         header-y also specifies which subdirectories to visit.
1283         A subdirectory is identified by a trailing '/' which
1284         can be seen in the example above for the usb subdirectory.
1285 
1286         Subdirectories are visited before their parent directories.
1287 
1288         --- 7.2 genhdr-y
1289 
1290         genhdr-y specifies generated files to be exported.
1291         Generated files are special as they need to be looked
1292         up in another directory when doing 'make O=...' builds.
1293 
1294                 Example:
1295                         #include/linux/Kbuild
1296                         genhdr-y += version.h
1297 
1298         --- 7.3 destination-y
1299 
1300         When an architecture has a set of exported headers that needs to be
1301         exported to a different directory destination-y is used.
1302         destination-y specifies the destination directory for all exported
1303         headers in the file where it is present.
1304 
1305                 Example:
1306                         #arch/xtensa/platforms/s6105/include/platform/Kbuild
1307                         destination-y := include/linux
1308 
1309         In the example above all exported headers in the Kbuild file
1310         will be located in the directory "include/linux" when exported.
1311 
1312         --- 7.4 generic-y
1313 
1314         If an architecture uses a verbatim copy of a header from
1315         include/asm-generic then this is listed in the file
1316         arch/$(ARCH)/include/asm/Kbuild like this:
1317 
1318                 Example:
1319                         #arch/x86/include/asm/Kbuild
1320                         generic-y += termios.h
1321                         generic-y += rtc.h
1322 
1323         During the prepare phase of the build a wrapper include
1324         file is generated in the directory: 
1325 
1326                 arch/$(ARCH)/include/generated/asm
1327 
1328         When a header is exported where the architecture uses
1329         the generic header a similar wrapper is generated as part
1330         of the set of exported headers in the directory:
1331 
1332                 usr/include/asm
1333 
1334         The generated wrapper will in both cases look like the following:
1335 
1336                 Example: termios.h
1337                         #include <asm-generic/termios.h>
1338 
1339         --- 7.5 generated-y
1340 
1341         If an architecture generates other header files alongside generic-y
1342         wrappers, and not included in genhdr-y, then generated-y specifies
1343         them.
1344 
1345         This prevents them being treated as stale asm-generic wrappers and
1346         removed.
1347 
1348                 Example:
1349                         #arch/x86/include/asm/Kbuild
1350                         generated-y += syscalls_32.h
1351 
1352 === 8 Kbuild Variables
1353 
1354 The top Makefile exports the following variables:
1355 
1356     VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
1357 
1358         These variables define the current kernel version.  A few arch
1359         Makefiles actually use these values directly; they should use
1360         $(KERNELRELEASE) instead.
1361 
1362         $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
1363         three-part version number, such as "2", "4", and "0".  These three
1364         values are always numeric.
1365 
1366         $(EXTRAVERSION) defines an even tinier sublevel for pre-patches
1367         or additional patches.  It is usually some non-numeric string
1368         such as "-pre4", and is often blank.
1369 
1370     KERNELRELEASE
1371 
1372         $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
1373         for constructing installation directory names or showing in
1374         version strings.  Some arch Makefiles use it for this purpose.
1375 
1376     ARCH
1377 
1378         This variable defines the target architecture, such as "i386",
1379         "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
1380         determine which files to compile.
1381 
1382         By default, the top Makefile sets $(ARCH) to be the same as the
1383         host system architecture.  For a cross build, a user may
1384         override the value of $(ARCH) on the command line:
1385 
1386             make ARCH=m68k ...
1387 
1388 
1389     INSTALL_PATH
1390 
1391         This variable defines a place for the arch Makefiles to install
1392         the resident kernel image and System.map file.
1393         Use this for architecture-specific install targets.
1394 
1395     INSTALL_MOD_PATH, MODLIB
1396 
1397         $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
1398         installation.  This variable is not defined in the Makefile but
1399         may be passed in by the user if desired.
1400 
1401         $(MODLIB) specifies the directory for module installation.
1402         The top Makefile defines $(MODLIB) to
1403         $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE).  The user may
1404         override this value on the command line if desired.
1405 
1406     INSTALL_MOD_STRIP
1407 
1408         If this variable is specified, it will cause modules to be stripped
1409         after they are installed.  If INSTALL_MOD_STRIP is '1', then the
1410         default option --strip-debug will be used.  Otherwise, the
1411         INSTALL_MOD_STRIP value will be used as the option(s) to the strip
1412         command.
1413 
1414 
1415 === 9 Makefile language
1416 
1417 The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
1418 use only the documented features of GNU Make, but they do use many
1419 GNU extensions.
1420 
1421 GNU Make supports elementary list-processing functions.  The kernel
1422 Makefiles use a novel style of list building and manipulation with few
1423 "if" statements.
1424 
1425 GNU Make has two assignment operators, ":=" and "=".  ":=" performs
1426 immediate evaluation of the right-hand side and stores an actual string
1427 into the left-hand side.  "=" is like a formula definition; it stores the
1428 right-hand side in an unevaluated form and then evaluates this form each
1429 time the left-hand side is used.
1430 
1431 There are some cases where "=" is appropriate.  Usually, though, ":="
1432 is the right choice.
1433 
1434 === 10 Credits
1435 
1436 Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1437 Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1438 Updates by Sam Ravnborg <sam@ravnborg.org>
1439 Language QA by Jan Engelhardt <jengelh@gmx.de>
1440 
1441 === 11 TODO
1442 
1443 - Describe how kbuild supports shipped files with _shipped.
1444 - Generating offset header files.
1445 - Add more variables to section 7?
1446 
1447 
1448