cpumask: introduce new API, without changing anything, v3

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

diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt
index 1ca535bcc8c7d3adeae372d74bdea0fc801a9198..7a7753321a263f62c2a00c9d0e348716e701ac2c 100644 (file)
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -276,40 +276,39 @@ more details, with real examples.
 
 --- 3.7 Compilation flags
 
-    EXTRA_CFLAGS, EXTRA_AFLAGS, EXTRA_LDFLAGS
+    ccflags-y, asflags-y and ldflags-y
+       The three flags listed above applies only to the kbuild makefile
+       where they are assigned. They are used for all the normal
+       cc, as and ld invocation happenign during a recursive build.
+       Note: Flags with the same behaviour were previously named:
+       EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
+       They are yet supported but their use are deprecated.
 
-       All the EXTRA_ variables apply only to the kbuild makefile
-       where they are assigned. The EXTRA_ variables apply to all
-       commands executed in the kbuild makefile.
-
-       $(EXTRA_CFLAGS) specifies options for compiling C files with
-       $(CC).
+       ccflags-y specifies options for compiling C files with $(CC).
 
        Example:
                # drivers/sound/emu10k1/Makefile
-               EXTRA_CFLAGS += -I$(obj)
-               ifdef DEBUG
-                   EXTRA_CFLAGS += -DEMU10K1_DEBUG
-               endif
+               ccflags-y += -I$(obj)
+               ccflags-$(DEBUG) += -DEMU10K1_DEBUG
 
 
        This variable is necessary because the top Makefile owns the
        variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
        entire tree.
 
-       $(EXTRA_AFLAGS) is a similar string for per-directory options
+       asflags-y is a similar string for per-directory options
        when compiling assembly language source.
 
        Example:
                #arch/x86_64/kernel/Makefile
-               EXTRA_AFLAGS := -traditional
+               asflags-y := -traditional
 
 
-       $(EXTRA_LDFLAGS) is a string for per-directory options to $(LD).
+       ldflags-y is a string for per-directory options to $(LD).
 
        Example:
                #arch/m68k/fpsp040/Makefile
-               EXTRA_LDFLAGS := -x
+               ldflags-y := -x
 
     CFLAGS_$@, AFLAGS_$@
 
@@ -424,6 +423,7 @@ more details, with real examples.
        as-instr checks if the assembler reports a specific instruction
        and then outputs either option1 or option2
        C escapes are supported in the test instruction
+       Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options
 
     cc-option
        cc-option is used to check if $(CC) supports a given option, and not
@@ -494,9 +494,9 @@ more details, with real examples.
 
        Example:
                #fs/reiserfs/Makefile
-               EXTRA_CFLAGS := $(call cc-ifversion, -lt, 0402, -O1)
+               ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
 
-       In this example, EXTRA_CFLAGS will be assigned the value -O1 if the
+       In this example, ccflags-y will be assigned the value -O1 if the
        $(CC) version is less than 4.2.
        cc-ifversion takes all the shell operators:
        -eq, -ne, -lt, -le, -gt, and -ge
@@ -518,6 +518,28 @@ more details, with real examples.
        In this example for a specific GCC version the build will error out explaining
        to the user why it stops.
 
+    cc-cross-prefix
+       cc-cross-prefix is used to check if there exists a $(CC) in path with
+       one of the listed prefixes. The first prefix where there exist a
+       prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
+       then nothing is returned.
+       Additional prefixes are separated by a single space in the
+       call of cc-cross-prefix.
+       This functionality is useful for architecture Makefiles that try
+       to set CROSS_COMPILE to well-known values but may have several
+       values to select between.
+       It is recommended only to try to set CROSS_COMPILE if it is a cross
+       build (host arch is different from target arch). And if CROSS_COMPILE
+       is already set then leave it with the old value.
+
+       Example:
+               #arch/m68k/Makefile
+               ifneq ($(SUBARCH),$(ARCH))
+                       ifeq ($(CROSS_COMPILE),)
+                              CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
+                       endif
+               endif
+
 === 4 Host Program support
 
 Kbuild supports building executables on the host for use during the
@@ -782,7 +804,7 @@ When kbuild executes, the following steps are followed (roughly):
        Example:
                #arch/s390/Makefile
                LDFLAGS         := -m elf_s390
-       Note: EXTRA_LDFLAGS can be used to further customise
+       Note: ldflags-y can be used to further customise
        the flags used. See chapter 3.7.
 
     LDFLAGS_MODULE     Options for $(LD) when linking modules
@@ -819,14 +841,14 @@ When kbuild executes, the following steps are followed (roughly):
        In this example, the binary $(obj)/image is a binary version of
        vmlinux. The usage of $(call if_changed,xxx) will be described later.
 
-    AFLAGS             $(AS) assembler flags
+    KBUILD_AFLAGS              $(AS) assembler flags
 
        Default value - see top level Makefile
        Append or modify as required per architecture.
 
        Example:
                #arch/sparc64/Makefile
-               AFLAGS += -m64 -mcpu=ultrasparc
+               KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
 
     KBUILD_CFLAGS              $(CC) compiler flags
 
@@ -1098,8 +1120,8 @@ When kbuild executes, the following steps are followed (roughly):
        specified options when building the target vmlinux.lds.
 
        When building the *.lds target, kbuild uses the variables:
-       CPPFLAGS        : Set in top-level Makefile
-       EXTRA_CPPFLAGS  : May be set in the kbuild makefile
+       KBUILD_CPPFLAGS : Set in top-level Makefile
+       cppflags-y      : May be set in the kbuild makefile
        CPPFLAGS_$(@F)  : Target specific flags.
                          Note that the full filename is used in this
                          assignment.