linux 2.6.16.38 w/ vs2.0.3-rc1

[linux-2.6.git] / Documentation / kbuild / makefiles.txt

diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt
index 1075e4d..443230b 100644 (file)
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -6,7 +6,7 @@ This document describes the Linux kernel Makefiles.
 
        === 1 Overview
        === 2 Who does what
-       === 3 The kbuild Makefiles
+       === 3 The kbuild files
           --- 3.1 Goal definitions
           --- 3.2 Built-in object goals - obj-y
           --- 3.3 Loadable module goals - obj-m
@@ -31,7 +31,7 @@ This document describes the Linux kernel Makefiles.
 
        === 6 Architecture Makefiles
           --- 6.1 Set variables to tweak the build to the architecture
-          --- 6.2 Add prerequisites to prepare:
+          --- 6.2 Add prerequisites to archprepare:
           --- 6.3 List directories to visit when descending
           --- 6.4 Architecture specific boot images
           --- 6.5 Building non-kbuild targets
@@ -101,11 +101,14 @@ These people need to know about all aspects of the kernel Makefiles.
 This document is aimed towards normal developers and arch developers.
 
 
-=== 3 The kbuild Makefiles
+=== 3 The kbuild files
 
 Most Makefiles within the kernel are kbuild Makefiles that use the
 kbuild infrastructure. This chapter introduce the syntax used in the
 kbuild makefiles.
+The preferred name for the kbuild files is 'Kbuild' but 'Makefile' will
+continue to be supported. All new developmen is expected to use the
+Kbuild filename.
 
 Section 3.1 "Goal definitions" is a quick intro, further chapters provide
 more details, with real examples.
@@ -707,15 +710,17 @@ When kbuild executes the following steps are followed (roughly):
        probe supported options:
 
                #arch/i386/Makefile
-               check_gcc = $(shell if $(CC) $(1) -S -o /dev/null -xc \
-                           /dev/null\ > /dev/null 2>&1; then echo "$(1)"; \
-                           else echo "$(2)"; fi)
-               cflags-$(CONFIG_MCYRIXIII) += $(call check_gcc,\
-                                                    -march=c3,-march=i486)
 
-               CFLAGS += $(cflags-y)
+               ...
+               cflags-$(CONFIG_MPENTIUMII)     += $(call cc-option,\
+                                               -march=pentium2,-march=i686)
+               ...
+               # Disable unit-at-a-time mode ...
+               CFLAGS += $(call cc-option,-fno-unit-at-a-time)
+               ...
+
 
-       The above examples both utilise the trick that a config option expands
+       The first examples utilises the trick that a config option expands
        to 'y' when selected.
 
     CFLAGS_KERNEL      $(CC) options specific for built-in
@@ -729,18 +734,18 @@ When kbuild executes the following steps are followed (roughly):
        for loadable kernel modules.
 
  
---- 6.2 Add prerequisites to prepare:
+--- 6.2 Add prerequisites to archprepare:
 
-       The prepare: rule is used to list prerequisites that needs to be
+       The archprepare: rule is used to list prerequisites that needs to be
        built before starting to descend down in the subdirectories.
        This is usual header files containing assembler constants.
 
                Example:
-               #arch/s390/Makefile
-               prepare: include/asm-$(ARCH)/offsets.h
+               #arch/arm/Makefile
+               archprepare: maketools
 
-       In this example the file include/asm-$(ARCH)/offsets.h will
-       be built before descending down in the subdirectories.
+       In this example the file target maketools will be processed
+       before descending down in the subdirectories.
        See also chapter XXX-TODO that describe how kbuild supports
        generating offset header files.
 
@@ -867,7 +872,13 @@ When kbuild executes the following steps are followed (roughly):
        Assignments to $(targets) are without $(obj)/ prefix.
        if_changed may be used in conjunction with custom commands as
        defined in 6.7 "Custom kbuild commands".
+
        Note: It is a typical mistake to forget the FORCE prerequisite.
+       Another common pitfall is that whitespace is sometimes
+       significant; for instance, the below will fail (note the extra space
+       after the comma):
+               target: source(s) FORCE
+       #WRONG!#        $(call if_changed, ld/objcopy/gzip)
 
     ld
        Link target. Often LDFLAGS_$@ is used to set specific options to ld.
@@ -997,6 +1008,21 @@ When kbuild executes the following steps are followed (roughly):
        option. When $(biarch) equals to y the expanded variables $(aflags-y)
        and $(cflags-y) will be assigned the values -a32 and -m32.
 
+    cc-option-align
+       gcc version >= 3.0 shifted type of options used to speify
+       alignment of functions, loops etc. $(cc-option-align) whrn used
+       as prefix to the align options will select the right prefix:
+       gcc < 3.00
+               cc-option-align = -malign
+       gcc >= 3.00
+               cc-option-align = -falign
+       
+       Example:
+               CFLAGS += $(cc-option-align)-functions=4
+
+       In the above example the option -falign-functions=4 is used for
+       gcc >= 3.00. For gcc < 3.00 -malign-functions=4 is used.
+       
     cc-version
        cc-version return a numerical version of the $(CC) compiler version.
        The format is <major><minor> where both are two digits. So for example
@@ -1007,9 +1033,9 @@ When kbuild executes the following steps are followed (roughly):
 
        Example:
                #arch/i386/Makefile
-               GCC_VERSION := $(call cc-version)
                cflags-y += $(shell \
-               if [ $(GCC_VERSION) -ge 0300 ] ; then echo "-mregparm=3"; fi ;)
+               if [ $(call cc-version) -ge 0300 ] ; then \
+                       echo "-mregparm=3"; fi ;)
 
        In the above example -mregparm=3 is only used for gcc version greater
        than or equal to gcc 3.0.