内核的makefile文档 2.6.30 Kernel

Linux Kernel Makefiles
This document describes the Linux kernel Makefiles.
=== Table of Contents
    === 1 Overview
    === 2 Who does what
    === 3 The kbuild files
       --- 3.1 Goal definitions
       --- 3.2 Built-in object goals - obj-y
       --- 3.3 Loadable module goals - obj-m
       --- 3.4 Objects which export symbols
       --- 3.5 Library file goals - lib-y
       --- 3.6 Descending down in directories
       --- 3.7 Compilation flags
       --- 3.8 Command line dependency
       --- 3.9 Dependency tracking
       --- 3.10 Special Rules
       --- 3.11 $(CC) support functions
    === 4 Host Program support
       --- 4.1 Simple Host Program
       --- 4.2 Composite Host Programs
       --- 4.3 Defining shared libraries
       --- 4.4 Using C++ for host programs
       --- 4.5 Controlling compiler options for host programs
       --- 4.6 When host programs are actually built
       --- 4.7 Using hostprogs-$(CONFIG_FOO)
    === 5 Kbuild clean infrastructure
    === 6 Architecture Makefiles
       --- 6.1 Set variables to tweak the build to the architecture
       --- 6.2 Add prerequisites to archprepare:
       --- 6.3 List directories to visit when descending
       --- 6.4 Architecture-specific boot images
       --- 6.5 Building non-kbuild targets
       --- 6.6 Commands useful for building a boot image
       --- 6.7 Custom kbuild commands
       --- 6.8 Preprocessing linker scripts
    === 7 Kbuild syntax for exported headers
        --- 7.1 header-y
        --- 7.2 objhdr-y
        --- 7.3 destination-y
        --- 7.4 unifdef-y (deprecated)
    === 8 Kbuild Variables
    === 9 Makefile language
    === 10 Credits
    === 11 TODO

=== 1 Overview

The Makefiles have five parts:
    Makefile        the top Makefile.
    .config            the kernel configuration file.
    arch/$(ARCH)/Makefile    the arch Makefile.
    scripts/Makefile.*    common rules etc. for all kbuild Makefiles.

    kbuild Makefiles    there are about 500 of these.

The top Makefile reads the .config file, which comes from the kernel configuration process.
The top Makefile is responsible for building two major products: vmlinux (the resident kernel image) and modules (any module files). It builds these goals by recursively descending into the subdirectories of the kernel source tree. The list of subdirectories which are visited depends upon the kernel configuration. The top Makefile textually includes an arch Makefile with the name arch/$(ARCH)/Makefile. The arch Makefile supplies architecture-specific information to the top Makefile.
Each subdirectory has a kbuild Makefile which carries out the commands passed down from above. The kbuild Makefile uses information from the .config file to construct various file lists used by kbuild to build any built-in or modular targets.
scripts/Makefile.* contains all the definitions/rules etc. that are used to build the kernel based on the kbuild makefiles.

=== 2 Who does what

People have four different relationships with the kernel Makefiles.
*Users* are people who build kernels.  These people type commands such as "make menuconfig" or "make".  They usually do not read or edit any kernel Makefiles (or any other source files).
*Normal developers* are people who work on features such as device drivers, file systems, and network protocols.  These people need to maintain the kbuild Makefiles for the subsystem they are working on.  In order to do this effectively, they need some overall knowledge about the kernel Makefiles, plus detailed knowledge about the public interface for kbuild.
*Arch developers* are people who work on an entire architecture, such as sparc or ia64.  Arch developers need to know about the arch Makefile as well as kbuild Makefiles.
*Kbuild developers* are people who work on the kernel build system itself. These people need to know about all aspects of the kernel Makefiles.
This document is aimed towards normal developers and arch developers.

=== 3 The kbuild files 

这章针对kbuild makefiles的语法进行介绍，文件名可以是Kbuild或者Makefile，前者优先级更高。

--- 3.1 Goal definitions

    Goal definitions are the main part (heart) of the kbuild Makefile. These lines define the files to be built, any special compilation options, and any subdirectories to be entered recursively.
    The most simple kbuild makefile contains one line:
    Example: obj-y += foo.o
    This tells kbuild that there is one object in that directory, named
    foo.o. foo.o will be built from foo.c or foo.S.
    If foo.o shall be built as a module, the variable obj-m is used. Therefore the following pattern is often used:
    Example: obj-$(CONFIG_FOO) += foo.o
    $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module). If CONFIG_FOO is neither y nor m, then the file will not be compiled  nor linked.

--- 3.2 Built-in object goals - obj-y 内建对象目标 obj-y

    The kbuild Makefile specifies object files for vmlinux in the $(obj-y) lists.  These lists depend on the kernel configuration.
    Kbuild compiles all the $(obj-y) files.  It then calls  "$(LD) -r" to merge these files into one built-in.o file.
    built-in.o is later linked into vmlinux by the parent Makefile.
    The order of files in $(obj-y) is significant.  Duplicates in the lists are allowed: the first instance will be linked into built-in.o and succeeding instances will be ignored.

    Link order is significant, because certain functions (module_init() / __initcall) will be called during boot in the order they appear.

So keep in mind that changing the link order may e.g. change the order in which your SCSI controllers are detected, and thus your disks are renumbered.

    Example: #drivers/isdn/i4l/Makefile

        # Makefile for the kernel ISDN subsystem and device drivers.
        # Each configuration option enables a list of files.
        obj-$(CONFIG_ISDN)             += isdn.o
        obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o

--- 3.3 Loadable module goals - obj-m 可加载模块目标 obj-m

    $(obj-m) specify object files which are built as loadable kernel modules.

    A module may be built from one source file or several source files.  单文件构建模块

   1 In the case of one source file, the kbuild makefile simply adds the file to $(obj-m).

    Example: #drivers/isdn/i4l/Makefile

        obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
    Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
   2 If a kernel module is built from several source files, you specify that you want to build a module in the same way as above. 多文件构建模块
    Kbuild needs to know which the parts that you want to build your module from, so you have to tell it by setting an $(<module_name>-objs) variable.

    Example: #drivers/isdn/i4l/Makefile

        obj-$(CONFIG_ISDN) += isdn.o    //再多文件构建目标的规则中，仍然是类似于上面的单文件构建模块，后面加上XXX-objs:= ***.o ***.o ***.o
        isdn-objs := isdn_net_lib.o isdn_v110.o isdn_common.o
    In this example, the module name will be isdn.o. Kbuild will compile the objects listed in $(isdn-objs) and then run "$(LD) -r" on the list of these files to generate isdn.o.
    Kbuild recognises objects used for composite objects by the suffix -objs, and the suffix -y. This allows the Makefiles to use the value of a CONFIG_ symbol to determine if an object is part of a composite object.

    Example: #fs/ext2/Makefile

     obj-$(CONFIG_EXT2_FS)   += ext2.o

     ext2-y  := balloc.o bitmap.o         

     ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o

    In this example, xattr.o is only part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR) evaluates to 'y'.

    Note: Of course, when you are building objects into the kernel, the syntax above will also work.

    So, if you have CONFIG_EXT2_FS=y, kbuild will build an ext2.o file for you out of the individual parts and then link this into built-in.o, as you would expect.

--- 3.4 Objects which export symbols

    No special notation is required in the makefiles for modules exporting symbols.

--- 3.5 Library file goals - lib-y  库文件目标 lib-y

    Objects listed with obj-* are used for modules, or combined in a built-in.o for that specific directory.
    There is also the possibility to list objects that will be included in a library, lib.a.
    All objects listed with lib-y are combined in a single library for that directory.
    Objects that are listed in obj-y and additionally listed in lib-y will not be included in the library, since they will  be accessible anyway.
    For consistency, objects listed in lib-m will be included in lib.a.
    Note that the same kbuild makefile may list files to be built-in and to be part of a library. Therefore the same directory may contain both a built-in.o and a lib.a file.

    Example: #arch/i386/lib/Makefile

        lib-y    := checksum.o delay.o
    This will create a library lib.a based on checksum.o and delay.o.
    For kbuild to actually recognize that there is a lib.a being built, the directory shall be listed in libs-y.
    See also "6.3 List directories to visit when descending".
    Use of lib-y is normally restricted to lib/ and arch/*/lib.

--- 3.6 Descending down in directories

    A Makefile is only responsible for build