KBUILD 2.5
Sections
  Makefiles
  Defining source and object trees
  kbuild targets
  Why have shadow trees?
  Global Makefile
  NO_MAKEFILE_GEN (fast build mode, only for experts)
  Makefile.in syntax
  Pre-processor programs
  Shipping generated files
  Converting old kbuild Makefiles
  Controlling kbuild
  Temporary files for kbuild
  Additional targets and commands
  Offsets for Assembler
  Identifying shadow files
  Converting shadow trees to a single source tree


MAKEFILES

  There are only two real Makefiles in the 2.5 kbuild system, the top level
  Makefile and scripts/Makefile.  For parallel running with 2.4 kernels,
  these are called Makefile-2.5 and will be renamed when the old kbuild is
  removed, until then use "make -f Makefile-2.5".

  The rest of the make information for kbuild 2.5 comes from Makefile.in
  files, one per directory that contains kernel code, plus architecture
  dependent files arch/$(ARCH)/Makefile.defs.noconfig and .config.  These
  files are read and processed by Makefile-2.5 and scripts/Makefile-2.5 to
  generate a global makefile which defines the entire kernel.


DEFINING SOURCE AND OBJECT TREES

  kbuild 2.5 can run in one of three modes:

  (1) Source and object in the same tree.  This is the only way that kbuild
      2.4 works and it is the default mode for kbuild 2.5.

        cd linux
        make -f Makefile-2.5

  (2) Separate source and object trees.  The source tree becomes read only,
      all files that are written or updated are done in the object tree.

        export KBUILD_OBJTREE=object_tree
        export KBUILD_SRCTREE_000=src_tree
        make -f $KBUILD_SRCTREE_000/Makefile-2.5

      You do not have to cd to either directory, make can be issued from
      anywhere.  The .config is held in the object directory, as is the
      asm-$ARCH symlink.  It is legal to do multiple compiles from the same
      source tree using different object trees, for the same architecture or
      for different architectures.  You can run multiple compiles in parallel
      for multiple architectures from the same source tree as long as each
      compile uses a different object tree.

  (3) Multiple source trees with a separate object tree.  This is an
      extension of mode (2) where the source is split over two or more source
      trees.  kbuild 2.5 logically merges files from all the source trees to
      form a single source tree for the purposes of compilation.

        export KBUILD_OBJTREE=object_tree
        export KBUILD_SRCTREE_000=base_src_tree
        export KBUILD_SRCTREE_010=shadow_tree_1
        export KBUILD_SRCTREE_020=shadow_tree_2
        make -f $KBUILD_SRCTREE_000/Makefile-2.5

      The logical source tree is synthesized from the base tree plus one or
      more shadow trees.  Shadow trees have the same directory structure as
      the base tree but they are are sparse, containing only the files that
      are different from the base tree and any related directories.  If the
      same filename appears in more than one source tree, the copy in the
      highest numbered tree is used.

      Source tree numbers range from 000 to 998, 999 is reserved internally
      for the object tree.  Tree 000 is always where kbuild runs from.  The
      kbuild code is only read from tree 000, i.e. you cannot use a shadow
      tree to test a new version of kbuild.  However you can have tree 000
      containing just the kbuild 2.5 code with the main kernel in a higher
      tree.  This configuration is only useful when converting from kbuild
      2.4 to 2.5, it lets you keep the kbuild 2.5 changes separate from
      Linus's kernel.

      A shadow file does not always have to be a complete replacement for the
      base file.  Many of the kbuild files are just lists, e.g.
      Configure.help or the list of drivers that are selected by a config
      option.  In many cases, appending to the end of an existing file is all
      that is required.  kbuild 2.5 recognizes special file suffices,
      '.append' and '.prepend'.  The final source file is built up from all
      .prepend files (top down), the primary file then all .append files
      (bottom up).

      For example, Documentation/Configure.help.append in a shadow tree is
      appended to Documentation/Configure.help.  To preserve the read only
      status of the source trees, prepend and append are done using a copy of
      the base file in the object tree, then the generated copy is used
      instead of the source file.

  Unlike kbuild 2.4, renaming a source or object tree does not force a
  complete rebuild.  After renaming any tree and updating the KBUILD_SRCTREE
  and KBUILD_OBJTREE variables, just run make.  Unless you have changed any
  files, nothing should be rebuilt, however the make step must be run to save
  the new tree names ready for the install step.


KBUILD TARGETS

  kbuild targets define what you want to build, they are specified on the
  make command line.  If you do not specify what to build, the default is
  "installable", to build an installable system.  Typical targets are

      oldconfig, xconfig, menuconfig, config etc.
      installable
      install
      install_with_errors

  You can also specify a directory name (e.g. drivers/char) which will build
  targets in that directory, without recursion.  Appending '-r' to the
  directory name (e.g. drivers/char-r) will do a recursive build in that
  directory and its children.  Not that zImage, bzImage, modules are not
  supported targets in kbuild 2.5, it does not have an artificial separation
  between building the kernel and building modules.

  Before building a kernel, you must run one of the make *config options.
  Also if you hand edit .config, you must run make *config before building.
  This is to ensure that the .config has been validated by the configuration
  mini language (CML).

  If you run make kbuild 2.5 without specifying any targets then the default
  target is 'installable'.  At a minimum, this builds vmlinux, any modules
  and System.map.  It may build additional targets, depending on your config
  options.  Unlike kbuild 2.4, the user does not specify make bzImage, make
  zImage, make sImage etc.  Instead the .config defines what additional
  targets are to be built from vmlinux, the possibilities are architecture
  specific.  You can manually specify installable as a target, when you want
  to make a config and build in the same run you can do
    make *config installable.

  After installable has succeeded, the next step is to install the kernel,
  using make install.  Unlike kbuild 2.4, there are not lots of little rules
  for special install processing.  Instead the standard install options are
  in .config, including whether to install System.map, .config, whether to
  use an install path prefix and any special commands to run after the
  standard install.  See "Controlling kbuild" below.

  Unless you are using a path prefix on install, you need root to run make
  install.  Avoid compiling the kernel as root, it is bad practice to do too
  much work as root.  The recommended method is
    make *config installable && sudo make install
  Also unlike kbuild 2.4, make install checks that the build is up to date.

  If the install user is different from the compile user then kbuild switches
  into read only mode and will refuse to update any build files.  This
  prevents root creating files which the build user cannot then access.
  Always complete the build before running make install as another user.

  Some users want to do an install even if the build is incomplete, e.g.
  even if some modules fail to build.  Obviously the kernel has to build
  correctly.  These users should 'make install_with_errors'.  This target
  will bypass the checks on whether the build is complete or not.  Because
  the checks are bypassed, it is not safe to specify this target with any
  other targets.  You must specify 'make install_with_errors' on its own, it
  cannot be mixed with any other targets.

  In addition to the *config, installable and install targets, kbuild 2.5
  lets you build an individual target or all targets in a directory, with or
  without recursion.  This must not be confused with a clean build, make
  install always requires a clean make installable first.

  Examples:
    make drivers/net/eepro100.o - build just this target
    make drivers/net - build all targets in drivers/net, without recursion
    make drivers/net-r - build all targets in drivers/net, with recursion
    make drivers/net/eepro100.i - pre-process eepro100.c and save as .i
    make drivers/net/eepro100.s - compile eepro100.c and save as .s

  The .i and .s targets are useful for debugging.  The output is
  automatically generated using the same flags as the corresponding .o file,
  if the .o file is not selected then the .i and .s files are generated using
  kernel flags.


WHY HAVE SHADOW TREES?

  A few people have asked why kbuild 2.5 supports shadow trees.  This is a
  reasonable question, given the extra code and complexity required to
  support them.  Why not just use Jeff Garzik's patch for supporting third
  party drivers?

  If kbuild only had to support add on, free-standing third party code then
  Jeff's patch would do the job.  But some people have a larger problem,
  their code replaces part of the existing kernel.  A short list:

  kdb
     Mostly free standing but it updates ~ 18 existing kernel files, and that
     is not counting the vmlinux.lds.S changes in each architecture.

  xfs
     Almost all free standing but it updates ~ 10 existing kernel files.

  Donald Becker's drivers.
     Every one replaces existing kernel code.  It is not just Donald's
     drivers that have this problem, every new version of an existing driver
     falls into this category.  Copying the entire kernel just to patch a
     couple of files is unsatisfactory.

  Architecture dependent code.
     Most architectures have additional and replacement code that has not
     been merged into the main tree yet.  In many cases, if these patches are
     applied to the base source tree then the source will not compile for
     other architectures.

  The aim of shadow trees is to keep a pristine, Linus blessed source tree.
  The extra code shadows the base tree, using multiple layers if that is what
  you need.  I want to be able to compile

    i386 from 2.4.x base
    ia64 from 2.4.x base + ia64 shadow tree
    i386 from 2.4.x base + kdb shadow tree
    ia64 from 2.4.x base + ia64 shadow tree + kdb shadow tree

  Repeat for alpha, sparc etc.  Add xfs, jfs, ext3 etc. over the above
  architectures.  When 2.4.y comes out, replace the base tree, make any
  changes required in the shadow files to match 2.4.y and compile again.

  Shadow trees support people developing or using large and relatively
  independent update sets.  Without shadow tree support you are doomed to a
  separate source tree for every combination.  That duplicates 120Mb of
  source which is bad enough.  But the real problem comes when you make a
  change in one of the patch sets and then have to extract and duplicate that
  change to every other source tree.  It gets even worse when you change the
  base kernel version, you have to extract all the changes from each
  duplicated source tree, build new trees based on the new base and try to
  apply the changes from the previous version.

  Shadow trees do not completely remove these problems but they do remove the
  need to reproduce changes in multiple separate trees.  It also means that
  upgrading to a new base kernel requires one set of changes for each shadow
  tree, instead of for each combination that you are supporting.

  Reviewing the kbuild 2.5 code, almost all of the complexity is to handle
  the ability to have separate source and object directories.  Going from one
  directory to two was hard, it required finding and correcting all the
  assumptions that files were in a single tree, which was not true for any
  generated files.  Once those problems were fixed, going from two to many
  was relatively easy.


GLOBAL MAKEFILE

  One big change in kbuild 2.5 is the use of a global Makefile.  This removes
  all the special case code for inter-directory dependencies and
  significantly speeds up parallel make.  It is also much easier to debug
  kbuild problems when you have a global Makefile containing all the rules.

  To get a global Makefile, kbuild 2.5 scans the source trees looking for
  files called Makefile.in.  All Makefile.in files are copied and
  pre-processed to create the final global Makefile.  Makefile.in files can
  contain make commands but most of them contain kbuild declarations, see
  below.  You say what you want kbuild to do and let kbuild generate the
  required make commands automatically.  This hides the internal complexity
  of kbuild from most kernel developers who can then concentrate on compiling
  their code instead of fighting with the makefiles.

  Ignoring the time it takes to compile the kbuild programs (they are only
  compiled once per object tree), the time to scan the source tree and
  generate the global Makefile is 1-2% of the time it takes to do a kernel
  compile.  Once the global Makefile is built, the compile is faster than
  kbuild 2.4, especially since make dep is no longer required.  Overall
  kbuild 2.5 with a global makefile runs about 9% faster than kbuild 2.4.  In
  addition it is easier to use, it is much more accurate and gives better
  parallelism.


NO_MAKEFILE_GEN (FAST BUILD MODE, ONLY FOR EXPERTS)

  The extra time required to build the global Makefile is only a problem when
  you are developing code, then the time required to generate the makefile
  can be longer than the time required to compile just one object.  If you
  are in a change, compile and test cycle you can
    make NO_MAKEFILE_GEN=anything
  to reuse the existing global makefile.  Setting NO_MAKEFILE_GEN to any
  value (including 0) bypasses the makefile generation, "make
  NO_MAKEFILE_GEN=0" does not do what you probably expect.

  There are differences between the makefile processing for normal and
  NO_MAKEFILE_GEN mode.  When you switch from normal mode to NO_MAKEFILE_GEN
  mode, the first make command has to take a few seconds to modify the
  makefile environment, you get message "Preparing makefile environment for
  NO_MAKEFILE_GEN mode".  This occurs once for each time that you switch
  modes.


  WARNING:

    The result of using NO_MAKEFILE_GEN may not be correct.  When you bypass
    the makefile generation it means that any of your changes that alter the
    kernel's dependencies will not be noted.  Only use NO_MAKEFILE_GEN when
    you are sure that you are not adding new files, that you are not changing
    config, that you are not adding new inter-file or inter-directory
    dependencies, that you are not changing any Makefile.in files etc.

  Also note that NO_MAKEFILE_GEN does not work well for targets which are
  split over multiple directories.  When the makefile generation is bypassed,
  the full dependency checking is not available.  Instead you get all the
  explicit dependencies plus implicit dependencies for just the targets you
  are working on.  Using NO_MAKEFILE_GEN for anything except a single low
  level target is not safe.

  About the only time it is safe to reuse the existing global makefile is
  when you are changing existing .c or .h files and you explicitly make a low
  level target where all the required sources are in the same directory.
  Even then you must not add or delete #include lines and you must not add a
  reference to a CONFIG_xxx variable that was not previously used in that
  file.  In other words, if you change the file's dependencies on other files
  or on the config you must regenerate the global makefile.  If you change a
  file which affects a target in another directory then that target may not
  be rebuilt.  If in doubt, be safe and let kbuild regenerate the global
  makefile.

  When NO_MAKEFILE_GEN is specified, pp_makefile4 is not run so targets which
  are out of date still exist.  The global makefile has explicit dependencies
  for targets and checks for command differences, it does not contain
  implicit dependencies.  In an ideal world I would just append the implicit
  dependencies to the global makefile and let make handle the dependency
  graph.  Alas the storage requirements when make is given all the
  dependencies are excessive, make with the full dependency tree ran for over
  20 minutes on a 16Mb machine without doing anything useful.

  When the makefile is generated, pp_makefile4 does all the implicit
  dependencies in a few seconds.  Even on a 16Mb machine, pp_makefile4
  handles all the implicit dependencies for the entire kernel in under 30
  seconds.  Specifying NO_MAKEFILE_GEN prevents pp_makefile4 from running.
  In order to detect as much of the implicit dependencies as possible without
  overloading small machines, the top level makefile identifies the directory
  you are working on (from the explicit target) and includes the implicit
  data for just that directory.  This means that NO_MAKEFILE_GEN may not
  rebuild targets in other directories, even if they are affected by your
  source change.

  After using NO_MAKEFILE_GEN, you must do a final kbuild without
  NO_MAKEFILE_GEN before you install the result.  Installing a kernel or
  modules that were built with NO_MAKEFILE_GEN is not safe.  However some
  people believe that they know if the build is complete or not and they want
  to force the install.  Those brave (or foolhardy) people can force an
  install after NO_MAKEFILE_GEN by using the option below on the make command
  line.  Do not complain if your kernel or modules fail after using this
  flag.

   I_KNOW_THAT_THIS_BUILD_MAY_BE_INCOMPLETE_BUT_I_WANT_TO_INSTALL_IT_ANYWAY=1

  If you want to specify debugging targets on the make command line, such as
  foo.i or bar.s, then you cannot use NO_MAKEFILE_GEN.  Rules for debugging
  targets are only generated when the full makefile processing is done.

  Bug reports against kbuild when you used NO_MAKEFILE_GEN will be ignored.


MAKEFILE.IN SYNTAX

  The Makefile.in fragments can contain normal make rules, there are still
  some cases where they are necessary.  However the bulk of the Makefile.in
  files are statements in a declarative mini-language.  The pre-processing
  code converts these statements and macros into standard make rules.  The
  pre-processor recognizes several commands plus some new make style macros.
  The commands are all of the format

    command(parameters)

  A command can be split over multiple lines.  The trailing '\' on continued
  lines is optional for the pre-processor commands.  You can use a trailing
  '\' on continued lines if you like but I recommend against it, the text is
  more readable without it.  The additional make style macros cannot be split
  over multiple lines, with or without a trailing '\'.

  Because the mini-language is converted to make rules before make sees the
  global makefile, you cannot use make statements to control bits of the a
  command.  This does not work:

    command(...
    ifeq ($(CONFIG_foo),y)
            ...
    endif
            ...)

  But it is legal to do this, with complete commands being controlled by make
  statements.  The pre-processor expands the commands into normal make rules
  then make decides which set of rules to execute.

    ifsel(CONFIG_foo)
      command(...)
    else
      command(...)
    endif

  Many of the commands take object names.  Unless otherwise specified, these
  names are relative to the directory that contains the Makefile.in file.  So
  the line "select(process.o)" in arch/i386/kernel/Makefile.in is a shorthand
  form that really refers to arch/i386/kernel/process.o.  Objects are
  automatically created in the relevant directory of the object tree, which
  can be the same as the source tree.  To refer to an object below the
  current directory, use a relative name like directory/object.o.  To refer
  to an object somewhere else in the tree, use a full path name from the root
  of the object tree, prefixed by '/'.  For example, /lib/lib.a refers to
  lib/lib.a under the object tree root.  Do not use '/../' in object names,
  it does not do what you expect with shadow trees.


  Makefile.in commands

    objlink(optional_CONFIG_list target_object sub_object_list)
        The target_object (.o) or archive (.a) is built up from the listed
        sub_objects.

        You can have multiple objlink statements for the same target_object,
        the list of sub_objects is cumulative for each target.  The
        sub_objects are linked into the target_object in the order they are
        specified in Makefile.in.  The target_object must be a local name,
        containing no '/'.  The sub_objects can be local, they can be in
        lower directories or elsewhere in the object tree.

        If a config list is present at the start of objlink() then all the
        config options must be satisfied before the sub_object_list is added
        to the target_object.  A normal config option must be set to 'y' or
        'm' in order for the entire list to be satisfied.  A negated config
        option (preceded by '!') must be set to 'n' or empty to satisfy the
        list.

        The type of config in optional_CONFIG_list does not affect the way
        that the sub_objects are compiled, it only determines if the
        sub_objects are linked into the target_object.  The select() command
        that refers to the target_object controls how all the sub_objects
        linked into that target are to be compiled.

        Since objlink defines _how_ a target_object is to be built but not
        _if_ it is to be built, these statements must not be subject to make
        'if' statements.  You get a cleaner Makefile.in if you always define
        the structure then rely on select(target_object) to say what is to be
        built.  kbuild 2.5 requires that all objlink statements be executed
        so kbuild can identify conglomerates which have no source, objlink()
        wrapped in 'if' statments will cause 'cannot find source' messages,
        don't do that.

        Example:

        objlink(unix.o af_unix.o garbage.o)
        objlink(CONFIG_SYSCTL unix.o sysctl_net_unix.o)

          unix.o is linked from af_unix.o and garbage.o.  If CONFIG_SYSCTL is
          selected (either 'y' or 'm') then sysctl_net_unix.o is appended to
          the link list for unix.o.

        objlink(!CONFIG_XFS_GRIO linux_xfs.o xfs_griostubs.o)

          If CONFIG_XFS_GRIO is not selected then link xfs_griostubs.o into
          linux_xfs.o.

        objlink(CONFIG_XFS_RT  xfs.o xfs_rtalloc.o xfs_rtbit.o)
        objlink(!CONFIG_XFS_RT xfs.o xfsrtstubs.o)

          If CONFIG_XFS_RT is set then link xfs_rtalloc.o and xfs_rtbit.o
          into xfs.o.  Otherwise link xfsrtstubs.o into xfs.o.

    expsyms(object_list)
        These objects export symbols.

    select(optional_CONFIG_list object_list)
        Process the objects depending on the value of the CONFIG list.  If
        the config_list is omitted then always compile the objects and link
        them into vmlinux.

        If the config_list is present then the object_list is only compiled
        if _all_ of the entries in the CONFIG list are satisfied.  Every
        normal config option in the list must be set to 'y' or 'm'.  Every
        negated config option (preceded by '!') must be 'n' or blank.

        The first config in the list determines how the objects are compiled,
        as modules (first config is set to 'm') or compiled and linked into
        vmlinux (first config is set to 'y').  The first config determines
        the object type, the second and subsequent configs only control if
        the objects are built, not how they are built.  If the first config
        is negated then it can only select the object list as built in, there
        is no way to use a negated first config to select as modules.

        If any config option in the list is not satisfied then the objects
        are not selected.  This does not prevent another command from
        selecting the objects.  An object can appear in several select()
        commands, if any are selected then the object is built.  If an object
        is selected as both 'y' and 'm' then 'y' take precedence.  You will
        get a warning if this results in a sub object being compiled for
        vmlinux and also linked into a module.

        The select() command should always refer to single unit objects or to
        the target_object of objlink, do not select any sub objects of a
        target, it is ambiguous.  When you select() an object which is made
        up of sub objects, the first config (if any) on the select() controls
        how all the sub objects are compiled.

        Examples:

        select(ll_rw_blk.o blkpg.o genhd.o elevator.o)

          The four objects are always compiled and linked into vmlinux.

        select(CONFIG_UNIX unix.o)

          unix.o is built if CONFIG_UNIX is selected.  If CONFIG_UNIX is 'm'
          then unix.o is a module, if CONFIG_UNIX is 'y' then unix.o is built
          into vmlinux.  Since unix.o is made up of sub objects, as defined
          by objlink() statements, the value of CONFIG_UNIX is used to build
          all the sub objects.

        select(CONFIG_M CONFIG_KDB CONFIG_ACPI kdbm_acpi.o)

          Compiles kdbm_acpi.o if both CONFIG_KDB and CONFIG_ACPI are true.
          kdbm_acpi.o is a module if the new kernel supports modules,
          otherwise kdbm_acpi.o is built into vmlinux.  CONFIG_M is a
          generated config value.  It is 'm' if the build supports modules,
          otherwise it is 'y'.  Use CONFIG_M if you prefer to build as a
          module with a fallback to building into vmlinux.

        select(CONFIG_M CONFIG_MODULES CONFIG_KDB CONFIG_ACPI kdbm_acpi.o)

          Unlike the previous command, kdbm_acpi.o can only be built as a
          module.  If the new kernel does not support modules then
          CONFIG_MODULES is false so the entire selection list is false, the
          object does not fallback to building into vmlinux.

          Which version is correct depends on the code.  Some code must
          always be a module, other code prefers to be a module but linking
          into vmlinux is acceptable.

        select(CONFIG_Y CONFIG_FOO object.o)

          CONFIG_Y is a generated config value, it is always 'y'.  The only
          use for CONFIG_Y is when the objects must be part of the kernel,
          even if the other configs are set to 'm'.  Some subsystems require
          some support code to be part of the kernel, even if the bulk of the
          subsystem is in a module.  Use CONFIG_Y for the kernel support
          code.

        select(CONFIG_PCI  CONFIG_VISWS pci-visws.o)
        select(CONFIG_PCI !CONFIG_VISWS pci-pc.o pci-irq.o)

          If PCI and VISWS are selected then compile pci-visws.o.  If PCI is
          selected and VISWS is not selected then compile pci-pc.o and
          pci-irq.o.  If you are not comfortable with this shorthand, you can
          get the same effect using ifsel(), else and endif, it just takes 5
          lines instead of 2.

    select_elsewhere(optional_CONFIG_list object_list)
        A kludge to work around a deficency in CML1.  Unlike select() which
        only allows you to select objects in the current directory,
        select_elsewhere() can select objects in other directories.  Each
        entry in the object_list must start with '/'.

        Do not use select_elsewhere(), it will be removed as soon as the CML1
        problem is overcome.  select_elsewhere() breaks the kbuild design
        that all data for an object should be in the same directory as the
        object.  The only reason that select_elsewhere() exists is to
        simplify the maintenance of fs, net and usb drivers, some of which
        need to select /lib/crc32.o.  From a maintenance viewpoint, it is
        better to have the crc32 requirement in the file that selects the
        driver.

    extra_aflags(object flags)
    extra_aflags_all(flags)
    extra_cflags(object flags)
    extra_cflags_all(flags)
    extra_ldflags(object flags)
    extra_ldflags_all(flags)
        Apply the extra flags to the compile of the specified object or to
        the compile of all objects in the current object directory.  There
        are no extra_arflags or extra_arflags_all commands, use ldflags
        instead.  Note that the *_all variants apply to all objects in the
        current directory, be careful if some of the objects are compiled for
        the host and some for the target.

        If the first word of flags is STRIP (in upper case) then the rest of
        the flags are stripped from the values of HOSTCFLAGS, CFLAGS,
        CFLAGS_KERNEL, CFLAGS_MODULE for C code, and from the corresponding
        global A and LDFLAGS for Assembler and linking.  Stripping only
        affects the global flag settings, not the per directory nor per file
        flags.  The main use of STRIP is to remove the -pg flags from the
        code that supports mcount processing in kernel debuggers, to prevent
        that code going recursive.  For example, kdb uses

          extra_cflags_all(STRIP -pg)

        If multiple flags are specified after STRIP, each is treated as a
        separate entry to be stripped.  That is,

          extra_cflags_all(STRIP -a -b -c)
        
        is equivalent to

          extra_cflags_all(STRIP -a)
          extra_cflags_all(STRIP -b)
          extra_cflags_all(STRIP -c)

    ifsel(CONFIG_name)
    ifnsel(CONFIG_name)
    ifselmod(CONFIG_name)
    ifselnmod(CONFIG_name)
        Expand into 'if' statements to test if the config option is selected
        ('y' or 'm'), not selected ('n' or blank), selected as a module
        ('m'), selected but not as a module ('y').  Used when the makefile
        needs unusual control over objects, needs a matching endif.

    link_subdirs(directory_list)
        vmlinux is linked from the objects selected as 'y' in this directory
        plus objects selected as 'y' in the sub directories specified by
        link_subdirs.  All in the order that they are defined.

        To link from a sub directory of the current object directory, use
        link_subdirs(subdir).  To link from a directory outside the current
        object directory, use link_subdirs(/path/to/dir), note the leading
        '/' to distinguish this from the sub directory case.  Avoid linking
        directories in other branches of the object tree, you are hard coding
        global knowledge in a local Makefile.  However this is sometimes
        necessary.

        link_subdirs() is required for the default base target (vmlinux) and
        for any user specified base targets such as boot loaders.  You do not
        need link_subdirs() for objects compiled for the current host.

    user_command(target (file dependencies) (command) (config dependencies))
        Build the target using the specified command.  Record enough
        information to rebuild the target if the command or config
        dependencies change.  At the moment it does not check time stamps on
        the file dependencies, leaving them to make.  This may change in a
        later release of kbuild.

        The config dependencies are not used in the command unless you
        include them in the command text, they are present to detect changes
        that cannot be detected in any other way.  To remove ambiguity with
        blank configs, the config dependencies should use a separator other
        than white space, e.g.  $CONFIG_foo:$CONFIG_bar.

        The target is always in the object tree, do not specify $(objfile
        target), just target.  The file dependencies can come from anywhere
        so you need to tell the pre-processor whether these files are in the
        source or object trees, i.e. they must use $(objfile) or $(srcfile).

        If the command contains $@, $< or $^ or any of the $(xD) or $(xF)
        variants then these macros are expanded by the pre-processor.  This
        only applies to user_command because it is the only command where all
        of the information is available to the pre-processor, also it is the
        only command where this expansion is required at pre-processor time,
        to build the new command string.

        Note: Be careful when using $@, $< or $^ and the command line
              contains a 'cd' command.  The target and file dependencies are
              based on the top level object directory, when you use 'cd'
              those names are no longer valid.  drivers/pci/Makefile.in has

              user_command(devlist.h
                      ($(srcfile pci.ids) $(objfile gen-devlist))
                      ((cd $(objdir) && ./gen-devlist) < $<)
                      ()
                      )

              Because it uses 'cd' and '$<', it uses a subshell so $< is not
              affected by the change of directory.

        The expansion of the command uses --command='...' so the user command
        must not contain ' characters, use " instead.  You can use ' if you
        follow the shell quoting rules, this will work (but is ugly):
          (program '"'quoted string'"' the rest)
        which expands into
          --command='program '"'quoted string'"' the rest'

        The command can be multi line, trailing '\' is not required.  If
        there is more than one shell command, each one must have a trailing
        ';'.  If possible, use 'set -e;' at the start of multiple commands,
        this assumes that none of the commands are expected to fail.

        The file and config dependency lists can be empty.  The command and
        target cannot be empty.

        user_command() adds the target to the CLEAN list, there is no need to
        manually clean up these targets.

        Beware of commands that contain pipelines.  The shell only checks the
        return code of the last command in the pipeline, even if set -e is
        specified.  If an earlier command in the pipeline fails, the overall
        return code will not reflect the failure and make will incorrectly
        think that the command has worked.  For example,

          set -e
          loadkeys --mktable $(srcfile defkeymap.map) | \
            sed -e "s/^static *//" > $@

        will not detect failures in loadkeys and will create an empty output
        file.  If there is any chance that a pipelined command can fail then
        do not use a pipeline, use separate commands and temporary files to
        ensure that all error conditions are detected.

          set -e
          loadkeys --mktable $(srcfile defkeymap.map) > $(tmpfile)
          sed -e "s/^static *//" $(tmpfile) > $@

    nodepend(target_list)
        The targets do not have associated .d files.  This means that kbuild
        cannot verify if the files are up to date, you have to rely on
        time stamps.  All filenames starting with '.' are automatically
        treated as nodepend.  The targets are assumed to be in the object
        tree.

    create_objdir(optional_CONFIG_list)
        Object directories are automatically created when any targets are
        selected in that directory.  Some directories contain only host code
        where select() cannot be used, e.g. Documentation/DocBook,
        net/802/pseudo, drivers/scsi/aic7xxx/aicasm.  The corresponding
        object directories need to be created, either unconditionally or
        based on config options.

        create_objdir() with no parameters unconditionally creates the
        corresponding object directory.  This should only be used when you
        cannot tell when the host commands will be executed, typically used
        for manually selected targets like DocBook.

        create_objdir(CONFIG_list) will create the object directory if all of
        the config list are selected, i.e. all are set to 'y' or 'm'.  This
        should be the normal use of create_objdir().

    installable(optional_CONFIG_list filename_list)
        If all of the config entries are selected then add the filenames to
        the target list for 'make installable'.  It also ensures that the
        current object directory is created, based on the optional config
        list.

        Example:

        installable(CONFIG_BZIMAGE bzImage)

          is exactly equivalent to:

          create_objdir(CONFIG_BZIMAGE)
          ifsel(CONFIG_BZIMAGE)
            installable: $(objfile bzImage)
          endif

        installable(loader1 loader2)

          is exactly equivalent to:

          create_objdir()
          installable: $(objfile loader1)
          installable: $(objfile loader2)

    side_effect(target1 target2)
        Target 1 is created as a side effect of creating target 2, normally
        target2 is created by a user_command().  Side effects need to be
        documented as well as primary effects.  It expands into the
        equivalent of
          $(objfile target1): $(objfile target2)
                @/bin/true
          nodepend(target1)
          CLEAN += $(objfile target1)

    shipped(prefix (target_list) (source_list) (commands) (CONFIG_list))
        See 'Shipping Generated Files' files below.

    issrcfile(target_list)
        Some target files are incorrectly shipped in the kernel tarball.
        This is bad practice, the shipped files are overwritten at run time,
        make mrproper cannot be relied upon to get a clean system.  Eventually
        all such files will be converted to use shipped() commands, but until
        then the targets must be marked as issrcfile().  This command will be
        removed after all files are being correctly shipped.

    base_target(label)
        Normally the select() and link_subdirs() commands apply to vmlinux.
        However you are not restricted to building vmlinux, you can use the
        kbuild features to build other kernel related code such as a boot
        loader.  base_target(label) applies to the following select() and
        link_subdirs() statements, until the next base_target() or the end of
        the current Makefile.in.

        The label does not define a target, it is just a common identifier
        for the target being built.  If any Makefile.in line contains the
        word $(__pp_<label>_objects) or $(__pp_<label>_modules) then kbuild
        replaces that word and the rest of the line with the list of objects
        or modules for the specified label.  It also creates files
        .tmp_<label>_objects_new and .tmp_<label>_modules_new containing the
        same list.  The objects list is in the form of a linker script, the
        modules list is one module per line.

        The label must be globally unique, i.e. you cannot use the same base
        target label in two makefiles unless they refer to the same target.
        base_target(host) is reserved, it cannot be used in any makefile.
        base_target(vmlinux) is semi-reserved, it can be specified in any
        makefile but it always refers to the top level vmlinux.

        Each base_target() has its own independent list of selections and
        subdirectories to link.  If an object is linked into multiple base
        targets (e.g. an object that is used in vmlinux and in a boot loader)
        then you need two select() and two link_subdirs() statements.  For
        example

          select(foo.o)    # no base_target, selected for vmlinux
          base_target(boot_loader)
          select(foo.o)    # selected for boot_loader target

        The directory containing foo.o must appear in two link_subdirs()
        statements, once for vmlinux (the default base target) and once after
        base_target(boot_loader).  The directory link orders for vmlinux and
        boot_loader do not have to be the same.

        For each base_target there is a root directory, where the link order
        starts.  The root directory is the first directory (in breadth search
        order) that mentions the base target.  For vmlinux this is always the
        top level directory.

        Defaulting the link order root to the first use (in breadth search
        order) of the base works for most base targets where the target is
        built from a parent and several child directories or from a single
        directory.  If you have an awkward case where a base target is built
        from multiple directories and the root of the link tree is not the
        first directory (in breadth search order) then you need to add a
        dummy entry higher up the directory tree to override the default root
        entry.

        For example, superh has a boot loader in arch/sh/boot/compressed which
        includes arch/sh/kernel/sh_bios, the object that needs to be linked is
        at a higher level.  In this case the default link root algorithm is
        wrong.  Adding

          base_target(boot_loader)
          link_subdirs(boot)

        to arch/sh/Makefile.in makes arch/sh a dummy link root for the boot
        loader and caters for the out of tree order linkage requirements for
        this boot loader.  The dummy link_subdirs() in arch/sh does not
        require that the base target be linked in arch/sh, the select()
        statements control what is built and where it is built, the
        user_command() statement in arch/sh/boot/compressed does the actual
        link of the boot loader.

    update_if_changed(target optional_new_target)
        If the new_target is newer than target and they are not identical
        then replace the contents of target with the contents of new_target.
        This command is normally used for text files generated by
        user_command(), the new_target is generated but only replaces target
        if anything has changed.  The new_target parameter can be omitted, it
        defaults to the target name prefixed with 'tmp_' (not '.tmp_').

        Obviously there must be another command that generates new_target.
        Do not use a new_target name that starts with '.', dot files are
        special cases in kbuild and will not do what you expect.  The target
        is automatically marked as nodepend(), the only thing it depends on
        is the new_target, there is no need for other dependency data.

        update_if_changed() is a micro optimization, resist the temptation to
        use it in too many places.  Only use it when a significant number of
        files are affected by a change to the target, so the saving in
        reduced compilation is worth the less readable code in the makefile.

    uses_asm_offsets(object_list)
        Assembler files that include asm-offsets.h require extra make rules
        to ensure that asm-offsets.h is generated first and the include path
        is valid.  uses_asm_offsets() defines the objects that need the extra
        rules, the source still requires #include "asm-offsets.h".

        Example:

        uses_asm_offsets(entry.o)

          is exactly equivalent to:

          extra_aflags(entry.o $(obj_includelist /arch/$(ARCH)))
          $(objfile entry.o): $(objfile /arch/$(ARCH)/asm-offsets.h)

    hostcc(object_list)
        Compile the objects to run on the host system.  It uses HOSTCC, the
        standard include list, HOSTCFLAGS plus any extra flags for the
        target.  Each entry in the object_list is compiled separately.

        Objects compiled for the host do not require link_subdirs(), instead
        the hostld() command defines the link order.

    hostld(binary object_list)
        Link the objects into the binary.  It uses HOSTLD, the standard
        include list, HOSTLDFLAGS plus any extra flags for the target.

    hostccld(binary object_list)
        This is exactly equivalent to
          hostcc(object_list)
          hostld(binary object_list)

        Unlike a single compile and link step, the intermediate objects are
        built and retained.  This is required to get the full dependency
        list, gcc creates an incomplete dependency list when compiling from
        multiple sources in a single step.

    targetcc(object_list)
        To Be Done.
        Compile the objects as normal user space programs but they will be
        linked into the kernel.  This is primarly (or only) used by UML.  The
        programs are compiled using CC (compiler for the target archietcture)
        and use the standard include list for CC.  They may not include any
        kernel headers.  Each entry in the object_list is compiled
        separately.

        Objects compiled with targetcc are treated as kernel objects and are
        subject to select(), objlink() and link_subdirs() commands.

    setup(target)
        Generated files must be created before the objects that depend on
        them can be built.  In an ideal world, the usage of generated files
        would be well defined and kbuild would contain explicit dependencies
        from the downstream objects on the generated files to ensure that the
        generated files are built first.

        Alas, kbuild is not an ideal world, some generated files are used all
        over the place, typically in .h files where the usage is not well
        defined.  To handle this case, use setup(target), the target will be
        built before anything else.  The setup() command must precede the
        command that creates the target.  Everything that a setup target
        depends on must also be defined as setup().  Failure to follow these
        rules will result in circular dependencies.

        NOTE: Use of setup() is almost always a sign of bad design and/or
              lazy coding.  If at all possible, code explicit dependencies on
              generated files.  setup() targets tend to cause more
              compilations than actually required, because they pollute the
              dependency tree.  The kbuild group will be very particular
              about allowing setup() rules into the system.


  Makefile.in macros

    The Makefile.in pre-processor defines some new macros.

    $(objdir)
        The name of the current object directory, relative to the root of the
        object tree.  Do not use $(CURRDIR), it does not work with separate
        source and object trees.  $(objdir) should only be used in "cd"
        commands and when you want to construct an object name from the
        current directory name.  Do not use $(objdir) to refer to object
        files, use $(objfile) instead.

    $(objfile filename)
        Expands into the relative path to the filename in the object
        directory.  It also defines to the pre-processor that this is a
        generated file.  The filename does not have to be an object or
        archive name, it can be a generated source file or header.  It is
        valid to read objects from other directories.  Writing to other
        directories is strongly discouraged, each object directory should be
        as self contained and as close to the source structure as possible.

        To access a file in the current object directory, use $(objfile
        filename).  To access a file in a sub directory of the current object
        directory, use $(objfile subdir/filename).  To access a file outside
        the current object directory, use $(objfile /path/to/filename), note
        the leading '/' to distinguish this from the sub directory case.
        Avoid using files in other branches of the object tree, you are hard
        coding global knowledge in a local Makefile.  However this is
        sometimes necessary.

    $(srcfile filename)
        Expands into the absolute path to the filename in the source
        directory, taking into account any shadow versions of the file.
        Because of shadow trees, you cannot assume that references to two
        source files in the same Makefile.in will be prefixed with the same
        root directory name.

        To access a file in the current source directory, use $(srcfile
        filename).  To access a file in a sub directory of the current source
        directory, use $(srcfile subdir/filename).  To access a file outside
        the current source directory, use $(srcfile /path/to/filename), note
        the leading '/' to distinguish this from the sub directory case.
        Avoid using files in other branches of the source tree, you are hard
        coding global knowledge in a local Makefile.  However this is
        sometimes necessary.

    $(srcfile_base filename)
        Expands into the absolute path to the filename in the base source
        directory, ignoring any shadow versions of the file.  If you want to
        use make implicit rules containing '%' then you must use
        srcfile_base, the file expansion for '%' assumes a fixed mapping from
        source to object directories and cannot cope with shadow trees.
        Avoid using '%'.

    $(src_includelist directory_name)
        Expands into one '-I source_directory_name' for each source tree,
        from the top shadow tree down to the base.  Normally used in
        extra_[ac]flags.

    $(obj_includelist directory_name)
        Expands into '-I object_directory_name'.  Normally used in
        extra_[ac]flags, when including generated files.

    $(c_to_o)
        Expands into one .o filename for each .c filename in the current
        source directory, including sources in shadow trees.  It is the
        equivalent of $(patsubst %.c,%.o,$(wildcard *.c)) except that it
        handles multiple input directories, which wildcard *c does not.

    $(tmpfile optional_suffix)
        Shorthand for $(objfile .tmp_file_$(notdir $@)optional_suffix), to
        generate a target specific temporary file name.  All .tmp_file_*
        files are automatically removed, they do not need to be added to the
        clean list.

    Besides the new macros above, the pre-processor also handles the existing
    $(dir) and $(notdir) macros, when the filename is plain text or can be
    expanded to plain text by the pre-processor.  To create a filename based
    on the current directory use '$(notdir $(objdir))', this name is usually
    modified further then passed to $(objfile).


PRE-PROCESSOR PROGRAMS

  There are four makefile pre-processor programs which live in the base
  source tree, in the scripts directory.  Creating the global makefile takes
  four phases.  Compiling the kernel is the fifth phase.

    pp_makefile1 - Phase 1 processing.
        Scan the source and object trees, extracting all the filenames,
        recording their location and timestamps.
        Perform .prepend and .append processing.

    pp_makefile2 - Phase 2 processing.  
        All the Makefile.in files are copied to a temporary file.
        The temporary file is read and the pre-processor commands and macros
        are expanded into make rules.

    In phase 3, the output from phase 2 is fed through make to perform all
    the variable assignments and conditional evaluation.  It was easier to
    use make and reuse the existing code base and concepts, instead of
    inventing yet another language.  Phase 3 does not compile anything,
    instead make is tricked into writing out the results of the conditional
    expansions, giving a list of which kernel objects are to be compiled and
    how they are to be compiled.

    pp_makefile4 - Phase 4 processing.
        Using the temporary file from phase 2 plus the evaluated conditionals
        from phase 3, generate the global makefile with rules for all the
        objects that were selected.

        Phase 4 processing detects time stamp differences between input and
        output files and forces a rebuild of the dependent outputs if the
        input time stamp has changed.  This is not the normal "input is newer
        than output" check, _any_ change to an input file time stamp will
        force a rebuild of all outputs that depend on it.

        The presence of shadow trees means that you can copy a file from the
        base tree to a shadow tree, edit, build, decide you made a mistake,
        delete the shadow copy and rebuild.  Deleting the shadow copy exposes
        the original file which has an older time stamp than the output, but
        you must rebuild to keep the targets and sources in sync.  As a
        bonus, checking for any time stamp change detects time stamp
        reversion when you check a file out of a source repository, it also
        detects if you have clock skew between two systems connected via NFS.

    In phase 5, make reads the global makefile and runs the commands that are
    required to bring the kernel up to date.  This is standard make
    processing, using the commands generated by phase 4, including force
    build where necessary.

    pp_makefile5 - Control each command in phase 5.
        All the generated commands run using pp_makefile5, it forks and runs
        other commands internally, depending on the type of the target being
        built.

        The main reason for using pp_makefile5 is to detect whether the build
        commands succeed or fail.  If they succeed then the dependency
        information for the target is reformatted to contain time stamp data
        and to avoid absolute filenames, the latter allows a source or object
        tree to be renamed without forcing a complete rebuild.  If the build
        command failed then the dependency information is marked as a
        failure.

        For success, pp_makefile5 writes the command to the dependency file.
        For each source file that the target depends on, pp_makefile5 reads
        the source and extracts all the config variables that it depends on.
        All the dependency data is used in the feedback loop for the next
        kbuild.

        The processing above is equivalent to the old 'make dep', except that
        it is now done at the correct point in the kbuild cycle and does not
        rely on human intervention to detect new dependencies after the
        source has changed.

  Rerunning kbuild.

    After the kernel has been built and you decide to rerun kbuild, it is
    critical that kbuild checks all the files and config settings that each
    target depends upon to see if they have changed.  During each step of
    phase 5, pp_makefile5 records dependency information for each target and
    config dependencies for each source or include file used by the target.
    This information is held in the kbuild database.

    As part of the input to phase 4 of the next kbuild, the dependency
    information is used to detect changes, any change will force a rebuild of
    the affected targets.  This includes changes to time stamps (forward or
    backward), changes to config settings, or changes to the command.  The
    command check includes the program used, the flags and the list of input
    files.

    This check also applies to user supplied commands in user_command(),
    however any user commands not using user_command() are not checked.  Also
    user_command() does not check time stamps on anything except the target,
    in particular it assumes that dependency time stamps do not go backwards.
    This may be changed in a later release of kbuild.

    If there is no dependency data for a target then that target is removed
    and rebuilt.  If there is no config dependency data for an input file
    then everything which depends on that input file is rebuilt.  If any
    input file listed in a dependency has a different time stamp or is at a
    different level in the shadow trees then every target which depends on
    that input is rebuilt.  If a target is marked as not up to date or there
    is no command line then the target is rebuilt.  If the target is newer
    than its last recorded timestamp then it has been changed outside kbuild
    and is unsafe, it is removed and rebuilt.

    Provided a target passes the checks above, its dependency list is
    expanded by adding all the input files it depends on plus all config
    settings that actually exist (see scripts/split-include).  No check is
    made on the time stamp of the config settings, they are always generated
    and do not have any problems with source time stamps going backwards.

    In addition to expanding the dependency list, pp_makefile4 tells make to
    check if the build command has changed, forcing a rebuild if it has.
    This is left to make because it requires expansion of all make variables
    used in the new commands.

    In this context, 'rebuilt' means that the target is always removed but it
    is only rebuilt if it is required for the current kernel.


SHIPPING GENERATED FILES

  In general it is bad practice to include generated files in the kernel
  source tree.  The only exceptions are when the generating code is not in
  the kernel or when the generating code is in the kernel but it requires
  additional tools which not all users have installed.  An example of a
  generated file without the code to regenerate it is firmware for a network
  driver.  An example of a generation process that requires extra tools is
  drivers/char/defkeymap.c which requires the loadkeys program.

  There is no justification for shipping any other generated file as part of
  the kernel.  This is especially true if the user is always expected to
  regenerate the file, even more so if the generated data depends upon the
  user's .config.  Under these circumstances it is dangerous to ship a
  generated file because it can be used when it does not reflect the user's
  kernel.

  When a generated file has no kernel support to regenerate it, the file can
  be shipped as is.  The question of whether including generated files in the
  kernel without the underlying code is a violation of the kernel license is
  outside the scope of this document.

  For generated files where the code is included but not all users can run
  it, you must be careful about when the generated file is rebuilt.  make
  looks at the time stamp of the generating and generated files to decide if
  the output needs to be regenerated.  This works for the person making the
  changes because they control when the files are updated.

  Time stamps do not work when the change is issued to the rest of the world
  as a diff.  After patch has run you cannot guarantee which of the updated
  files has the more recent time.  The patch program does not preserve time
  stamps (it must not) so the time stamps on the changed files depend on the
  order of the entries in the patch set.  There is no defined order for
  entries in a patch set, it depends on the program that generated the
  difference listing.  GNU diff generates patches in alphabetical order but
  only when it is given an entire directory.  When diff is invoked from a
  source repository tool it is typically called once for each file and the
  file order is controlled by the repository tool.  Even if your repository
  generates the patch in the correct order, that order can change when the
  patch is merged into the kernel.

  Since you cannot rely on time stamps to decide if a generated and shipped
  file needs to be regenerated, you must use another mechanism for this case.
  There are two basic possibilities, manual or automatic (otherwise known as
  lazy or correct).

  In the manual case you ignore changes to the generated or generating files
  until the user performs some manual operation, such as selecting
  CONFIG_REGENERATE_foo.  This is easy to implement but it is also the lazy
  approach, making the end user do extra work to save the maintainer doing
  anything.  This goes against the whole idea of *automatically* deciding
  what needs to be rebuilt, instead it relies on human intervention.

  In the automatic case the maintainer has to do more work but the make rules
  can automatically determine if the end user has changed any of the related
  files and regenerate automatically.  This is the correct approach.  In the
  absence of reliable time stamps you need another method to check if the
  generating and generated files are in sync or not.  The obvious method is a
  checksum of files.

  Given a generated file 'foo' and a script to generate it 'foo-gen' which
  not all users can run because they may not have the required software
  installed.

    foo_files := $(srcfile foo-gen) $(srcfile foo.out_shipped)
    $(objfile foo_sum.d): $(srcfile foo_sum) $(foo_files)
            $(KBUILD_QUIET)(set -e;
              mkdir -p $(objdir); \
              sed -e 's:$$[ABD-Z][^$$]*\$$::g' $(foo_files) > \
                $(objfile .tmp_foo_files); \
              ($(MD5SUM) -c $(srcfile foo_sum) >/dev/null 2>&1 && \
                echo S OK || echo F) > $@; \
              rm $(objfile .tmp_foo_files); \
            )

    user_command(foo.out
            ($(objfile foo_sum.d))
            ([ "`cat $<`" = "S OK" ] &&
              (cp -f $(srcfile $(notdir $@)_shipped) $@) ||
              (set -ex ; $(srcfile foo-gen) > $(objfile foo.out)))
            ()
            )

    # Exception: this writes to the source tree.  The target must be
    # explicitly requested.
    .PHONY: foo_sum_shipped
    foo_sum_shipped: $(objfile foo.out)
            @cmp -s $(objfile foo.out) $(srcfile foo.out_shipped) || \
                 mv -f $(objfile foo.out) $(srcfile foo.out_shipped)
            @( \
             set -e; \
             sed -e 's:$$[ABD-Z][^$$]*\$$::g' $(foo_files) > \
                $(objfile .tmp_foo_files); \
              $(MD5SUM) $(objfile .tmp_foo_files) > \
	        $(objfile .tmp_$(notdir $@)) && \
              cmp -s $(objfile .tmp_$(notdir $@)) $(srcfile foo_sum) || \
                (echo Updating checksum for foo; \
                 mv -f $(objfile .tmp_$(notdir $@)) $(srcfile foo_sum)); \
            )
            @rm -f $(objfile foo_sum.d) $(objfile .tmp_$(notdir $@)) \
              $(objfile .tmp_foo_files)

    ifsel(CONFIG_foo)
      all_sum_shipped: foo_sum_shipped
    endif

  That is boiler plate code which can be used for any shipped files, by
  globally replacing 'foo-gen' and 'foo'.  To initialize the sequence, touch
  $(srcfile foo_sum) and $(srcfile foo.out_shipped) then make
  foo_sum_shipped.  Thereafter any real change to the foo files will
  regenerate foo, ignoring any spurious time stamp differences caused by
  patch.  It removes all need for special configuration options, if anybody
  changes the input files then kbuild automatically rebuilds foo when it is
  used.  Users who do not change the input files get the shipped version when
  foo is required.

    foo_files       - List all the source files, including the generating
                      code and the shipped version of foo.  The list does not
                      include foo_sum.
    foo_sum         - Checksum over $(foo_files), i.e. the master copies.
                      The checksum ignores RCS id and date strings.
    foo_sum.d       - Built on the first make and when any of the input files
                      are updated after the first make.  foo_sum.d either
                      contains 'S OK' (sum is valid) or 'F' (failed).
    user_command    - Creates the working copy of foo, either from the
                      shipped copy (sum is valid) or by running foo-gen (sum
                      does not match, a real change has occurred).  Watch the
                      parenthesis in the user_command, in particular the use
                      of foo-gen requires () around the set of commands.
    foo_sum_shipped - Takes the latest version of foo, generating it if
                      necessary and writes it back to the source tree as
                      foo.out_shipped.  Generates a new checksum
                      automatically.  Note: This command must be manually
                      specified by the foo maintainer before shipping a new
                      version of foo.

  For a concrete example, see defkeymap.c in drivers/char/Makefile.in.

  Because this is boiler plate code, it has been automated.

    shipped(prefix
             (generated files)
             (generating files)
             (commands to create all the generated files)
             (CONFIG dependencies to select all_sum_shipped)
           )

  The first field is the prefix for variables and for _sum files.  It must be
  globally unique in the kbuild files.

  The generated files are bare names, without '/', without '_shipped', no
  $(objfile) or $(srcfile) is allowed, in fact no $(variables) are accepted.
  These names are used to create the user_command() and the 'cp' commands,
  one for each generated file.  Because user_command() only takes one target,
  all the other generated files are defined as side_effect()s of the last
  target, you must list the generated files in the order that they are
  created by your commands.

  The generating files are bare names and list the source files used to
  generate the targets.  For example, scripts, tables, lex or yacc code.

  The commands define how you create the target files if the shipped versions
  of the targets are no longer valid, i.e. the checksum has failed.  I
  recommend that the first command is 'set -ex;'.

  The config dependencies are zero or more configs to check.  If any are
  selected then all_sum_shipped is extended with foo_sum_shipped.

  The code above shrinks to these few lines.

    shipped(foo
             (foo.out)
             (foo-gen)
             (set -ex ; $(srcfile foo-gen) > $(objfile foo.out))
             (CONFIG_foo)
           )


CONVERTING OLD KBUILD MAKEFILES

  All of the architecture independent code has been converted to kbuild 2.5
  format.  The ix86 arch dependent code has also been converted.  These notes
  describe how to convert other architectures to kbuild 2.5 and how to plug
  third party code into kbuild.

  Converting architecture dependent Makefiles

    See these files for examples of a working conversion:
      arch/i386/Makefile.defs.noconfig
      arch/i386/Makefile.defs.config
      arch/i386/Makefile.in
      arch/i386/boot/Makefile.in
      arch/i386/kernel/Makefile.in

    arch/$(ARCH)/Makefile.defs.{no}config contain arch specific defines.
    Makefile.defs.noconfig is included by the top level Makefile, before any
    config variables are set.  Makefile.defs.config is included by the global
    makefile, after the config is known.  These files must not contain any
    make rules, just definitions.  Most of the entries come from
    arch/$(ARCH)/Makefile, the compile rules are moved to
    arch/$(ARCH)/boot/Makefile.in and arch/$(ARCH)/Makefile.in.  Do not use
    ifdef or ifndef, CML2 changes the way some variables are defined, see
    arch/i386/Makefile.defs.config for the CML1/CML2 compatible method.

    The boot rules are the biggest problem, they contain arch specific
    special cases.  arch/$(ARCH)/boot/Makefile.in extends target
    'installable' with any arch specific dependencies.  You will probably
    need a create_objdir statement to say when object directory
    arch/$(ARCH)/boot is created.

    Because the boot compile rules are non-standard, they may not be able to
    use select(), use user_command() instead.  This will add the generated
    files to the CLEAN list, as well as detect changes in flags and inputs
    and automatically rebuild the target.  However, if your boot code uses
    standard kernel compile and link options then you can use base_target()
    and then you can use select and other commands for the boot loader as
    well as for the kernel.

    The hard part is getting the dependencies right.  Some architectures have
    been lazy about setting the correct build dependencies, instead of
    defining the correct dependency tree they have relied on 'make dep' doing
    the work.  make dep no longer exists and it was never safe anyway because
    it relied on human intervention.  Sometimes developers assumed that make
    dep was always rerun after config changes, this is obviously not true.
    If a user changes the config so that the size of a structure changes but
    they do not rerun make dep then the kernel has a mixture of definitions,
    oops.

      Never rely on human intervention.  If your kbuild requires the user to
      do anything other than make *config, installable or install then you
      have failed.  The only safe way is to code the correct dependency tree
      and remove all reliance on human intervention.

    Several architectures require assembler mappings of structures and
    typically rely on make dep to generate the data.  As noted above, this
    was never safe and is no longer supported.  Instead the objects that
    require the assembler mappings must have an explicit dependency on the
    generated file, which must be defined as $(objfile).  Get the
    dependencies right and let make take care of rebuilding as required.

    Convert non-boot arch/$(ARCH)/*/Makefile to Makefile.in style, using
    objlink(), select() etc.  Aassembler compiles do not get -traditional by
    default, add extra_aflags(foo.o -traditional) if required.

    Create arch/$(ARCH)/boot/config.install-2.5.  The config.install options
    are added to the end of the CML1 menus.  Instead of specifying make
    bzImage, make lilo, make zlilo etc., users set their required format
    using make *config, then make install does all the work.  If your boot
    file name is not vmlinux, zImage nor bzImage then add CONFIG_name,
    updating Configure.help, top level Makefile.in and scripts/Makefile-2.5
    accordingly.

    vmlinux.lds has been replaced by vmlinux.lds.i which is generated from
    vmlinux.lds.S.  All architectures should use this format so we have a
    consistent set of filenames to exclude.  Using vmlinux.lds.[Si] means
    that these files get full dependency support.

  Converting external Makefiles and sources

    You can only use kbuild 2.5 for external sources when the external source
    tree uses the same directory structure as the kernel.  For example, if
    you have an additional parallel port module, put the source in
    drivers/parport in a separate tree.  Set and export the variables
    KBUILD_OBJTREE (common object tree), KBUILD_SRCTREE_000 (base Linus
    kernel), KBUILD_SRCTREE_010 (your external source).  kbuild 2.5 will
    then treat your source tree as part of a single kernel source, no need
    for manual compilation or installation.

    Every new external source requires updates to the configuration and
    Makefile entries for the affected directories.  You can take a copy of
    the base Config.in and Makefile.in into your tree and change them but
    there is a better way.  It is rare that you have to add your option in
    the middle of an existing file, appending to an existing file is usually
    good enough.  Create Config.in.append and Makefile.in.append in your
    tree, containing just the new lines.  For example,

      drivers/parport/Config.in.append
        dep_tristate '  Wibble' CONFIG_PARPORT_WIBBLE $CONFIG_PARPORT

      drivers/parport/Makefile.in.append
        select(CONFIG_PARPORT_WIBBLE wibble.o)

    To be a good CML citizen, you should also have help text for your config
    options, create Documentation/Configure.help.append in your tree.
    Because Configure.help relies on blank lines, make sure your help text
    has a blank line at the start and end.

    Converting kbuild 2.4 Makefiles to kbuild 2.5 Makefile.in style is
    relatively easy, unless you have special requirements.  Unfortunately
    kbuild 2.4 Makefiles do subtly different processing, depending on the
    presence of variables such as O_TARGET.  Sometimes it is easier to
    document what you want kbuild to do then code the kbuild 2.5 statements
    from scratch, instead of reverse engineering the kbuild 2.4 interactions.

    Occurrences of "obj-$(CONFIG) += dir/object.o" or "obj-y += dir/object.o"
    are not selecting the object, instead they are controlling the link
    order.  In kbuild 2.5 link order for other directories is controlled by
    link_subdirs(), not by select.  The replacement is "link_subdirs(dir)".
    Note that this is always unconditional, link_subdirs defines the link
    order for vmlinux, irrespective of whether and option is selected or
    not.

    "export-objs := list" maps to "expsyms(list)".

    Multi part objects in kbuild 2.4 have three parts, "list-multi :=
    targets", "target-objs := sub_objects" plus a rule to link the
    sub_objects into their target.  In kbuild 2.5 this collapses to one
    definition for each target, "objlink(target sub_objects)".

    Lines like "ifeq ($(CONFIG_ISDN_PPP),y)" are replaced by
    "ifsel(CONFIG_ISDN_PPP)" or "ifselnmod(CONFIG_ISDN_PPP)".  ifsel() tests
    if the config is selected ('y' or 'm'), ifselnmod() tests for 'y' only.
    Which one you use depends on what you are trying to achieve, if in doubt
    use ifsel().  In most cases you can collapse the ifsel() into the
    select() command.  For example,

      ifeq ($(CONFIG_ISDN_PPP),y)
        obj-$(CONFIG_ISDN) += slhc.o
      endif

    converts neatly to

      select(CONFIG_ISDN CONFIG_ISDN_PPP slhc.o)

    The first config (CONFIG_ISDN) determines how slhc.o is built ('y' or
    'm'), slhc.o is only built if both CONFIG_ISDN and CONFIG_ISDN_PPP are
    selected.

    Remove L_TARGET.

    A lot of the kbuild 2.4 O_TARGET lines are present to overcome the
    deficiencies of recursive make.  Each directory links its objects plus
    the objects in the lower directories into an object which is then passed
    up to the next layer.  This causes a lot of redundant linking and file
    activity and raises the possibility of out of date contents.  In kbuild
    2.5 you should only link the directory contents into a single object if
    that object may be used as a module.  Where a target is built up from
    multiple objects _and_ the config variable that selects that object has
    type tristate then replace O_TARGET with objlink().  Otherwise remove
    O_TARGET entirely, the objects will automatically be linked into vmlinux
    if they are selected.

    When you have an objlink() entry, be careful if the kbuild 2.4 Makefile
    defines O_TARGET and has no list-multi entries.  The presence of O_TARGET
    without list-multi modifies the behavior of "obj-$(CONFIG)", instead of
    linking into vmlinux or becoming a free standing module, the object is
    silently appended to the sub_object_list for O_TARGET.  So

      O_TARGET := isofs.o
      obj-y  := namei.o inode.o dir.o util.o rock.o
      obj-$(CONFIG_JOLIET) += joliet.o

    is not selecting namei.o, inode.o, dir.o, util.o and rock.o or joliet.o
    on their own, it is appending them to the list of objects that make up
    isofs.o.  kbuild 2.5 makes this explicit, the equivalent is

      objlink(isofs.o namei.o inode.o dir.o util.o rock.o)
      objlink(CONFIG_JOLIET isofs.o joliet.o)

    In kbuild 2.4, you have to look at the parent of each Makefile to
    determine how and when this Makefile is invoked.  In kbuild 2.5 all
    Makefile.in files are read and processed, so each Makefile.in must be
    self contained and must control its own processing.  In a few cases, you
    need to move a test from the parent Makefile into the child Makefile.in.
    For example, drivers/tc/Makefile tested just CONFIG_VT because the
    makefile was only expanded when TC was selected.  drivers/tc/Makefile.in
    does

      select(CONFIG_VT CONFIG_TC lk201.o lk201-map.o lk201-remap.o)

    because CONFIG_VT can be set without CONFIG_TC.  This is only a problem
    where a config variable selects objects in multiple directories.
    Strictly speaking this is the wrong way to handle this case, the config
    code should derive CONFIG_TC_VT from both variables and tc/Makefile.in
    should have an unconditional

      select(CONFIG_TC_VT lk201.o lk201-map.o lk201-remap.o)

    Ignore mod-subdirs and subdirs-*, they are not required in kbuild 2.5,
    with one exception.  Check the child Makefile.in to see if any config
    tests need to be moved from the parent into the child.  For example,
    fs/isofs/Makefile in kbuild 2.4 does not test CONFIG_ISO9660_FS, instead
    it is tested in the parent fs/Makefile.  In kbuild 2.5 each Makefile.in
    must be self contained so fs/isofs/Makefile.in contains

      select(CONFIG_ISO9660_FS isofs.o)

    "obj-$(CONFIG_FOO) += foo.o" maps to "select(CONFIG_FOO foo.o)", unless
    the object is in another directory (use link_subdirs) or the Makefile
    defines O_TARGET _and_ the selection variable has type tristate (use
    objlink(CONFIG_FOO).

    If any of your code uses #include <> for local files or #include "../"
    then you should change your code.  #include <> is incorrect for local
    files, it should be #include "".  #include "../foo.h" assumes that all
    the source is in the same tree, you got away with it for kbuild 2.4 but
    2.5 breaks that assumption.  The correct way to include files in other
    directories is to use '#include "foo.h"' and set extra cflags for the
    source that includes foo.h to add the relevant directory to the include
    path.  In particular, change '#include "../scsi/scsi.h"' to '#include
    "scsi.h"' and add 'extra_cflags(bar.o $(src_includelist /drivers/scsi))'
    to your Makefile.in, where bar.o is the object that includes scsi.h.  Use
    #include <> only for global include files from include/linux and
    include/asm, use #include "" for special includes from other locations.
    Do not use relative paths in any includes.

    Replace "EXTRA_CFLAGS += flags" with extra_cflags_all(flags).  Replace
    "CFLAGS_object.o += flags" with "extra_cflags(object.o flags)".  Ditto
    for assembler and ld flags.

    If at all possible, convert host commands to user_command() or hostcc
    format.  That has the benefit of automatic checking on dependencies,
    flags etc.

    The commands expsyms() and objlink() describe what will happen to
    objects, the select() commands say when the objects will be built.  There
    is no point in making expsyms and objlink dependent on ifsel(config),
    they can usually be issued unconditionally.  As a matter of style, I
    prefer expsyms and objlink at the start of the Makefile.in, followed by
    select and link_subdirs commands, then flags, with user_commands at the
    end.

    Remove all references to TOPDIR, HPATH and Rules.make.

    You should never need to run make yourself in any Makefile.in.  The
    global makefile removes the need to specially make a sub directory,
    instead you code the dependency rules and let the global make do its job.

    Clean up architecture assembler offsets and use the standard method
    listed in "Offsets for Assembler" below.


CONTROLLING KBUILD

  It is always safe to use make -j or make -j<n> in kbuild 2.5, as long as
  your machine can handle the load.  I recommend make -j2 even on
  uni-processors, so cpu processing can overlap with programs that are
  waiting for I/O to complete.  Experiment to find the value of -j that
  minimizes the elapsed time on your hardware.

  NOTE: You need make 3.79.1 to use kbuild 2.5.  It might work with 3.78 but
        it has not been tested.

  The make command line can specify multiple targets, which will be built in
  the order you specify.  Any targets can be mixed on the command line except
  for clean and mrproper, the clean and mrproper targets cannot appear on the
  same make command as other targets.  It is quite valid to unpack a kernel
  source, copy your .config to the object directory, set KBUILD_OBJTREE and
  KBUILD_SRCTREE_nnn as required and run
    make -j oldconfig installable && sudo make -j install

  You can make all the targets in a directory by make directory/name, without
  a trailing '/'.  This is not recursive, it only builds targets in that
  object directory, but if any of the targets in the specified directory
  depend on targets in other object directories then those other targets will
  be built as well.  For example, make fs/cramfs requires inflate/zlib.o in
  order to link cramfs.o so inflate/zlib.o will be built as well.  make
  drivers/acpi will only make the objects in drivers/acpi because there is no
  direct dependency on objects in any of the acpi sub-directories.  You can
  force a recursive scan by appending '-r' to the directory name, so make
  drivers/acpi-r will consider all selected targets in drivers/acpi and its
  sub-directories.

  In addition to the KBUILD_OBJTREE and KBUILD_SRCTREE_nnn variables which
  define where the source and object trees are, kbuild 2.5 supports several
  other variables which can be set on the make command line.

  KBUILD_DIR_LIST
    Defines a file which contains definitions of KBUILD_OBJTREE and
    KBUILD_SRCTREE_000.  From the top level Makefile:

      If KBUILD_DIR_LIST is set then read it, it must contain at least
        export KBUILD_SRCTREE_000=/full/path/name/to/source
        export KBUILD_OBJTREE=/full/path/name/to/object
      but can contain other KBUILD_SRCTREE_nnn variables.  '=' must be used,
      not ':=' and there must be no spaces either side of '='.  You can use
      variables as long as they use ${name} syntax, that format works for
      both shell and make.

      If KBUILD_DIR_LIST is not set then use environment variables
      KBUILD_SRCTREE_000 and KBUILD_OBJTREE if they are set.  You can set
      other KBUILD_SRCTREE_nnn environment variables.

      If either of KBUILD_SRCTREE_000 and KBUILD_OBJTREE are not set then
      they default to the current directory.

  KBUILD_SHELL
    Defaults to $BASH if set, then /bin/bash if it exists, otherwise sh.

  ARCH
    The architecture you are building for.  The default is the architecture
    of the build machine.

  KBUILD_INCLUDE_PATHS, KBUILD_INCLUDE_DIRS
    Separate source and object directories require some tweaking to maintain
    the include list correctly, especially with multiple source trees.  The
    top level Makefile-2.5 uses an awk script to find all the possible
    include paths and generate a set of symlinks to the include directories.
    The awk script uses variable KBUILD_INCLUDE_PATHS to list the main
    include directories and KBUILD_INCLUDE_DIRS to list the directories
    directly under include.

    KBUILD_INCLUDE_PATHS always contains 'include' as the first path,
    normally that is all that is required.  However some kernel code has been
    developed using its own additional include tree, complete with
    asm-$(ARCH).  This is probably the wrong way to handle extra includes,
    they should be stored with the other include files instead of duplicating
    the structure elsewhere.  For now, set KBUILD_INCLUDE_PATHS to the
    relative path to the extra include directory, gcc will then look in the
    extra include directories after the standard ones.  For example,

      KBUILD_INCLUDE_PATHS=security/selinux/include

    KBUILD_INCLUDE_DIRS lists the directories under KBUILD_INCLUDE_PATHS
    which contain global data referenced by #include statements.  Do not
    include asm-$(ARCH), that is automatically added by the awk script as
    asm, not asm-$(ARCH).  The default value for KBUILD_INCLUDE_DIRS is

      linux math-emu net pcmcia scsi video asm-generic

    For ppc, asm-m68k is added to that list, due to broken ppc code that
    includes m68k asm headers.

    Note that extra include directories specified on KBUILD_INCLUDE_PATHS
    (try not to do this, it is probably wrong) will only work if the include
    directory contains sub directories listed in KBUILD_INCLUDE_DIRS.

  HOSTCC, HOSTAS, HOSTLD, HOSTAR
    The tools used for building programs that will run on this machine.
    Typically used when you compile a program then run it to generate output
    which is used by the rest of the build.

  HOSTCFLAGS, HOSTAFLAGS, HOSTLDFLAGS, HOSTARFLAGS
    Flags for compiling and linking programs that are run on this machine.

    The order of cflags and aflags for host compiles is:
      An include list for local files which are referenced by #include "".
      This list is automatically generated.
        -I for the current object directory, for any generated files.
        -I for the current source directory in each of the shadow trees, from
          top to bottom.
        -I for the current source directory in the base source tree.
        -I- to prevent local files being read from anywhere else.
      HOST[CA]FLAGS from the top level Makefile.  This contains the include
      list for files included by #include <>.  The include list is:
        include, in the object directory, for any generated include files.
        .tmp_include/src_nnn, a set of symlinks for each source tree, running
        from the top shadow tree to the base source tree.  Each set of
        symlinks points to directories include/linux, include/math-emu,
        include/net, include/pcmcia, include/scsi, include/video,
        include/asm-generic plus include/asm for include/asm-$(ARCH) in the
        corresponding source tree, but only if the target directories exist.
      -DKBUILD_OBJECT=module, the name of the module the object is linked
        into, without the trailing '.o' and without any paths.  If the object
        is a free standing module or is linked into vmlinux then the "module"
        name is the object itself.  Automatically generated.  Probably
        irrelevant for host compiles but retained just in case somebody finds
        a use for it.  Omitted if the object is linked into multiple targets.
      -DKBUILD_BASENAME=object, the name of the object itself, with ',' and
        '-' converted to '_'.  For an object that is not linked into anything
        else (ignoring vmlinux), KBUILD_OBJECT and KBUILD_BASENAME are the
        same.  KBUILD_BASENAME is mainly used for object specific labels in
        out of line code.  Automatically generated.  Probably irrelevant for
        host compiles but retained just in case somebody finds a use for it.
      extra_[ca]flags_all() from the directory Makefile.in.
      extra_[ca]flags(object.o) from the directory Makefile.in.
      EXTRA_[CA]FLAGS_directory from the command line.
      EXTRA_[CA]FLAGS_directory/object.o from the command line.

    The order of ldflags and arflags for host linking is:
      HOSTxxFLAGS from the top level Makefile.
      xxFLAGS from arch/$(ARCH)/Makefile.defs.{no}config.
      EXTRA_xxFLAGS from the command line.
      extra_xxflags_all() from the directory Makefile.in.
      extra_xxflags(object.o) from the directory Makefile.in.
      EXTRA_xxFLAGS_directory from the command line.
      EXTRA_xxFLAGS_directory/object.o from the command line.

  CROSS_COMPILE
    A string which is prefixed to utilities that depend on the target
    architecture.  To cross compile for IA64 when the IA64 utilities are in
    /usr/bin/ia64, use CROSS_COMPILE=/usr/bin/ia64/.

  CC, AS, LD, AR, CPP, NM, STRIP, OBJCOPY, OBJDUMP
    Names for utilities that depend on the target architecture.  If you set
    any of these on the command line then you must explicitly include any
    cross compile prefix, a command line specification for these variables
    overrides any CROSS_COMPILE value.

  AWK, DEPMOD, PERL, LEX, YACC, GZIP_COMMAND, MD5SUM, WISH
    Names for utilities that do not depend on the target architecture.  When
    you build for another architecture and make install, you should set
    DEPMOD=/bin/true, current depmod does not support cross building.
    Note: the variable for gzip is GZIP_COMMAND, not GZIP.  gzip uses GZIP
          for its options.

  KBUILD_WRITABLE
    kbuild 2.5 supports compilation by one user and installation by another
    user, typically the installation user is root.  The installation process
    must not change any file permissions nor update any files owned by the
    compilation user, otherwise they will not be able to recompile.  If
    autoconf.h exists and is not owned by this user then kbuild switches into
    read only mode.  If multiple users are sharing a compile environment
    (why??) then make KBUILD_WRITABLE=y, then it is your responsibility to
    get the permissions right.  Bug reports with KBUILD_WRITABLE forced to y
    will be ignored.

    NOTE: If your build is not up to date when you run make install then the
          make install will try to complete the build.  If the build and
          install users are different this will fail with
            KBUILD_WRITABLE is false, giving up
          Always complete the build before running make install as another
          user.

  CFLAGS, CFLAGS_KERNEL, CFLAGS_MODULE
    CFLAGS applies to all compiles for the target machine.  CFLAGS_KERNEL are
    additional flags that only apply to objects which are linked into the
    kernel.  CFLAGS_MODULE are additional flags that only apply to objects
    which are built as modules.  You should not need to set any of these
    variables, use EXTRA_... flags instead.  CFLAGS, CFLAGS_KERNEL and
    CFLAGS_MODULE are set to arch independent values in the top level
    makefile and are usually extended by
    arch/$(ARCH)/Makefile.defs.{no}config.

  CFLAGS_NOSTDINC
    Flags generated by kbuild to prevent the compiler from reading from user
    space includes.  The kernel code must be completely self contained and
    the build must not vary depending on which operating system you do the
    compile on.  The only reason that this variable is exposed is to allow
    the user to 'make CFLAGS_NOSTDINC=' as a temporary workaround for include
    problems, but a production kernel must not include user space files.

  EXTRA_CFLAGS, EXTRA_CFLAGS_KERNEL, EXTRA_CFLAGS_MODULE
    These variables are not set by kbuild, they are intended for extra flags
    which the user needs.  If any of CFLAGS, CFLAGS_KERNEL or CFLAGS_MODULE
    are set on the command line then the corresponding EXTRA_ flags are
    ignored.

  EXTRA_CFLAGS_directory
    Add these flags to all objects built in the specified object directory.
    The directory name is relative to the top object directory and must not
    contain a trailing '/'.  EXTRA_CFLAGS_drivers/net="-g -gstabs" is valid,
    EXTRA_CFLAGS_/drivers/net= and EXTRA_CFLAGS_drivers/net/= are not.

  EXTRA_CFLAGS_object
    Add these flags to the build of the specified object.  The object name is
    relative to the top object directory and must contain the full file name.
    EXTRA_CFLAGS_drivers/net/plip.o="-g -gstabs" is valid,
    EXTRA_CFLAGS_/drivers/net/plip.o= and EXTRA_CFLAGS_drivers/net/plip= are
    not.

    The order of cflags (except for targetcc) is:
      An include list for local files which are referenced by #include "".
      This list is automatically generated.
        -I for the current object directory, for any generated files.
        -I for the current source directory in each of the shadow trees, from
          top to bottom.
        -I for the current source directory in the base source tree.
        -I- to prevent local files being read from anywhere else.
      CFLAGS from the top level Makefile.  This contains the include list for
      files included by #include <>.  The include list is:
        include, in the object directory, for any generated include files.
        .tmp_include/src_nnn, a set of symlinks for each source tree, running
        from the top shadow tree to the base source tree.  Each set of
        symlinks points to directories include/linux, include/math-emu,
        include/net, include/pcmcia, include/scsi, include/video,
        include/asm-generic plus include/asm for include/asm-$(ARCH) in the
        corresponding source tree, but only if the target directories exist.
      CFLAGS from arch/$(ARCH)/Makefile.defs.{no}config.
      CFLAGS for special compilers, such as StackGuard.
      CFLAGS_NOSTDINC.
      EXTRA_CFLAGS from the command line.
      -DKBUILD_OBJECT=module, the name of the module the object is linked
        into, without the trailing '.o' and without any paths.  If the object
        is a free standing module or is linked into vmlinux then the "module"
        name is the object itself.  Automatically generated.  Omitted if the
        object is linked into multiple targets.
      -DKBUILD_BASENAME=object, the name of the object itself, with ',' and
        '-' converted to '_'.  For an object that is not linked into anything
        else (ignoring vmlinux), KBUILD_OBJECT and KBUILD_BASENAME are the
        same.  KBUILD_BASENAME is mainly used for object specific labels in
        out of line code.  Automatically generated.
      -DKBUILD_SETUP for targets defined as setup().
      -DEXPORT_SYMTAB for objects defined in expsyms().
      extra_cflags_all() from the directory Makefile.in.
      extra_cflags(object.o) from the directory Makefile.in.
      CFLAGS_MODULE or CFLAGS_KERNEL, as required.
      EXTRA_CFLAGS_MODULE or EXTRA_CFLAGS_KERNEL, as required, from the
        command line.
      EXTRA_CFLAGS_directory from the command line.
      EXTRA_CFLAGS_directory/object.o from the command line.

    The order of cflags for objects specified in targetcc is:
      An include list for local files which are referenced by #include "".
      This list is automatically generated.
        -I for the current object directory, for any generated files.
        -I for the current source directory in each of the shadow trees, from
          top to bottom.
        -I for the current source directory in the base source tree.
        -I- to prevent local files being read from anywhere else.
      The standard include list for CC.
      No CFLAGS from any of the global kernel sources.  Objects compiled by
      targetcc should not include kernel headers.
      CFLAGS for special compilers, such as StackGuard.
      -DKBUILD_OBJECT=module, the name of the module the object is linked
        into, without the trailing '.o' and without any paths.  If the object
        is a free standing module or is linked into vmlinux then the "module"
        name is the object itself.  Automatically generated.  Omitted if the
        object is linked into multiple targets.
      -DKBUILD_BASENAME=object, the name of the object itself, with ',' and
        '-' converted to '_'.  For an object that is not linked into anything
        else (ignoring vmlinux), KBUILD_OBJECT and KBUILD_BASENAME are the
        same.  KBUILD_BASENAME is mainly used for object specific labels in
        out of line code.  Automatically generated.
      extra_cflags_all() from the directory Makefile.in.
      extra_cflags(object.o) from the directory Makefile.in.
      EXTRA_CFLAGS_directory from the command line.
      EXTRA_CFLAGS_directory/object.o from the command line.

  NOTE: Bash will not accept environment variables that contain special
        characters such as '/' and '.' so you cannot export such variables,
        the variables must be specified on the make command line.

  NOTE: Some gcc options have hidden assumptions about directories.  In
        particular -save-temps assumes that the object is being written to
        the current directory, which is not true for kbuild.  It only makes
        sense to use -save-temps for a single object or a single directory
        and you must look in the top level object directory to find the
        results.  -save-temps will not work with module symbol versions, you
        must add CONFIG_MODVERSIONS=n to the make command line when using
        -save-temps.  You can always make directory/object.[is] to see the
        pre-processor or assembler output, kbuild 2.5 generates rules for the
        .[is] files, no need to use -save-temps for that case.

  AFLAGS, AFLAGS_KERNEL, AFLAGS_MODULE
  AFLAGS_NOSTDINC
  EXTRA_AFLAGS, EXTRA_AFLAGS_KERNEL, EXTRA_AFLAGS_MODULE
  EXTRA_AFLAGS_directory, EXTRA_AFLAGS_object
    As for CFLAGS but for Assembler programs for the target architecture.
    AFLAGS, AFLAGS_KERNEL and AFLAGS_MODULE are set to arch independent
    values in the top level makefile and are usually extended by
    arch/$(ARCH)/Makefile.defs.{no}config.

    The order of aflags is:
      An include list for local files which are referenced by #include "",
      this is the same include list that is used for cflags.
      AFLAGS from the top level Makefile, including the external include
        list, as for cflags.
      AFLAGS from arch/$(ARCH)/Makefile.defs.{no}config.
      AFLAGS_NOSTDINC.
      EXTRA_AFLAGS from the command line.
      -DKBUILD_OBJECT=module.  Omitted if the object is linked into multiple
        targets.
      -DKBUILD_BASENAME=object.
      extra_aflags_all() from the directory Makefile.in.
      extra_aflags(object.o) from the directory Makefile.in.
      AFLAGS_MODULE or AFLAGS_KERNEL, as required.
      EXTRA_AFLAGS_MODULE or EXTRA_AFLAGS_KERNEL, as required, from the
        command line.
      EXTRA_AFLAGS_directory from the command line.
      EXTRA_AFLAGS_directory/object.o from the command line.

  NOTE: The default AFLAGS excludes -traditional, as a kbuild standard.  If
        your assembler requires pre-processing with -traditional, use
        extra_aflags(object.o -traditional).

  LDFLAGS, LDFLAGS_KERNEL, LDFLAGS_MODULE
  EXTRA_LDFLAGS, EXTRA_LDFLAGS_KERNEL, EXTRA_LDFLAGS_MODULE
  EXTRA_LDFLAGS_directory, EXTRA_LDFLAGS_object
    As for CFLAGS but used when linking programs for the target architecture.
    LDFLAGS, LDFLAGS_KERNEL and LDFLAGS_MODULE are set to arch independent
    values in the top level makefile and are usually extended by
    arch/$(ARCH)/Makefile.defs.{no}config.

    The order of ldflags is:
      LDFLAGS from the top level Makefile.
      LDFLAGS from arch/$(ARCH)/Makefile.defs.{no}config.
      EXTRA_LDFLAGS from the command line.
      extra_ldflags_all() from the directory Makefile.in.
      extra_ldflags(object.o) from the directory Makefile.in.
      LDFLAGS_MODULE or LDFLAGS_KERNEL, as required.
      EXTRA_LDFLAGS_MODULE or EXTRA_LDFLAGS_KERNEL, as required, from the
        command line.
      EXTRA_LDFLAGS_directory from the command line.
      EXTRA_LDFLAGS_directory/object.o from the command line.

  ARFLAGS, ARFLAGS_KERNEL, ARFLAGS_MODULE
  EXTRA_ARFLAGS, EXTRA_ARFLAGS_KERNEL, EXTRA_ARFLAGS_MODULE
  EXTRA_ARFLAGS_directory, EXTRA_ARFLAGS_object
    As for LDFLAGS but used when building archives for the target
    architecture.  ARFLAGS, ARFLAGS_KERNEL and ARFLAGS_MODULE are set to arch
    independent values in the top level makefile and are usually extended by
    arch/$(ARCH)/Makefile.defs.{no}config.

    The order of ARflags is:
      ARFLAGS from the top level Makefile.
      ARFLAGS from arch/$(ARCH)/Makefile.defs.{no}config.
      EXTRA_ARFLAGS from the command line.
      extra_arflags_all() from the directory Makefile.in.
      extra_arflags(object.o) from the directory Makefile.in.
      ARFLAGS_MODULE or ARFLAGS_KERNEL, as required.
      EXTRA_ARFLAGS_MODULE or EXTRA_ARFLAGS_KERNEL, as required, from the
        command line.
      EXTRA_ARFLAGS_directory from the command line.
      EXTRA_ARFLAGS_directory/object.o from the command line.

  OBJCOPYFLAGS
    Flags for running objcopy to convert targets into unusual formats, in
    particular when converting vmlinux to a bootable format.  OBJCOPYFLAGS
    are set to arch independent values in the top level makefile and are
    usually extended by arch/$(ARCH)/Makefile.defs.{no}config.

  KBUILD_QUIET
    Most commands run by make are prefixed by $(KBUILD_QUIET) which defaults
    to '@' so you do not see all the commands.  It is much easier to see what
    is happening in quiet mode, you get one short line per target plus any
    errors and warnings.  If you suspect the problem is in kbuild itself and
    not your code, you can "make KBUILD_QUIET= directory/object.o" to see the
    commands being run.

  PP_MAKEFILE[1-4]_FLAGS
    Flags passed to programs pp_makefile[1-4] when they are run.  Normally
    only used when debugging kbuild.

  PP_GETOPT_H
    The full path to the include file that defines getopt().  Default is
    /usr/include/getopt.h if that file exists, otherwise the default is
    /usr/include/unistd.h.

  PP_GETOPT_LONG
    1 if $(PP_GETOPT_H) contains the string getopt_long, otherwise 0.  When
    PP_GETOPT_LONG is 0, the pp_makefile* programs do not support long
    command options.

  PP_GNU_SOURCE
    Normally the string '-D_GNU_SOURCE'.  This flag is exposed in case you
    compile on a system that has problems when _GNU_SOURCE is defined.

  PP_CC_FLAGS
    Flags for compiling the pre-processor programs using the host compiler.
    Default is -fno-strict-aliasing -O2 -DNDEBUG=1 -Wall, override as
    required.

  CONFIG_Y, CONFIG_M
    Generated config variables, used in select() commands.  CONFIG_Y is
    always 'y'.  CONFIG_M is 'm' if CONFIG_MODULES is true, otherwise
    CONFIG_M is 'y'.

  CONFIG_KBUILD_GCC_VERSION
    A generated config variable, it contains the version of gcc used to
    compile the kernel and modules.  It is the result of
      $(CC) -v 2>&1 | sed -ne '1s:.*/\([^/]*/[^/]*\)/[^/]\+$:\1:p'

  CONFIG_KBUILD_CRITICAL
    A string config variable, it contains a list of other config variables
    that are critical to the build.  If any of the listed variables change
    their value then the entire kernel must be rebuilt.  The critical list is
    intended to prevent a kernel being built from an incompatible mixture of
    options and to prevent modules being loaded into grossly incompatible
    kernels.  A typical list is

      CONFIG_KBUILD_CRITICAL="CONFIG_SMP CONFIG_KBUILD_GCC_VERSION arch_opt"

    Changing the version of gcc or switching from UP to SMP or vice versa
    forces a complete rebuild.  'arch_opt' is a set of architecture specific
    config variables, such as a list of machine types.

  USERVERSION
    In current kernels the kernel version information is part of the top
    level Makefile. I want to move them to a separate file so the top level
    Makefile it is only changed for kbuild, not for every kernel.  The plan
    is to ship a file A_version containing just the VERSION, PATCHLEVEL,
    SUBLEVEL and EXTRAVERSION variables with the kernel sources.
    In the meantime, we generate our own $KBUILD_OBJTREE/A_version containing
    these variables based on the old Makefile.

    Variable USERVERSION is _not_ part of A_version, this variable is
    reserved for the end user and must never be set in any distributed kernel.
    The user can then customize the kernel version by setting USERVERSION as
    part of the make command line e.g.
	make -f $KBUILD_SRCTREE_000/Makefile-2.5 -j2 USERVERSION=whatever
    The USERVERSION text gets appended to the existing kernel version info.


TEMPORARY FILES FOR KBUILD

  All the temporary files and directories created by kbuild start with
  '.tmp_' or 'tmp_'.  Only the kbuild team needs to know what is in these
  files, but a brief list might be useful to the general build audience.
  This list is roughly in the order they appear in the top level and scripts
  Makefiles.

  .tmp_include_list
    A shell script which, when executed, returns the external include list,
    used for files referenced by '#include <>'.

  .tmp_global_makefile
    The final global makefile, executed by make to build everything except
    scripts.  This makefile includes the rules for building vmlinux, building
    modules, converting vmlinix to a bootable format, installing the bootable
    kernel, installing the modules and running the post install script, if
    any.

  .tmp_db_main
    The main kbuild database.  This uses Larry McVoy's memory mapped database
    (mdbm).  For information on the record formats, see kbuild-2.5-db* files
    in this directory.

  .tmp_xxx followed by cmp -s || mv
    Various files are generated but the file must not be updated if the
    contents have not changed.  Writing to .tmp_xxx followed by cmp -s || mv
    generates the new version but does not update the original unless the
    contents have changed.

  .tmp_implicit
    A .tmp_implicit file is generated in every directory that contains
    targets.  It contains the implicit dependencies of each target on the
    files that it includes, including the source file, either directly or
    indirectly.  For each included file, .tmp_implicit also includes the
    config settings that the included file depends on.

    Normally pp_makefile4 does all the implicit dependency checking and does
    it far faster than make can.  However when you use NO_MAKEFILE_GEN,
    pp_makefile4 is not run, then the .tmp_implicit files are used to give
    make some of the information it needs.

  .tmp_no_makefile_gen
    Set when you kbuild with NO_MAKEFILE_GEN, cleared after a successful make
    installable without NO_MAKEFILE_GEN.  Used to detect make install on an
    incomplete build.

  .tmp_config/
    The config programs are unusual in that they scan all of the source tree.
    Instead of teaching all the config code about shadow trees, it is easier
    to build a tree that mimics the source structure, including the top
    version of shadow files plus .append and .prepend then run config under
    that directory.  .tmp_config/ contains all the symlinks and generated
    config files to hide the shadows from CML code.

  .tmp_filelist.txt, .tmp_filelist.bin
    A list of all files, including objects and shadow files, but excluding
    files that start with '.'.  Used all over the place to control kbuild.

  .tmp_env
    In the unlikely event that you need to run the global makefile or
    individual pp_makefile5 commands by hand, you need various exported
    variables.  'source .tmp_env' will set the required variables, other than
    KBUILD_OBJTREE and KBUILD_SCRTREE_nnn.  Only use .tmp_env when debugging
    kbuild.

  .tmp_global_makefile_in.1
    A concatenation of all the Makefile.in files, including any .append and
    .prepend data, taking into account any shadow Makefile.in files.

  .tmp_global_makefile_in.2
    .tmp_global_makefile_in.1 converted from the kbuild mini-language to make
    commands.  I use make to evaluate the conditions in this file, it is
    easier than writing yet another language and it lets the makefiles use
    real make commands where necessary.

  .tmp_select
    The output from running make on .tmp_global_makefile_in.2.  It is a
    series of lines defining the relative object directory, the flags, the
    objects selected, the sub directories to be scanned when linking vmlinux,
    the multi part objects, which objects export symbols, what is compiled as
    assembler.

  .tmp_global_makefile_feedback
    A list of the old commands used to create every selected target.  Each
    old command is compared against the new command for that target, any
    mismatch forces a rebuild of the target.  This detects changes to
    compilers, to flags etc.

  .tmp_vmlinux_order
    A tree showing the order that directories and objects are used when
    linking vmlinux.  Very useful when debugging link order problems
    for code defined as __init, no need to guess about the link order.

  .tmp_vmlinux_objects
    The objects used to link vmlinux, excluding $(arch_head) objects,
    as a linker script.  This is a separate file because the list of
    objects was approaching the command limit for some build hosts.

  .tmp_vmlinux_modules
    A list of all the modules to install.

  The _order, _objects and _modules files are created for each base defined
  in the Makefile.in files.  vmlinux is always defined as a base.  Some
  architectures define other base targets, e.g. boot loaders.

  .tmp_targets
    The pre-processing programs require a list of targets.  Most of the
    target list is extracted during the initial conversion of the Makefile.in
    to make commands, but some targets cannot be identified until after make
    has expanded variables.  .tmp_targets contains just the additional
    targets.

  .tmp_pp_makefile2_parse.y_to_l
    For some constructs, the parser in pp_makefile2 generates output which is
    fed back into the lexical analyser for macro expansion.  It uses this
    temporary file for the feedback, the feedback is never more than one
    level.

  tmp_<target>
    Used with update_if_changed() to decide if a file has changed or not.
    The default for the second parameter of update_if_changed() is the target
    prefixed with 'tmp_'.


ADDITIONAL TARGETS AND COMMANDS

  Some users will want to execute additional commands as part of kbuild.  In
  particular users who generate kernel packages will want to run their own
  commands after make install.  Instead of polluting the kbuild Makefiles
  with rules that have nothing to do with kernel building, kbuild 2.5
  supports user defined additional commands, using variables ADD0 through
  ADD9, with the corresponding ADD[0-9]_DEP and ADD[0-9]_CMD.  A command like

    make ADD0=pkg ADD0_DEP=install ADD0_CMD='my-package-script' pkg

  Will make target 'pkg', which is defined by ADD0.  It has a dependency
  (ADD0_DEP) of install so the install process runs first.  After install has
  completed, command my-package-script (ADD0_CMD) is run.  The command can be
  shell commands separated by ';' but will normally be a distribution
  specific script.  The command has access to all the config variables plus
  the variables that define the kernel, including KERNELRELEASE.

  It is the responsibility of the packager to maintain their own scripts.
  kbuild will not maintain scripts for every packaging manager used by every
  distribution.

  Because of the way that the .config variables are read by kbuild, you can
  specify a CONFIG_ variable on the make command line and it will override
  the value used by the makefiles.  In general this is not safe because the
  config values read during the compile stage are set by another mechanism so
  overriding a config variable on the command line when that variable is used
  in code will generate inconsistent results.

  However there are some config variables that can be safely specified on the
  make command line because they are only used by the makefiles.  All these
  variables start with CONFIG_INSTALL_, they define where the kernel,
  modules, map, .config etc. are installed.  Obviously a packaging system
  will want to set some of these values on the command line.  See the top
  level Makefile.in for the current CONFIG_INSTALL_ variables.


OFFSETS FOR ASSEMBLER

  kbuild 2.5 solves a long standing problem with kbuild 2.4.  Every
  architecture has Assembler that requires offsets of fields within C
  structures or the mapping of C names to numbers.  Assembler cannot include
  the C definitions so we need a mapping from C constructs to Assembler
  numbers.  Every architecture has handled this problem in a different way,
  none of the methods are 100% accurate nor dependable.

  i386 hard codes the offsets into the assembler code and hopes that the
  structure definitions never change.

  Alpha uses a C program that generates the text for the assembler.  This
  does not work in a cross compile environment because it assumes that HOSTCC
  == CC.

  Cris generates a chunk of assembler from C then uses .include instead of
  #include, with some fancy conditional selection.

  Mips, parisc, ppc, sparc generate assembler then extract and reformat lines
  from the assembler.  This works in both local and cross compile mode and is
  getting close to the correct way of doing it.  But it still has problems,
  see below.

  IA64 in 2.4 is particularly loathsome.  It uses different methods in native
  and cross compile modes, when the cross compile version would do for both.
  It ships a copy of the generated asm/offsets.h which is totally unreliable
  because the real offsets.h depends on the user's .config.  To add insult to
  injury, offsets.h is included in processor.h and ptrace.h on ia64 which
  means that it pollutes almost every C file.

  None of the above methods handle dependency checking at all.  PPC makes an
  attempt but it is manually defined and is incomplete, no other arch even
  makes an attempt to check dependencies on Assembler offsets.  All
  architectures assume that the user always runs make dep after any config
  changes that affect the assembler offsets.  If the user forgets to run make
  dep and the assembler and C values do not match - oops.

  kbuild 2.5 has a solution which works in all modes, is standard across all
  architectures and automatically tracks dependency changes.  No more room
  for human error.

  * Create arch/$(ARCH)/asm-offsets.c containing code like this, from
    arch/i386/asm-offsets.c.  This should be the standard format on all
    architectures, the only difference should be the list of fields to
    generate.

    /*
     * Generate definitions needed by assembly language modules.
     * This code generates raw asm output which is post-processed to extract
     * and format the required data.
     */

    #include <linux/types.h>
    #include <linux/stddef.h>
    #include <linux/sched.h>

    /* Use marker if you need to separate the values later */

    #define DEFINE(sym, val, marker) \
      asm volatile("\n-> " #sym " %0 " #val " " #marker : : "i" (val))

    #define BLANK() asm volatile("\n->" : : )

    int
    main(void)
    {
      DEFINE(state,        offsetof(struct task_struct, state),);
      DEFINE(flags,        offsetof(struct task_struct, flags),);
      DEFINE(sigpending,   offsetof(struct task_struct, sigpending),);
      DEFINE(addr_limit,   offsetof(struct task_struct, addr_limit),);
      DEFINE(exec_domain,  offsetof(struct task_struct, exec_domain),);
      DEFINE(need_resched, offsetof(struct task_struct, need_resched),);
      DEFINE(tsk_ptrace,   offsetof(struct task_struct, ptrace),);
      DEFINE(processor,    offsetof(struct task_struct, processor),);
      BLANK();
      DEFINE(ENOSYS,       ENOSYS,);
      return 0;
    }

  * When that code is compiled from .c to .s using CC for the target system,
    the generated Assembler contains lines like this

    -> state $0 offsetof(struct task_struct, state)
    -> flags $4 offsetof(struct task_struct, flags)
    -> sigpending $8 offsetof(struct task_struct, sigpending)
    -> addr_limit $12 offsetof(struct task_struct, addr_limit)
    -> exec_domain $16 offsetof(struct task_struct, exec_domain)
    -> need_resched $20 offsetof(struct task_struct, need_resched)
    -> tsk_ptrace $24 offsetof(struct task_struct, ptrace)
    -> processor $52 offsetof(struct task_struct, processor)
    ->
    -> ENOSYS $38 ENOSYS

    interspersed with Assembler declarations and blank lines.  The use of %c0
    instead of %0 in the DEFINE macro would remove '$' from the generated
    value but there are reports that %c0 does not work correctly on some
    architectures.  So DEFINE uses %0 and the next step removes '$' from the
    value field.

  * In arch/$(ARCH)/Makefile.in, define user commands to extract the '->'
    lines from asm-offsets.s and reformat as required for your architecture.
    arch/i386/Makefile.in contains

    # Convert raw asm offsets into something that can be included as
    # assembler definitions.  It converts
    #   -> symbol $value source
    # into
    #   symbol = value /* 0xvalue source */

    user_command(tmp_asm-offsets.h
            ($(objfile asm-offsets.s))
            (set -e;
              (echo "#ifndef __ASM_OFFSETS_H__";
               echo "#define __ASM_OFFSETS_H__";
               echo "/*";
               echo " * DO NOT MODIFY";
               echo " *";
               echo " * This file was generated by arch/$(ARCH)/Makefile.in.";
               echo " *";
               echo " */";
               echo "";
               awk "/^->\$$/{printf(\"\\n\");}
                 /^-> /{
                   sym = \$$2;
                   val = \$$3;
                   sub(/^\\\$$/, \"\", val);
                   \$$1 = \"\";
                   \$$2 = \"\";
                   \$$3 = \"\";
                   printf(\"%-20s = %3d\\t\\t\\t/* 0x%x\\t%s */\\n\",
                     sym, val, val, \$$0)
                 }";
               echo "";
               echo "#endif";
              ) < $< > $@;
            )
            ()
            )

    update_if_changed(asm-offsets.h)

    CLEAN += $(objfile asm-offsets.s)

    The awk code is a little complicated because it has to cope with both
    shell (\ -> \\, " -> \", $ -> \$) and make ($ -> $$) quoting rules but it
    works, and only has to be coded once.  There are benefits to having the
    awk code directly in the Makefile.in instead of a separate file, it gives
    full command tracking and avoids relying on file timestamps which do not
    work well with shadow trees and source repositories.

    The final output is in arch/$(ARCH)/asm-offsets.h.  On i386,
    asm-offsets.h contains

    #ifndef __ASM_OFFSETS_H__
    #define __ASM_OFFSETS_H__
    /*
     * DO NOT MODIFY
     *
     * This file was generated by arch/i386/Makefile.in.
     *
     */

    state        =   0  /* 0x0  offsetof(struct task_struct, state) */
    flags        =   4  /* 0x4  offsetof(struct task_struct, flags) */
    sigpending   =   8  /* 0x8  offsetof(struct task_struct, sigpending) */
    addr_limit   =  12  /* 0xc  offsetof(struct task_struct, addr_limit) */
    exec_domain  =  16  /* 0x10 offsetof(struct task_struct, exec_domain) */
    need_resched =  20  /* 0x14 offsetof(struct task_struct, need_resched) */
    tsk_ptrace   =  24  /* 0x18 offsetof(struct task_struct, ptrace) */
    processor    =  52  /* 0x34 offsetof(struct task_struct, processor) */

    ENOSYS       =  38  /* 0x26 ENOSYS */

    #endif

    Most architectures use offsets.h but some use other names.  None of the
    architectures agree on the location of the directory containing the code
    that generates the offsets, nor where the generated header is written to.
    kbuild 2.5 standardizes the location and name of the code, the location
    and name of the output and the format of the output, doing any arch
    specific processing in the makefile.  In the long run this will be easier
    than having eight different ways of generating assembler output.  I have
    included a marker parameter in the DEFINE macro, marker appears at the
    end of the '->' line, just in case an architecture needs some indicator
    in order to split the offsets into multiple files.

  * Do not, under any circumstances, include asm-offsets.h in any files that
    are used by C source, asm-offsets.h must only be used in Assembler code.
    IA64 made the mistake of including asm-offsets.h in processor.h and
    ptrace.h so they have to ship the generated asm-offsets.h to avoid C
    compile errors on parallel builds.  But the version that is shipped is
    incorrect, it does not match the user's config, a source of human error.

  * Do not ship arch/$(ARCH)/asm-offsets.h nor include it in any patches.
    Add asm-offsets.h to your don't diff list.

  * In the assembler sources that need offsets, add #include "asm-offsets.h".
    Note that this has no path, the makefile controls where the generated
    code is read from.

  * Specify uses_asm_offsets(object.o) for the objects that include
    asm-offsets.h.  arch/i386/kernel/Makefile.in has

    uses_asm_offsets(entry.o)

    You only need to specify this include/dependency list for the Assembler
    files that use the generated offset values.

  When kbuild 2.5 wants to compile entry.o, it checks if asm-offsets.h is up
  to date.  user_command() says that asm-offsets.h depends on asm-offsets.s.
  asm-offsets.s implicitly depends on asm-offsets.c, there is no need for an
  explicit rule.  Not only does asm-offsets.s directly depend on
  asm-offsets.c, it indirectly depends on all the files included by
  asm-offsets.c, either directly or indirectly, and on the CONFIG_ settings
  in asm-offsets.c and all its included files.

  If anything that affects asm-offsets.s has changed then it is rebuilt, the
  '->' lines are extracted and written to asm-offsets.h.  That will force a
  recompile of the affected assembler objects.  The result is a standard,
  reliable and, above all, an automatic method of converting C values to
  Assembler lines and rebuilding the affected assembler objects.


IDENTIFYING SHADOW FILES

  When you have shadow trees it can be difficult to identify files that have
  been shadowed.  .tmp_filelist.txt in the object directory contains some
  pseudo filenames starting with '/.tmp_shadow' to identify the shadowed
  files.  These pseudo filenames are of the form
    /.tmp_shadow/file/name/nnn xxxxx n xxx
  Only the first and third fields are meaningful for .tmp_shadow entries.
  '/nnn' on the end of the filename gives the shadowed tree number, the third
  field is the number of the tree that is shadowing this file.

  The filelist also contains pseudo filenames to define the source trees
    /.tmp_nametree/directory/name/nnn
  Only the first field is meaningful for tmp_nametree entries.  '/nnn' gives
  the tree number.

  scripts/shadow.pl extracts the tree and shadow data from .tmp_filelist.txt
  and prints one line per shadowed file with five fields.
    file/name m n M N
  m and n are the numbers of the tree being shadowed and the shadowing tree
  respectively.  M and N are the names of the tree being shadowed and the
  shadowing tree respectively.  In most cases you will want to ignore files
  in the base that have been shadowed, i.e. ignore lines where m is 0.

  A filename can appear more than once, it can be shadowed by multiple trees.

  If a file is modified by .prepend or .append then the result is stored in
  the object directory and effectively shadows the original file.  However
  this case is not useful, users need to know the original file.  Generated
  files in the object directory are not included in the tmp_shadow entries.


CONVERTING SHADOW TREES TO A SINGLE SOURCE TREE

  Sometimes you need to convert a shadow tree structure to a single source
  tree.  kbuild has an optional target to do this, $(KBUILD_OBJTREE).tmp_src,
  this target creates directory .tmp_src in the object directory containing a
  forest of symlinks pointing to the relevant source files.  This target is
  optional because creating 10,000+ symlinks is slow.

  You can use $(KBUILD_OBJTREE).tmp_src to generate diffs against your base
  kernel.  This is particularly useful if the base kernel is a read only tree
  so the only changes are in the shadow trees.

  It is possible to edit files in .tmp_src and to apply patches against this
  tree, except when the source file is targeted by .append or .prepend.  When
  a file is appended or prepended, the base version is copied to the object
  directory then updated with the additional text.  The .tmp_src symlink will
  point to the modified copy in the object directory, because that is what
  the kernel was built with.  Any changes to such files will not be reflected
  in the underlying source tree.
