kbuild: enable 'make CFLAGS=...' to add additional options to CC

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

diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt
index bb5306e9a5c331c781aceef4d168c8710d482cb4..1ca535bcc8c7d3adeae372d74bdea0fc801a9198 100644 (file)
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -276,7 +276,7 @@ more details, with real examples.
 
 --- 3.7 Compilation flags
 
-    EXTRA_CFLAGS, EXTRA_AFLAGS, EXTRA_LDFLAGS, EXTRA_ARFLAGS
+    EXTRA_CFLAGS, EXTRA_AFLAGS, EXTRA_LDFLAGS
 
        All the EXTRA_ variables apply only to the kbuild makefile
        where they are assigned. The EXTRA_ variables apply to all
@@ -294,7 +294,7 @@ more details, with real examples.
 
 
        This variable is necessary because the top Makefile owns the
-       variable $(CFLAGS) and uses it for compilation flags for the
+       variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
        entire tree.
 
        $(EXTRA_AFLAGS) is a similar string for per-directory options
@@ -305,8 +305,7 @@ more details, with real examples.
                EXTRA_AFLAGS := -traditional
 
 
-       $(EXTRA_LDFLAGS) and $(EXTRA_ARFLAGS) are similar strings for
-       per-directory options to $(LD) and $(AR).
+       $(EXTRA_LDFLAGS) is a string for per-directory options to $(LD).
 
        Example:
                #arch/m68k/fpsp040/Makefile
@@ -438,6 +437,7 @@ more details, with real examples.
        -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
        The second argument to cc-option is optional, and if omitted,
        cflags-y will be assigned no value if first option is not supported.
+       Note: cc-option uses KBUILD_CFLAGS for $(CC) options
 
    cc-option-yn
        cc-option-yn is used to check if gcc supports a given option
@@ -453,6 +453,7 @@ more details, with real examples.
        option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
        and $(cflags-y) will be assigned the values -a32 and -m32,
        respectively.
+       Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
 
     cc-option-align
        gcc versions >= 3.0 changed the type of options used to specify
@@ -464,10 +465,11 @@ more details, with real examples.
                cc-option-align = -falign
 
        Example:
-               CFLAGS += $(cc-option-align)-functions=4
+               KBUILD_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.
+       Note: cc-option-align uses KBUILD_CFLAGS for $(CC) options
 
     cc-version
        cc-version returns a numerical version of the $(CC) compiler version.
@@ -501,6 +503,20 @@ more details, with real examples.
        The third parameter may be a text as in this example, but it may also
        be an expanded variable or a macro.
 
+    cc-fullversion
+       cc-fullversion is useful when the exact version of gcc is needed.
+       One typical use-case is when a specific GCC version is broken.
+       cc-fullversion points out a more specific version than cc-version does.
+
+       Example:
+               #arch/powerpc/Makefile
+               $(Q)if test "$(call cc-fullversion)" = "040200" ; then \
+                       echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ; \
+                       false ; \
+               fi
+
+       In this example for a specific GCC version the build will error out explaining
+       to the user why it stops.
 
 === 4 Host Program support
 
@@ -766,8 +782,8 @@ When kbuild executes, the following steps are followed (roughly):
        Example:
                #arch/s390/Makefile
                LDFLAGS         := -m elf_s390
-       Note: EXTRA_LDFLAGS and LDFLAGS_$@ can be used to further customise
-       the flags used. See chapter 7.
+       Note: EXTRA_LDFLAGS can be used to further customise
+       the flags used. See chapter 3.7.
 
     LDFLAGS_MODULE     Options for $(LD) when linking modules
 
@@ -812,17 +828,17 @@ When kbuild executes, the following steps are followed (roughly):
                #arch/sparc64/Makefile
                AFLAGS += -m64 -mcpu=ultrasparc
 
-    CFLAGS             $(CC) compiler flags
+    KBUILD_CFLAGS              $(CC) compiler flags
 
        Default value - see top level Makefile
        Append or modify as required per architecture.
 
-       Often, the CFLAGS variable depends on the configuration.
+       Often, the KBUILD_CFLAGS variable depends on the configuration.
 
        Example:
                #arch/i386/Makefile
                cflags-$(CONFIG_M386) += -march=i386
-               CFLAGS += $(cflags-y)
+               KBUILD_CFLAGS += $(cflags-y)
 
        Many arch Makefiles dynamically run the target C compiler to
        probe supported options:
@@ -834,7 +850,7 @@ When kbuild executes, the following steps are followed (roughly):
                                                -march=pentium2,-march=i686)
                ...
                # Disable unit-at-a-time mode ...
-               CFLAGS += $(call cc-option,-fno-unit-at-a-time)
+               KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
                ...