linux/Documentation/kbuild/makefiles.txt
<<
>>
Prefs
   1Linux Kernel Makefiles
   2
   3This document describes the Linux kernel Makefiles.
   4
   5=== Table of Contents
   6
   7        === 1 Overview
   8        === 2 Who does what
   9        === 3 The kbuild files
  10           --- 3.1 Goal definitions
  11           --- 3.2 Built-in object goals - obj-y
  12           --- 3.3 Loadable module goals - obj-m
  13           --- 3.4 Objects which export symbols
  14           --- 3.5 Library file goals - lib-y
  15           --- 3.6 Descending down in directories
  16           --- 3.7 Compilation flags
  17           --- 3.8 Command line dependency
  18           --- 3.9 Dependency tracking
  19           --- 3.10 Special Rules
  20           --- 3.11 $(CC) support functions
  21           --- 3.12 $(LD) support functions
  22
  23        === 4 Host Program support
  24           --- 4.1 Simple Host Program
  25           --- 4.2 Composite Host Programs
  26           --- 4.3 Defining shared libraries
  27           --- 4.4 Using C++ for host programs
  28           --- 4.5 Controlling compiler options for host programs
  29           --- 4.6 When host programs are actually built
  30           --- 4.7 Using hostprogs-$(CONFIG_FOO)
  31
  32        === 5 Kbuild clean infrastructure
  33
  34        === 6 Architecture Makefiles
  35           --- 6.1 Set variables to tweak the build to the architecture
  36           --- 6.2 Add prerequisites to archheaders:
  37           --- 6.3 Add prerequisites to archprepare:
  38           --- 6.4 List directories to visit when descending
  39           --- 6.5 Architecture-specific boot images
  40           --- 6.6 Building non-kbuild targets
  41           --- 6.7 Commands useful for building a boot image
  42           --- 6.8 Custom kbuild commands
  43           --- 6.9 Preprocessing linker scripts
  44           --- 6.10 Generic header files
  45
  46        === 7 Kbuild syntax for exported headers
  47                --- 7.1 header-y
  48                --- 7.2 genhdr-y
  49                --- 7.3 destination-y
  50                --- 7.4 generic-y
  51
  52        === 8 Kbuild Variables
  53        === 9 Makefile language
  54        === 10 Credits
  55        === 11 TODO
  56
  57=== 1 Overview
  58
  59The Makefiles have five parts:
  60
  61        Makefile                the top Makefile.
  62        .config                 the kernel configuration file.
  63        arch/$(ARCH)/Makefile   the arch Makefile.
  64        scripts/Makefile.*      common rules etc. for all kbuild Makefiles.
  65        kbuild Makefiles        there are about 500 of these.
  66
  67The top Makefile reads the .config file, which comes from the kernel
  68configuration process.
  69
  70The top Makefile is responsible for building two major products: vmlinux
  71(the resident kernel image) and modules (any module files).
  72It builds these goals by recursively descending into the subdirectories of
  73the kernel source tree.
  74The list of subdirectories which are visited depends upon the kernel
  75configuration. The top Makefile textually includes an arch Makefile
  76with the name arch/$(ARCH)/Makefile. The arch Makefile supplies
  77architecture-specific information to the top Makefile.
  78
  79Each subdirectory has a kbuild Makefile which carries out the commands
  80passed down from above. The kbuild Makefile uses information from the
  81.config file to construct various file lists used by kbuild to build
  82any built-in or modular targets.
  83
  84scripts/Makefile.* contains all the definitions/rules etc. that
  85are used to build the kernel based on the kbuild makefiles.
  86
  87
  88=== 2 Who does what
  89
  90People have four different relationships with the kernel Makefiles.
  91
  92*Users* are people who build kernels.  These people type commands such as
  93"make menuconfig" or "make".  They usually do not read or edit
  94any kernel Makefiles (or any other source files).
  95
  96*Normal developers* are people who work on features such as device
  97drivers, file systems, and network protocols.  These people need to
  98maintain the kbuild Makefiles for the subsystem they are
  99working on.  In order to do this effectively, they need some overall
 100knowledge about the kernel Makefiles, plus detailed knowledge about the
 101public interface for kbuild.
 102
 103*Arch developers* are people who work on an entire architecture, such
 104as sparc or ia64.  Arch developers need to know about the arch Makefile
 105as well as kbuild Makefiles.
 106
 107*Kbuild developers* are people who work on the kernel build system itself.
 108These people need to know about all aspects of the kernel Makefiles.
 109
 110This document is aimed towards normal developers and arch developers.
 111
 112
 113=== 3 The kbuild files
 114
 115Most Makefiles within the kernel are kbuild Makefiles that use the
 116kbuild infrastructure. This chapter introduces the syntax used in the
 117kbuild makefiles.
 118The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
 119be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
 120file will be used.
 121
 122Section 3.1 "Goal definitions" is a quick intro, further chapters provide
 123more details, with real examples.
 124
 125--- 3.1 Goal definitions
 126
 127        Goal definitions are the main part (heart) of the kbuild Makefile.
 128        These lines define the files to be built, any special compilation
 129        options, and any subdirectories to be entered recursively.
 130
 131        The most simple kbuild makefile contains one line:
 132
 133        Example:
 134                obj-y += foo.o
 135
 136        This tells kbuild that there is one object in that directory, named
 137        foo.o. foo.o will be built from foo.c or foo.S.
 138
 139        If foo.o shall be built as a module, the variable obj-m is used.
 140        Therefore the following pattern is often used:
 141
 142        Example:
 143                obj-$(CONFIG_FOO) += foo.o
 144
 145        $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
 146        If CONFIG_FOO is neither y nor m, then the file will not be compiled
 147        nor linked.
 148
 149--- 3.2 Built-in object goals - obj-y
 150
 151        The kbuild Makefile specifies object files for vmlinux
 152        in the $(obj-y) lists.  These lists depend on the kernel
 153        configuration.
 154
 155        Kbuild compiles all the $(obj-y) files.  It then calls
 156        "$(LD) -r" to merge these files into one built-in.o file.
 157        built-in.o is later linked into vmlinux by the parent Makefile.
 158
 159        The order of files in $(obj-y) is significant.  Duplicates in
 160        the lists are allowed: the first instance will be linked into
 161        built-in.o and succeeding instances will be ignored.
 162
 163        Link order is significant, because certain functions
 164        (module_init() / __initcall) will be called during boot in the
 165        order they appear. So keep in mind that changing the link
 166        order may e.g. change the order in which your SCSI
 167        controllers are detected, and thus your disks are renumbered.
 168
 169        Example:
 170                #drivers/isdn/i4l/Makefile
 171                # Makefile for the kernel ISDN subsystem and device drivers.
 172                # Each configuration option enables a list of files.
 173                obj-$(CONFIG_ISDN_I4L)         += isdn.o
 174                obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
 175
 176--- 3.3 Loadable module goals - obj-m
 177
 178        $(obj-m) specify object files which are built as loadable
 179        kernel modules.
 180
 181        A module may be built from one source file or several source
 182        files. In the case of one source file, the kbuild makefile
 183        simply adds the file to $(obj-m).
 184
 185        Example:
 186                #drivers/isdn/i4l/Makefile
 187                obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
 188
 189        Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
 190
 191        If a kernel module is built from several source files, you specify
 192        that you want to build a module in the same way as above; however,
 193        kbuild needs to know which object files you want to build your
 194        module from, so you have to tell it by setting a $(<module_name>-y)
 195        variable.
 196
 197        Example:
 198                #drivers/isdn/i4l/Makefile
 199                obj-$(CONFIG_ISDN_I4L) += isdn.o
 200                isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
 201
 202        In this example, the module name will be isdn.o. Kbuild will
 203        compile the objects listed in $(isdn-y) and then run
 204        "$(LD) -r" on the list of these files to generate isdn.o.
 205
 206        Due to kbuild recognizing $(<module_name>-y) for composite objects,
 207        you can use the value of a CONFIG_ symbol to optionally include an
 208        object file as part of a composite object.
 209
 210        Example:
 211                #fs/ext2/Makefile
 212                obj-$(CONFIG_EXT2_FS) += ext2.o
 213                ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
 214                          namei.o super.o symlink.o
 215                ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \
 216                                                xattr_trusted.o
 217
 218        In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
 219        part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
 220        evaluates to 'y'.
 221
 222        Note: Of course, when you are building objects into the kernel,
 223        the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
 224        kbuild will build an ext2.o file for you out of the individual
 225        parts and then link this into built-in.o, as you would expect.
 226
 227--- 3.4 Objects which export symbols
 228
 229        No special notation is required in the makefiles for
 230        modules exporting symbols.
 231
 232--- 3.5 Library file goals - lib-y
 233
 234        Objects listed with obj-* are used for modules, or
 235        combined in a built-in.o for that specific directory.
 236        There is also the possibility to list objects that will
 237        be included in a library, lib.a.
 238        All objects listed with lib-y are combined in a single
 239        library for that directory.
 240        Objects that are listed in obj-y and additionally listed in
 241        lib-y will not be included in the library, since they will
 242        be accessible anyway.
 243        For consistency, objects listed in lib-m will be included in lib.a.
 244
 245        Note that the same kbuild makefile may list files to be built-in
 246        and to be part of a library. Therefore the same directory
 247        may contain both a built-in.o and a lib.a file.
 248
 249        Example:
 250                #arch/x86/lib/Makefile
 251                lib-y    := delay.o
 252
 253        This will create a library lib.a based on delay.o. For kbuild to
 254        actually recognize that there is a lib.a being built, the directory
 255        shall be listed in libs-y.
 256        See also "6.4 List directories to visit when descending".
 257
 258        Use of lib-y is normally restricted to lib/ and arch/*/lib.
 259
 260--- 3.6 Descending down in directories
 261
 262        A Makefile is only responsible for building objects in its own
 263        directory. Files in subdirectories should be taken care of by
 264        Makefiles in these subdirs. The build system will automatically
 265        invoke make recursively in subdirectories, provided you let it know of
 266        them.
 267
 268        To do so, obj-y and obj-m are used.
 269        ext2 lives in a separate directory, and the Makefile present in fs/
 270        tells kbuild to descend down using the following assignment.
 271
 272        Example:
 273                #fs/Makefile
 274                obj-$(CONFIG_EXT2_FS) += ext2/
 275
 276        If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
 277        the corresponding obj- variable will be set, and kbuild will descend
 278        down in the ext2 directory.
 279        Kbuild only uses this information to decide that it needs to visit
 280        the directory, it is the Makefile in the subdirectory that
 281        specifies what is modules and what is built-in.
 282
 283        It is good practice to use a CONFIG_ variable when assigning directory
 284        names. This allows kbuild to totally skip the directory if the
 285        corresponding CONFIG_ option is neither 'y' nor 'm'.
 286
 287--- 3.7 Compilation flags
 288
 289    ccflags-y, asflags-y and ldflags-y
 290        These three flags apply only to the kbuild makefile in which they
 291        are assigned. They are used for all the normal cc, as and ld
 292        invocations happening during a recursive build.
 293        Note: Flags with the same behaviour were previously named:
 294        EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
 295        They are still supported but their usage is deprecated.
 296
 297        ccflags-y specifies options for compiling with $(CC).
 298
 299        Example:
 300                # drivers/acpi/Makefile
 301                ccflags-y := -Os
 302                ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT
 303
 304        This variable is necessary because the top Makefile owns the
 305        variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
 306        entire tree.
 307
 308        asflags-y specifies options for assembling with $(AS).
 309
 310        Example:
 311                #arch/sparc/kernel/Makefile
 312                asflags-y := -ansi
 313
 314        ldflags-y specifies options for linking with $(LD).
 315
 316        Example:
 317                #arch/cris/boot/compressed/Makefile
 318                ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
 319
 320    subdir-ccflags-y, subdir-asflags-y
 321        The two flags listed above are similar to ccflags-y and asflags-y.
 322        The difference is that the subdir- variants have effect for the kbuild
 323        file where they are present and all subdirectories.
 324        Options specified using subdir-* are added to the commandline before
 325        the options specified using the non-subdir variants.
 326
 327        Example:
 328                subdir-ccflags-y := -Werror
 329
 330    CFLAGS_$@, AFLAGS_$@
 331
 332        CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
 333        kbuild makefile.
 334
 335        $(CFLAGS_$@) specifies per-file options for $(CC).  The $@
 336        part has a literal value which specifies the file that it is for.
 337
 338        Example:
 339                # drivers/scsi/Makefile
 340                CFLAGS_aha152x.o =   -DAHA152X_STAT -DAUTOCONF
 341                CFLAGS_gdth.o    = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
 342                                     -DGDTH_STATISTICS
 343
 344        These two lines specify compilation flags for aha152x.o and gdth.o.
 345
 346        $(AFLAGS_$@) is a similar feature for source files in assembly
 347        languages.
 348
 349        Example:
 350                # arch/arm/kernel/Makefile
 351                AFLAGS_head.o        := -DTEXT_OFFSET=$(TEXT_OFFSET)
 352                AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
 353                AFLAGS_iwmmxt.o      := -Wa,-mcpu=iwmmxt
 354
 355
 356--- 3.9 Dependency tracking
 357
 358        Kbuild tracks dependencies on the following:
 359        1) All prerequisite files (both *.c and *.h)
 360        2) CONFIG_ options used in all prerequisite files
 361        3) Command-line used to compile target
 362
 363        Thus, if you change an option to $(CC) all affected files will
 364        be re-compiled.
 365
 366--- 3.10 Special Rules
 367
 368        Special rules are used when the kbuild infrastructure does
 369        not provide the required support. A typical example is
 370        header files generated during the build process.
 371        Another example are the architecture-specific Makefiles which
 372        need special rules to prepare boot images etc.
 373
 374        Special rules are written as normal Make rules.
 375        Kbuild is not executing in the directory where the Makefile is
 376        located, so all special rules shall provide a relative
 377        path to prerequisite files and target files.
 378
 379        Two variables are used when defining special rules:
 380
 381    $(src)
 382        $(src) is a relative path which points to the directory
 383        where the Makefile is located. Always use $(src) when
 384        referring to files located in the src tree.
 385
 386    $(obj)
 387        $(obj) is a relative path which points to the directory
 388        where the target is saved. Always use $(obj) when
 389        referring to generated files.
 390
 391        Example:
 392                #drivers/scsi/Makefile
 393                $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
 394                        $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
 395
 396        This is a special rule, following the normal syntax
 397        required by make.
 398        The target file depends on two prerequisite files. References
 399        to the target file are prefixed with $(obj), references
 400        to prerequisites are referenced with $(src) (because they are not
 401        generated files).
 402
 403    $(kecho)
 404        echoing information to user in a rule is often a good practice
 405        but when execution "make -s" one does not expect to see any output
 406        except for warnings/errors.
 407        To support this kbuild define $(kecho) which will echo out the
 408        text following $(kecho) to stdout except if "make -s" is used.
 409
 410        Example:
 411                #arch/blackfin/boot/Makefile
 412                $(obj)/vmImage: $(obj)/vmlinux.gz
 413                        $(call if_changed,uimage)
 414                        @$(kecho) 'Kernel: $@ is ready'
 415
 416
 417--- 3.11 $(CC) support functions
 418
 419        The kernel may be built with several different versions of
 420        $(CC), each supporting a unique set of features and options.
 421        kbuild provide basic support to check for valid options for $(CC).
 422        $(CC) is usually the gcc compiler, but other alternatives are
 423        available.
 424
 425    as-option
 426        as-option is used to check if $(CC) -- when used to compile
 427        assembler (*.S) files -- supports the given option. An optional
 428        second option may be specified if the first option is not supported.
 429
 430        Example:
 431                #arch/sh/Makefile
 432                cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
 433
 434        In the above example, cflags-y will be assigned the option
 435        -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
 436        The second argument is optional, and if supplied will be used
 437        if first argument is not supported.
 438
 439    cc-ldoption
 440        cc-ldoption is used to check if $(CC) when used to link object files
 441        supports the given option.  An optional second option may be
 442        specified if first option are not supported.
 443
 444        Example:
 445                #arch/x86/kernel/Makefile
 446                vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
 447
 448        In the above example, vsyscall-flags will be assigned the option
 449        -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
 450        The second argument is optional, and if supplied will be used
 451        if first argument is not supported.
 452
 453    as-instr
 454        as-instr checks if the assembler reports a specific instruction
 455        and then outputs either option1 or option2
 456        C escapes are supported in the test instruction
 457        Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options
 458
 459    cc-option
 460        cc-option is used to check if $(CC) supports a given option, and not
 461        supported to use an optional second option.
 462
 463        Example:
 464                #arch/x86/Makefile
 465                cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
 466
 467        In the above example, cflags-y will be assigned the option
 468        -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
 469        The second argument to cc-option is optional, and if omitted,
 470        cflags-y will be assigned no value if first option is not supported.
 471        Note: cc-option uses KBUILD_CFLAGS for $(CC) options
 472
 473   cc-option-yn
 474        cc-option-yn is used to check if gcc supports a given option
 475        and return 'y' if supported, otherwise 'n'.
 476
 477        Example:
 478                #arch/ppc/Makefile
 479                biarch := $(call cc-option-yn, -m32)
 480                aflags-$(biarch) += -a32
 481                cflags-$(biarch) += -m32
 482
 483        In the above example, $(biarch) is set to y if $(CC) supports the -m32
 484        option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
 485        and $(cflags-y) will be assigned the values -a32 and -m32,
 486        respectively.
 487        Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
 488
 489    cc-option-align
 490        gcc versions >= 3.0 changed the type of options used to specify
 491        alignment of functions, loops etc. $(cc-option-align), when used
 492        as prefix to the align options, will select the right prefix:
 493        gcc < 3.00
 494                cc-option-align = -malign
 495        gcc >= 3.00
 496                cc-option-align = -falign
 497
 498        Example:
 499                KBUILD_CFLAGS += $(cc-option-align)-functions=4
 500
 501        In the above example, the option -falign-functions=4 is used for
 502        gcc >= 3.00. For gcc < 3.00, -malign-functions=4 is used.
 503        Note: cc-option-align uses KBUILD_CFLAGS for $(CC) options
 504
 505    cc-disable-warning
 506        cc-disable-warning checks if gcc supports a given warning and returns
 507        the commandline switch to disable it. This special function is needed,
 508        because gcc 4.4 and later accept any unknown -Wno-* option and only
 509        warn about it if there is another warning in the source file.
 510
 511        Example:
 512                KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)
 513
 514        In the above example, -Wno-unused-but-set-variable will be added to
 515        KBUILD_CFLAGS only if gcc really accepts it.
 516
 517    cc-version
 518        cc-version returns a numerical version of the $(CC) compiler version.
 519        The format is <major><minor> where both are two digits. So for example
 520        gcc 3.41 would return 0341.
 521        cc-version is useful when a specific $(CC) version is faulty in one
 522        area, for example -mregparm=3 was broken in some gcc versions
 523        even though the option was accepted by gcc.
 524
 525        Example:
 526                #arch/x86/Makefile
 527                cflags-y += $(shell \
 528                if [ $(call cc-version) -ge 0300 ] ; then \
 529                        echo "-mregparm=3"; fi ;)
 530
 531        In the above example, -mregparm=3 is only used for gcc version greater
 532        than or equal to gcc 3.0.
 533
 534    cc-ifversion
 535        cc-ifversion tests the version of $(CC) and equals last argument if
 536        version expression is true.
 537
 538        Example:
 539                #fs/reiserfs/Makefile
 540                ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
 541
 542        In this example, ccflags-y will be assigned the value -O1 if the
 543        $(CC) version is less than 4.2.
 544        cc-ifversion takes all the shell operators:
 545        -eq, -ne, -lt, -le, -gt, and -ge
 546        The third parameter may be a text as in this example, but it may also
 547        be an expanded variable or a macro.
 548
 549    cc-fullversion
 550        cc-fullversion is useful when the exact version of gcc is needed.
 551        One typical use-case is when a specific GCC version is broken.
 552        cc-fullversion points out a more specific version than cc-version does.
 553
 554        Example:
 555                #arch/powerpc/Makefile
 556                $(Q)if test "$(call cc-fullversion)" = "040200" ; then \
 557                        echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ; \
 558                        false ; \
 559                fi
 560
 561        In this example for a specific GCC version the build will error out explaining
 562        to the user why it stops.
 563
 564    cc-cross-prefix
 565        cc-cross-prefix is used to check if there exists a $(CC) in path with
 566        one of the listed prefixes. The first prefix where there exist a
 567        prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
 568        then nothing is returned.
 569        Additional prefixes are separated by a single space in the
 570        call of cc-cross-prefix.
 571        This functionality is useful for architecture Makefiles that try
 572        to set CROSS_COMPILE to well-known values but may have several
 573        values to select between.
 574        It is recommended only to try to set CROSS_COMPILE if it is a cross
 575        build (host arch is different from target arch). And if CROSS_COMPILE
 576        is already set then leave it with the old value.
 577
 578        Example:
 579                #arch/m68k/Makefile
 580                ifneq ($(SUBARCH),$(ARCH))
 581                        ifeq ($(CROSS_COMPILE),)
 582                               CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
 583                        endif
 584                endif
 585
 586--- 3.12 $(LD) support functions
 587
 588    ld-option
 589        ld-option is used to check if $(LD) supports the supplied option.
 590        ld-option takes two options as arguments.
 591        The second argument is an optional option that can be used if the
 592        first option is not supported by $(LD).
 593
 594        Example:
 595                #Makefile
 596                LDFLAGS_vmlinux += $(call really-ld-option, -X)
 597
 598
 599=== 4 Host Program support
 600
 601Kbuild supports building executables on the host for use during the
 602compilation stage.
 603Two steps are required in order to use a host executable.
 604
 605The first step is to tell kbuild that a host program exists. This is
 606done utilising the variable hostprogs-y.
 607
 608The second step is to add an explicit dependency to the executable.
 609This can be done in two ways. Either add the dependency in a rule,
 610or utilise the variable $(always).
 611Both possibilities are described in the following.
 612
 613--- 4.1 Simple Host Program
 614
 615        In some cases there is a need to compile and run a program on the
 616        computer where the build is running.
 617        The following line tells kbuild that the program bin2hex shall be
 618        built on the build host.
 619
 620        Example:
 621                hostprogs-y := bin2hex
 622
 623        Kbuild assumes in the above example that bin2hex is made from a single
 624        c-source file named bin2hex.c located in the same directory as
 625        the Makefile.
 626
 627--- 4.2 Composite Host Programs
 628
 629        Host programs can be made up based on composite objects.
 630        The syntax used to define composite objects for host programs is
 631        similar to the syntax used for kernel objects.
 632        $(<executable>-objs) lists all objects used to link the final
 633        executable.
 634
 635        Example:
 636                #scripts/lxdialog/Makefile
 637                hostprogs-y   := lxdialog
 638                lxdialog-objs := checklist.o lxdialog.o
 639
 640        Objects with extension .o are compiled from the corresponding .c
 641        files. In the above example, checklist.c is compiled to checklist.o
 642        and lxdialog.c is compiled to lxdialog.o.
 643        Finally, the two .o files are linked to the executable, lxdialog.
 644        Note: The syntax <executable>-y is not permitted for host-programs.
 645
 646--- 4.3 Defining shared libraries
 647
 648        Objects with extension .so are considered shared libraries, and
 649        will be compiled as position independent objects.
 650        Kbuild provides support for shared libraries, but the usage
 651        shall be restricted.
 652        In the following example the libkconfig.so shared library is used
 653        to link the executable conf.
 654
 655        Example:
 656                #scripts/kconfig/Makefile
 657                hostprogs-y     := conf
 658                conf-objs       := conf.o libkconfig.so
 659                libkconfig-objs := expr.o type.o
 660
 661        Shared libraries always require a corresponding -objs line, and
 662        in the example above the shared library libkconfig is composed by
 663        the two objects expr.o and type.o.
 664        expr.o and type.o will be built as position independent code and
 665        linked as a shared library libkconfig.so. C++ is not supported for
 666        shared libraries.
 667
 668--- 4.4 Using C++ for host programs
 669
 670        kbuild offers support for host programs written in C++. This was
 671        introduced solely to support kconfig, and is not recommended
 672        for general use.
 673
 674        Example:
 675                #scripts/kconfig/Makefile
 676                hostprogs-y   := qconf
 677                qconf-cxxobjs := qconf.o
 678
 679        In the example above the executable is composed of the C++ file
 680        qconf.cc - identified by $(qconf-cxxobjs).
 681
 682        If qconf is composed by a mixture of .c and .cc files, then an
 683        additional line can be used to identify this.
 684
 685        Example:
 686                #scripts/kconfig/Makefile
 687                hostprogs-y   := qconf
 688                qconf-cxxobjs := qconf.o
 689                qconf-objs    := check.o
 690
 691--- 4.5 Controlling compiler options for host programs
 692
 693        When compiling host programs, it is possible to set specific flags.
 694        The programs will always be compiled utilising $(HOSTCC) passed
 695        the options specified in $(HOSTCFLAGS).
 696        To set flags that will take effect for all host programs created
 697        in that Makefile, use the variable HOST_EXTRACFLAGS.
 698
 699        Example:
 700                #scripts/lxdialog/Makefile
 701                HOST_EXTRACFLAGS += -I/usr/include/ncurses
 702
 703        To set specific flags for a single file the following construction
 704        is used:
 705
 706        Example:
 707                #arch/ppc64/boot/Makefile
 708                HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
 709
 710        It is also possible to specify additional options to the linker.
 711
 712        Example:
 713                #scripts/kconfig/Makefile
 714                HOSTLOADLIBES_qconf := -L$(QTDIR)/lib
 715
 716        When linking qconf, it will be passed the extra option
 717        "-L$(QTDIR)/lib".
 718
 719--- 4.6 When host programs are actually built
 720
 721        Kbuild will only build host-programs when they are referenced
 722        as a prerequisite.
 723        This is possible in two ways:
 724
 725        (1) List the prerequisite explicitly in a special rule.
 726
 727        Example:
 728                #drivers/pci/Makefile
 729                hostprogs-y := gen-devlist
 730                $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
 731                        ( cd $(obj); ./gen-devlist ) < $<
 732
 733        The target $(obj)/devlist.h will not be built before
 734        $(obj)/gen-devlist is updated. Note that references to
 735        the host programs in special rules must be prefixed with $(obj).
 736
 737        (2) Use $(always)
 738        When there is no suitable special rule, and the host program
 739        shall be built when a makefile is entered, the $(always)
 740        variable shall be used.
 741
 742        Example:
 743                #scripts/lxdialog/Makefile
 744                hostprogs-y   := lxdialog
 745                always        := $(hostprogs-y)
 746
 747        This will tell kbuild to build lxdialog even if not referenced in
 748        any rule.
 749
 750--- 4.7 Using hostprogs-$(CONFIG_FOO)
 751
 752        A typical pattern in a Kbuild file looks like this:
 753
 754        Example:
 755                #scripts/Makefile
 756                hostprogs-$(CONFIG_KALLSYMS) += kallsyms
 757
 758        Kbuild knows about both 'y' for built-in and 'm' for module.
 759        So if a config symbol evaluate to 'm', kbuild will still build
 760        the binary. In other words, Kbuild handles hostprogs-m exactly
 761        like hostprogs-y. But only hostprogs-y is recommended to be used
 762        when no CONFIG symbols are involved.
 763
 764=== 5 Kbuild clean infrastructure
 765
 766"make clean" deletes most generated files in the obj tree where the kernel
 767is compiled. This includes generated files such as host programs.
 768Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
 769$(extra-y) and $(targets). They are all deleted during "make clean".
 770Files matching the patterns "*.[oas]", "*.ko", plus some additional files
 771generated by kbuild are deleted all over the kernel src tree when
 772"make clean" is executed.
 773
 774Additional files can be specified in kbuild makefiles by use of $(clean-files).
 775
 776        Example:
 777                #drivers/pci/Makefile
 778                clean-files := devlist.h classlist.h
 779
 780When executing "make clean", the two files "devlist.h classlist.h" will
 781be deleted. Kbuild will assume files to be in same relative directory as the
 782Makefile except if an absolute path is specified (path starting with '/').
 783
 784To delete a directory hierarchy use:
 785
 786        Example:
 787                #scripts/package/Makefile
 788                clean-dirs := $(objtree)/debian/
 789
 790This will delete the directory debian, including all subdirectories.
 791Kbuild will assume the directories to be in the same relative path as the
 792Makefile if no absolute path is specified (path does not start with '/').
 793
 794To exclude certain files from make clean, use the $(no-clean-files) variable.
 795This is only a special case used in the top level Kbuild file:
 796
 797        Example:
 798                #Kbuild
 799                no-clean-files := $(bounds-file) $(offsets-file)
 800
 801Usually kbuild descends down in subdirectories due to "obj-* := dir/",
 802but in the architecture makefiles where the kbuild infrastructure
 803is not sufficient this sometimes needs to be explicit.
 804
 805        Example:
 806                #arch/x86/boot/Makefile
 807                subdir- := compressed/
 808
 809The above assignment instructs kbuild to descend down in the
 810directory compressed/ when "make clean" is executed.
 811
 812To support the clean infrastructure in the Makefiles that builds the
 813final bootimage there is an optional target named archclean:
 814
 815        Example:
 816                #arch/x86/Makefile
 817                archclean:
 818                        $(Q)$(MAKE) $(clean)=arch/x86/boot
 819
 820When "make clean" is executed, make will descend down in arch/x86/boot,
 821and clean as usual. The Makefile located in arch/x86/boot/ may use
 822the subdir- trick to descend further down.
 823
 824Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is
 825included in the top level makefile, and the kbuild infrastructure
 826is not operational at that point.
 827
 828Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
 829be visited during "make clean".
 830
 831=== 6 Architecture Makefiles
 832
 833The top level Makefile sets up the environment and does the preparation,
 834before starting to descend down in the individual directories.
 835The top level makefile contains the generic part, whereas
 836arch/$(ARCH)/Makefile contains what is required to set up kbuild
 837for said architecture.
 838To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
 839a few targets.
 840
 841When kbuild executes, the following steps are followed (roughly):
 8421) Configuration of the kernel => produce .config
 8432) Store kernel version in include/linux/version.h
 8443) Symlink include/asm to include/asm-$(ARCH)
 8454) Updating all other prerequisites to the target prepare:
 846   - Additional prerequisites are specified in arch/$(ARCH)/Makefile
 8475) Recursively descend down in all directories listed in
 848   init-* core* drivers-* net-* libs-* and build all targets.
 849   - The values of the above variables are expanded in arch/$(ARCH)/Makefile.
 8506) All object files are then linked and the resulting file vmlinux is
 851   located at the root of the obj tree.
 852   The very first objects linked are listed in head-y, assigned by
 853   arch/$(ARCH)/Makefile.
 8547) Finally, the architecture-specific part does any required post processing
 855   and builds the final bootimage.
 856   - This includes building boot records
 857   - Preparing initrd images and the like
 858
 859
 860--- 6.1 Set variables to tweak the build to the architecture
 861
 862    LDFLAGS             Generic $(LD) options
 863
 864        Flags used for all invocations of the linker.
 865        Often specifying the emulation is sufficient.
 866
 867        Example:
 868                #arch/s390/Makefile
 869                LDFLAGS         := -m elf_s390
 870        Note: ldflags-y can be used to further customise
 871        the flags used. See chapter 3.7.
 872
 873    LDFLAGS_MODULE      Options for $(LD) when linking modules
 874
 875        LDFLAGS_MODULE is used to set specific flags for $(LD) when
 876        linking the .ko files used for modules.
 877        Default is "-r", for relocatable output.
 878
 879    LDFLAGS_vmlinux     Options for $(LD) when linking vmlinux
 880
 881        LDFLAGS_vmlinux is used to specify additional flags to pass to
 882        the linker when linking the final vmlinux image.
 883        LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
 884
 885        Example:
 886                #arch/x86/Makefile
 887                LDFLAGS_vmlinux := -e stext
 888
 889    OBJCOPYFLAGS        objcopy flags
 890
 891        When $(call if_changed,objcopy) is used to translate a .o file,
 892        the flags specified in OBJCOPYFLAGS will be used.
 893        $(call if_changed,objcopy) is often used to generate raw binaries on
 894        vmlinux.
 895
 896        Example:
 897                #arch/s390/Makefile
 898                OBJCOPYFLAGS := -O binary
 899
 900                #arch/s390/boot/Makefile
 901                $(obj)/image: vmlinux FORCE
 902                        $(call if_changed,objcopy)
 903
 904        In this example, the binary $(obj)/image is a binary version of
 905        vmlinux. The usage of $(call if_changed,xxx) will be described later.
 906
 907    KBUILD_AFLAGS               $(AS) assembler flags
 908
 909        Default value - see top level Makefile
 910        Append or modify as required per architecture.
 911
 912        Example:
 913                #arch/sparc64/Makefile
 914                KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
 915
 916    KBUILD_CFLAGS               $(CC) compiler flags
 917
 918        Default value - see top level Makefile
 919        Append or modify as required per architecture.
 920
 921        Often, the KBUILD_CFLAGS variable depends on the configuration.
 922
 923        Example:
 924                #arch/x86/Makefile
 925                cflags-$(CONFIG_M386) += -march=i386
 926                KBUILD_CFLAGS += $(cflags-y)
 927
 928        Many arch Makefiles dynamically run the target C compiler to
 929        probe supported options:
 930
 931                #arch/x86/Makefile
 932
 933                ...
 934                cflags-$(CONFIG_MPENTIUMII)     += $(call cc-option,\
 935                                                -march=pentium2,-march=i686)
 936                ...
 937                # Disable unit-at-a-time mode ...
 938                KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
 939                ...
 940
 941
 942        The first example utilises the trick that a config option expands
 943        to 'y' when selected.
 944
 945    KBUILD_AFLAGS_KERNEL        $(AS) options specific for built-in
 946
 947        $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
 948        resident kernel code.
 949
 950    KBUILD_AFLAGS_MODULE   Options for $(AS) when building modules
 951
 952        $(KBUILD_AFLAGS_MODULE) is used to add arch specific options that
 953        are used for $(AS).
 954        From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
 955
 956    KBUILD_CFLAGS_KERNEL        $(CC) options specific for built-in
 957
 958        $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
 959        resident kernel code.
 960
 961    KBUILD_CFLAGS_MODULE   Options for $(CC) when building modules
 962
 963        $(KBUILD_CFLAGS_MODULE) is used to add arch specific options that
 964        are used for $(CC).
 965        From commandline CFLAGS_MODULE shall be used (see kbuild.txt).
 966
 967    KBUILD_LDFLAGS_MODULE   Options for $(LD) when linking modules
 968
 969        $(KBUILD_LDFLAGS_MODULE) is used to add arch specific options
 970        used when linking modules. This is often a linker script.
 971        From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).
 972
 973    KBUILD_ARFLAGS   Options for $(AR) when creating archives
 974
 975        $(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic
 976        mode) if this option is supported by $(AR).
 977
 978--- 6.2 Add prerequisites to archheaders:
 979
 980        The archheaders: rule is used to generate header files that
 981        may be installed into user space by "make header_install" or
 982        "make headers_install_all".  In order to support
 983        "make headers_install_all", this target has to be able to run
 984        on an unconfigured tree, or a tree configured for another
 985        architecture.
 986
 987        It is run before "make archprepare" when run on the
 988        architecture itself.
 989
 990
 991--- 6.3 Add prerequisites to archprepare:
 992
 993        The archprepare: rule is used to list prerequisites that need to be
 994        built before starting to descend down in the subdirectories.
 995        This is usually used for header files containing assembler constants.
 996
 997                Example:
 998                #arch/arm/Makefile
 999                archprepare: maketools
1000
1001        In this example, the file target maketools will be processed
1002        before descending down in the subdirectories.
1003        See also chapter XXX-TODO that describe how kbuild supports
1004        generating offset header files.
1005
1006
1007--- 6.4 List directories to visit when descending
1008
1009        An arch Makefile cooperates with the top Makefile to define variables
1010        which specify how to build the vmlinux file.  Note that there is no
1011        corresponding arch-specific section for modules; the module-building
1012        machinery is all architecture-independent.
1013
1014
1015    head-y, init-y, core-y, libs-y, drivers-y, net-y
1016
1017        $(head-y) lists objects to be linked first in vmlinux.
1018        $(libs-y) lists directories where a lib.a archive can be located.
1019        The rest list directories where a built-in.o object file can be
1020        located.
1021
1022        $(init-y) objects will be located after $(head-y).
1023        Then the rest follows in this order:
1024        $(core-y), $(libs-y), $(drivers-y) and $(net-y).
1025
1026        The top level Makefile defines values for all generic directories,
1027        and arch/$(ARCH)/Makefile only adds architecture-specific directories.
1028
1029        Example:
1030                #arch/sparc64/Makefile
1031                core-y += arch/sparc64/kernel/
1032                libs-y += arch/sparc64/prom/ arch/sparc64/lib/
1033                drivers-$(CONFIG_OPROFILE)  += arch/sparc64/oprofile/
1034
1035
1036--- 6.5 Architecture-specific boot images
1037
1038        An arch Makefile specifies goals that take the vmlinux file, compress
1039        it, wrap it in bootstrapping code, and copy the resulting files
1040        somewhere. This includes various kinds of installation commands.
1041        The actual goals are not standardized across architectures.
1042
1043        It is common to locate any additional processing in a boot/
1044        directory below arch/$(ARCH)/.
1045
1046        Kbuild does not provide any smart way to support building a
1047        target specified in boot/. Therefore arch/$(ARCH)/Makefile shall
1048        call make manually to build a target in boot/.
1049
1050        The recommended approach is to include shortcuts in
1051        arch/$(ARCH)/Makefile, and use the full path when calling down
1052        into the arch/$(ARCH)/boot/Makefile.
1053
1054        Example:
1055                #arch/x86/Makefile
1056                boot := arch/x86/boot
1057                bzImage: vmlinux
1058                        $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@
1059
1060        "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
1061        make in a subdirectory.
1062
1063        There are no rules for naming architecture-specific targets,
1064        but executing "make help" will list all relevant targets.
1065        To support this, $(archhelp) must be defined.
1066
1067        Example:
1068                #arch/x86/Makefile
1069                define archhelp
1070                  echo  '* bzImage      - Image (arch/$(ARCH)/boot/bzImage)'
1071                endif
1072
1073        When make is executed without arguments, the first goal encountered
1074        will be built. In the top level Makefile the first goal present
1075        is all:.
1076        An architecture shall always, per default, build a bootable image.
1077        In "make help", the default goal is highlighted with a '*'.
1078        Add a new prerequisite to all: to select a default goal different
1079        from vmlinux.
1080
1081        Example:
1082                #arch/x86/Makefile
1083                all: bzImage
1084
1085        When "make" is executed without arguments, bzImage will be built.
1086
1087--- 6.6 Building non-kbuild targets
1088
1089    extra-y
1090
1091        extra-y specify additional targets created in the current
1092        directory, in addition to any targets specified by obj-*.
1093
1094        Listing all targets in extra-y is required for two purposes:
1095        1) Enable kbuild to check changes in command lines
1096           - When $(call if_changed,xxx) is used
1097        2) kbuild knows what files to delete during "make clean"
1098
1099        Example:
1100                #arch/x86/kernel/Makefile
1101                extra-y := head.o init_task.o
1102
1103        In this example, extra-y is used to list object files that
1104        shall be built, but shall not be linked as part of built-in.o.
1105
1106
1107--- 6.7 Commands useful for building a boot image
1108
1109        Kbuild provides a few macros that are useful when building a
1110        boot image.
1111
1112    if_changed
1113
1114        if_changed is the infrastructure used for the following commands.
1115
1116        Usage:
1117                target: source(s) FORCE
1118                        $(call if_changed,ld/objcopy/gzip)
1119
1120        When the rule is evaluated, it is checked to see if any files
1121        need an update, or the command line has changed since the last
1122        invocation. The latter will force a rebuild if any options
1123        to the executable have changed.
1124        Any target that utilises if_changed must be listed in $(targets),
1125        otherwise the command line check will fail, and the target will
1126        always be built.
1127        Assignments to $(targets) are without $(obj)/ prefix.
1128        if_changed may be used in conjunction with custom commands as
1129        defined in 6.8 "Custom kbuild commands".
1130
1131        Note: It is a typical mistake to forget the FORCE prerequisite.
1132        Another common pitfall is that whitespace is sometimes
1133        significant; for instance, the below will fail (note the extra space
1134        after the comma):
1135                target: source(s) FORCE
1136        #WRONG!#        $(call if_changed, ld/objcopy/gzip)
1137
1138    ld
1139        Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1140
1141    objcopy
1142        Copy binary. Uses OBJCOPYFLAGS usually specified in
1143        arch/$(ARCH)/Makefile.
1144        OBJCOPYFLAGS_$@ may be used to set additional options.
1145
1146    gzip
1147        Compress target. Use maximum compression to compress target.
1148
1149        Example:
1150                #arch/x86/boot/Makefile
1151                LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
1152                LDFLAGS_setup    := -Ttext 0x0 -s --oformat binary -e begtext
1153
1154                targets += setup setup.o bootsect bootsect.o
1155                $(obj)/setup $(obj)/bootsect: %: %.o FORCE
1156                        $(call if_changed,ld)
1157
1158        In this example, there are two possible targets, requiring different
1159        options to the linker. The linker options are specified using the
1160        LDFLAGS_$@ syntax - one for each potential target.
1161        $(targets) are assigned all potential targets, by which kbuild knows
1162        the targets and will:
1163                1) check for commandline changes
1164                2) delete target during make clean
1165
1166        The ": %: %.o" part of the prerequisite is a shorthand that
1167        free us from listing the setup.o and bootsect.o files.
1168        Note: It is a common mistake to forget the "target :=" assignment,
1169              resulting in the target file being recompiled for no
1170              obvious reason.
1171
1172    dtc
1173        Create flattend device tree blob object suitable for linking
1174        into vmlinux. Device tree blobs linked into vmlinux are placed
1175        in an init section in the image. Platform code *must* copy the
1176        blob to non-init memory prior to calling unflatten_device_tree().
1177
1178        Example:
1179                #arch/x86/platform/ce4100/Makefile
1180                clean-files := *dtb.S
1181
1182                DTC_FLAGS := -p 1024
1183                obj-y += foo.dtb.o
1184
1185                $(obj)/%.dtb: $(src)/%.dts
1186                        $(call cmd,dtc)
1187
1188--- 6.8 Custom kbuild commands
1189
1190        When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
1191        of a command is normally displayed.
1192        To enable this behaviour for custom commands kbuild requires
1193        two variables to be set:
1194        quiet_cmd_<command>     - what shall be echoed
1195              cmd_<command>     - the command to execute
1196
1197        Example:
1198                #
1199                quiet_cmd_image = BUILD   $@
1200                      cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
1201                                                     $(obj)/vmlinux.bin > $@
1202
1203                targets += bzImage
1204                $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
1205                        $(call if_changed,image)
1206                        @echo 'Kernel: $@ is ready'
1207
1208        When updating the $(obj)/bzImage target, the line
1209
1210        BUILD    arch/x86/boot/bzImage
1211
1212        will be displayed with "make KBUILD_VERBOSE=0".
1213
1214
1215--- 6.9 Preprocessing linker scripts
1216
1217        When the vmlinux image is built, the linker script
1218        arch/$(ARCH)/kernel/vmlinux.lds is used.
1219        The script is a preprocessed variant of the file vmlinux.lds.S
1220        located in the same directory.
1221        kbuild knows .lds files and includes a rule *lds.S -> *lds.
1222
1223        Example:
1224                #arch/x86/kernel/Makefile
1225                always := vmlinux.lds
1226
1227                #Makefile
1228                export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
1229
1230        The assignment to $(always) is used to tell kbuild to build the
1231        target vmlinux.lds.
1232        The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
1233        specified options when building the target vmlinux.lds.
1234
1235        When building the *.lds target, kbuild uses the variables:
1236        KBUILD_CPPFLAGS : Set in top-level Makefile
1237        cppflags-y      : May be set in the kbuild makefile
1238        CPPFLAGS_$(@F)  : Target specific flags.
1239                          Note that the full filename is used in this
1240                          assignment.
1241
1242        The kbuild infrastructure for *lds file are used in several
1243        architecture-specific files.
1244
1245--- 6.10 Generic header files
1246
1247        The directory include/asm-generic contains the header files
1248        that may be shared between individual architectures.
1249        The recommended approach how to use a generic header file is
1250        to list the file in the Kbuild file.
1251        See "7.4 generic-y" for further info on syntax etc.
1252
1253=== 7 Kbuild syntax for exported headers
1254
1255The kernel include a set of headers that is exported to userspace.
1256Many headers can be exported as-is but other headers require a
1257minimal pre-processing before they are ready for user-space.
1258The pre-processing does:
1259- drop kernel specific annotations
1260- drop include of compiler.h
1261- drop all sections that are kernel internal (guarded by ifdef __KERNEL__)
1262
1263Each relevant directory contains a file name "Kbuild" which specifies the
1264headers to be exported.
1265See subsequent chapter for the syntax of the Kbuild file.
1266
1267        --- 7.1 header-y
1268
1269        header-y specify header files to be exported.
1270
1271                Example:
1272                        #include/linux/Kbuild
1273                        header-y += usb/
1274                        header-y += aio_abi.h
1275
1276        The convention is to list one file per line and
1277        preferably in alphabetic order.
1278
1279        header-y also specify which subdirectories to visit.
1280        A subdirectory is identified by a trailing '/' which
1281        can be seen in the example above for the usb subdirectory.
1282
1283        Subdirectories are visited before their parent directories.
1284
1285        --- 7.2 genhdr-y
1286
1287        genhdr-y specifies generated files to be exported.
1288        Generated files are special as they need to be looked
1289        up in another directory when doing 'make O=...' builds.
1290
1291                Example:
1292                        #include/linux/Kbuild
1293                        genhdr-y += version.h
1294
1295        --- 7.3 destination-y
1296
1297        When an architecture have a set of exported headers that needs to be
1298        exported to a different directory destination-y is used.
1299        destination-y specify the destination directory for all exported
1300        headers in the file where it is present.
1301
1302                Example:
1303                        #arch/xtensa/platforms/s6105/include/platform/Kbuild
1304                        destination-y := include/linux
1305
1306        In the example above all exported headers in the Kbuild file
1307        will be located in the directory "include/linux" when exported.
1308
1309        --- 7.4 generic-y
1310
1311        If an architecture uses a verbatim copy of a header from
1312        include/asm-generic then this is listed in the file
1313        arch/$(ARCH)/include/asm/Kbuild like this:
1314
1315                Example:
1316                        #arch/x86/include/asm/Kbuild
1317                        generic-y += termios.h
1318                        generic-y += rtc.h
1319
1320        During the prepare phase of the build a wrapper include
1321        file is generated in the directory:
1322
1323                arch/$(ARCH)/include/generated/asm
1324
1325        When a header is exported where the architecture uses
1326        the generic header a similar wrapper is generated as part
1327        of the set of exported headers in the directory:
1328
1329                usr/include/asm
1330
1331        The generated wrapper will in both cases look like the following:
1332
1333                Example: termios.h
1334                        #include <asm-generic/termios.h>
1335
1336=== 8 Kbuild Variables
1337
1338The top Makefile exports the following variables:
1339
1340    VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
1341
1342        These variables define the current kernel version.  A few arch
1343        Makefiles actually use these values directly; they should use
1344        $(KERNELRELEASE) instead.
1345
1346        $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
1347        three-part version number, such as "2", "4", and "0".  These three
1348        values are always numeric.
1349
1350        $(EXTRAVERSION) defines an even tinier sublevel for pre-patches
1351        or additional patches.  It is usually some non-numeric string
1352        such as "-pre4", and is often blank.
1353
1354    KERNELRELEASE
1355
1356        $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
1357        for constructing installation directory names or showing in
1358        version strings.  Some arch Makefiles use it for this purpose.
1359
1360    ARCH
1361
1362        This variable defines the target architecture, such as "i386",
1363        "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
1364        determine which files to compile.
1365
1366        By default, the top Makefile sets $(ARCH) to be the same as the
1367        host system architecture.  For a cross build, a user may
1368        override the value of $(ARCH) on the command line:
1369
1370            make ARCH=m68k ...
1371
1372
1373    INSTALL_PATH
1374
1375        This variable defines a place for the arch Makefiles to install
1376        the resident kernel image and System.map file.
1377        Use this for architecture-specific install targets.
1378
1379    INSTALL_MOD_PATH, MODLIB
1380
1381        $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
1382        installation.  This variable is not defined in the Makefile but
1383        may be passed in by the user if desired.
1384
1385        $(MODLIB) specifies the directory for module installation.
1386        The top Makefile defines $(MODLIB) to
1387        $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE).  The user may
1388        override this value on the command line if desired.
1389
1390    INSTALL_MOD_STRIP
1391
1392        If this variable is specified, will cause modules to be stripped
1393        after they are installed.  If INSTALL_MOD_STRIP is '1', then the
1394        default option --strip-debug will be used.  Otherwise,
1395        INSTALL_MOD_STRIP value will be used as the option(s) to the strip
1396        command.
1397
1398
1399=== 9 Makefile language
1400
1401The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
1402use only the documented features of GNU Make, but they do use many
1403GNU extensions.
1404
1405GNU Make supports elementary list-processing functions.  The kernel
1406Makefiles use a novel style of list building and manipulation with few
1407"if" statements.
1408
1409GNU Make has two assignment operators, ":=" and "=".  ":=" performs
1410immediate evaluation of the right-hand side and stores an actual string
1411into the left-hand side.  "=" is like a formula definition; it stores the
1412right-hand side in an unevaluated form and then evaluates this form each
1413time the left-hand side is used.
1414
1415There are some cases where "=" is appropriate.  Usually, though, ":="
1416is the right choice.
1417
1418=== 10 Credits
1419
1420Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1421Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1422Updates by Sam Ravnborg <sam@ravnborg.org>
1423Language QA by Jan Engelhardt <jengelh@gmx.de>
1424
1425=== 11 TODO
1426
1427- Describe how kbuild supports shipped files with _shipped.
1428- Generating offset header files.
1429- Add more variables to section 7?
1430
1431
1432
1433
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.