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