1670 lines · plain
1======================2Linux Kernel Makefiles3======================4 5This document describes the Linux kernel Makefiles.6 7Overview8========9 10The Makefiles have five parts::11 12 Makefile the top Makefile.13 .config the kernel configuration file.14 arch/$(SRCARCH)/Makefile the arch Makefile.15 scripts/Makefile.* common rules etc. for all kbuild Makefiles.16 kbuild Makefiles exist in every subdirectory17 18The top Makefile reads the .config file, which comes from the kernel19configuration process.20 21The top Makefile is responsible for building two major products: vmlinux22(the resident kernel image) and modules (any module files).23It builds these goals by recursively descending into the subdirectories of24the kernel source tree.25 26The list of subdirectories which are visited depends upon the kernel27configuration. The top Makefile textually includes an arch Makefile28with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies29architecture-specific information to the top Makefile.30 31Each subdirectory has a kbuild Makefile which carries out the commands32passed down from above. The kbuild Makefile uses information from the33.config file to construct various file lists used by kbuild to build34any built-in or modular targets.35 36scripts/Makefile.* contains all the definitions/rules etc. that37are used to build the kernel based on the kbuild makefiles.38 39Who does what40=============41 42People have four different relationships with the kernel Makefiles.43 44*Users* are people who build kernels. These people type commands such as45``make menuconfig`` or ``make``. They usually do not read or edit46any kernel Makefiles (or any other source files).47 48*Normal developers* are people who work on features such as device49drivers, file systems, and network protocols. These people need to50maintain the kbuild Makefiles for the subsystem they are51working on. In order to do this effectively, they need some overall52knowledge about the kernel Makefiles, plus detailed knowledge about the53public interface for kbuild.54 55*Arch developers* are people who work on an entire architecture, such56as sparc or x86. Arch developers need to know about the arch Makefile57as well as kbuild Makefiles.58 59*Kbuild developers* are people who work on the kernel build system itself.60These people need to know about all aspects of the kernel Makefiles.61 62This document is aimed towards normal developers and arch developers.63 64 65The kbuild files66================67 68Most Makefiles within the kernel are kbuild Makefiles that use the69kbuild infrastructure. This chapter introduces the syntax used in the70kbuild makefiles.71 72The preferred name for the kbuild files are ``Makefile`` but ``Kbuild`` can73be used and if both a ``Makefile`` and a ``Kbuild`` file exists, then the ``Kbuild``74file will be used.75 76Section `Goal definitions`_ is a quick intro; further chapters provide77more details, with real examples.78 79Goal definitions80----------------81 82Goal definitions are the main part (heart) of the kbuild Makefile.83These lines define the files to be built, any special compilation84options, and any subdirectories to be entered recursively.85 86The most simple kbuild makefile contains one line:87 88Example::89 90 obj-y += foo.o91 92This tells kbuild that there is one object in that directory, named93foo.o. foo.o will be built from foo.c or foo.S.94 95If foo.o shall be built as a module, the variable obj-m is used.96Therefore the following pattern is often used:97 98Example::99 100 obj-$(CONFIG_FOO) += foo.o101 102$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).103If CONFIG_FOO is neither y nor m, then the file will not be compiled104nor linked.105 106Built-in object goals - obj-y107-----------------------------108 109The kbuild Makefile specifies object files for vmlinux110in the $(obj-y) lists. These lists depend on the kernel111configuration.112 113Kbuild compiles all the $(obj-y) files. It then calls114``$(AR) rcSTP`` to merge these files into one built-in.a file.115This is a thin archive without a symbol table. It will be later116linked into vmlinux by scripts/link-vmlinux.sh117 118The order of files in $(obj-y) is significant. Duplicates in119the lists are allowed: the first instance will be linked into120built-in.a and succeeding instances will be ignored.121 122Link order is significant, because certain functions123(module_init() / __initcall) will be called during boot in the124order they appear. So keep in mind that changing the link125order may e.g. change the order in which your SCSI126controllers are detected, and thus your disks are renumbered.127 128Example::129 130 #drivers/isdn/i4l/Makefile131 # Makefile for the kernel ISDN subsystem and device drivers.132 # Each configuration option enables a list of files.133 obj-$(CONFIG_ISDN_I4L) += isdn.o134 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o135 136Loadable module goals - obj-m137-----------------------------138 139$(obj-m) specifies object files which are built as loadable140kernel modules.141 142A module may be built from one source file or several source143files. In the case of one source file, the kbuild makefile144simply adds the file to $(obj-m).145 146Example::147 148 #drivers/isdn/i4l/Makefile149 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o150 151Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to "m"152 153If a kernel module is built from several source files, you specify154that you want to build a module in the same way as above; however,155kbuild needs to know which object files you want to build your156module from, so you have to tell it by setting a $(<module_name>-y)157variable.158 159Example::160 161 #drivers/isdn/i4l/Makefile162 obj-$(CONFIG_ISDN_I4L) += isdn.o163 isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o164 165In this example, the module name will be isdn.o. Kbuild will166compile the objects listed in $(isdn-y) and then run167``$(LD) -r`` on the list of these files to generate isdn.o.168 169Due to kbuild recognizing $(<module_name>-y) for composite objects,170you can use the value of a ``CONFIG_`` symbol to optionally include an171object file as part of a composite object.172 173Example::174 175 #fs/ext2/Makefile176 obj-$(CONFIG_EXT2_FS) += ext2.o177 ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \178 namei.o super.o symlink.o179 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \180 xattr_trusted.o181 182In this example, xattr.o, xattr_user.o and xattr_trusted.o are only183part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)184evaluates to "y".185 186Note: Of course, when you are building objects into the kernel,187the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,188kbuild will build an ext2.o file for you out of the individual189parts and then link this into built-in.a, as you would expect.190 191Library file goals - lib-y192--------------------------193 194Objects listed with obj-* are used for modules, or195combined in a built-in.a for that specific directory.196There is also the possibility to list objects that will197be included in a library, lib.a.198All objects listed with lib-y are combined in a single199library for that directory.200Objects that are listed in obj-y and additionally listed in201lib-y will not be included in the library, since they will202be accessible anyway.203For consistency, objects listed in lib-m will be included in lib.a.204 205Note that the same kbuild makefile may list files to be built-in206and to be part of a library. Therefore the same directory207may contain both a built-in.a and a lib.a file.208 209Example::210 211 #arch/x86/lib/Makefile212 lib-y := delay.o213 214This will create a library lib.a based on delay.o. For kbuild to215actually recognize that there is a lib.a being built, the directory216shall be listed in libs-y.217 218See also `List directories to visit when descending`_.219 220Use of lib-y is normally restricted to ``lib/`` and ``arch/*/lib``.221 222Descending down in directories223------------------------------224 225A Makefile is only responsible for building objects in its own226directory. Files in subdirectories should be taken care of by227Makefiles in these subdirs. The build system will automatically228invoke make recursively in subdirectories, provided you let it know of229them.230 231To do so, obj-y and obj-m are used.232ext2 lives in a separate directory, and the Makefile present in fs/233tells kbuild to descend down using the following assignment.234 235Example::236 237 #fs/Makefile238 obj-$(CONFIG_EXT2_FS) += ext2/239 240If CONFIG_EXT2_FS is set to either "y" (built-in) or "m" (modular)241the corresponding obj- variable will be set, and kbuild will descend242down in the ext2 directory.243 244Kbuild uses this information not only to decide that it needs to visit245the directory, but also to decide whether or not to link objects from246the directory into vmlinux.247 248When Kbuild descends into the directory with "y", all built-in objects249from that directory are combined into the built-in.a, which will be250eventually linked into vmlinux.251 252When Kbuild descends into the directory with "m", in contrast, nothing253from that directory will be linked into vmlinux. If the Makefile in254that directory specifies obj-y, those objects will be left orphan.255It is very likely a bug of the Makefile or of dependencies in Kconfig.256 257Kbuild also supports dedicated syntax, subdir-y and subdir-m, for258descending into subdirectories. It is a good fit when you know they259do not contain kernel-space objects at all. A typical usage is to let260Kbuild descend into subdirectories to build tools.261 262Examples::263 264 # scripts/Makefile265 subdir-$(CONFIG_GCC_PLUGINS) += gcc-plugins266 subdir-$(CONFIG_MODVERSIONS) += genksyms267 subdir-$(CONFIG_SECURITY_SELINUX) += selinux268 269Unlike obj-y/m, subdir-y/m does not need the trailing slash since this270syntax is always used for directories.271 272It is good practice to use a ``CONFIG_`` variable when assigning directory273names. This allows kbuild to totally skip the directory if the274corresponding ``CONFIG_`` option is neither "y" nor "m".275 276Non-builtin vmlinux targets - extra-y277-------------------------------------278 279extra-y specifies targets which are needed for building vmlinux,280but not combined into built-in.a.281 282Examples are:283 2841) vmlinux linker script285 286 The linker script for vmlinux is located at287 arch/$(SRCARCH)/kernel/vmlinux.lds288 289Example::290 291 # arch/x86/kernel/Makefile292 extra-y += vmlinux.lds293 294$(extra-y) should only contain targets needed for vmlinux.295 296Kbuild skips extra-y when vmlinux is apparently not a final goal.297(e.g. ``make modules``, or building external modules)298 299If you intend to build targets unconditionally, always-y (explained300in the next section) is the correct syntax to use.301 302Always built goals - always-y303-----------------------------304 305always-y specifies targets which are literally always built when306Kbuild visits the Makefile.307 308Example::309 310 # ./Kbuild311 offsets-file := include/generated/asm-offsets.h312 always-y += $(offsets-file)313 314Compilation flags315-----------------316 317ccflags-y, asflags-y and ldflags-y318 These three flags apply only to the kbuild makefile in which they319 are assigned. They are used for all the normal cc, as and ld320 invocations happening during a recursive build.321 Note: Flags with the same behaviour were previously named:322 EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.323 They are still supported but their usage is deprecated.324 325 ccflags-y specifies options for compiling with $(CC).326 327 Example::328 329 # drivers/acpi/acpica/Makefile330 ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA331 ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT332 333 This variable is necessary because the top Makefile owns the334 variable $(KBUILD_CFLAGS) and uses it for compilation flags for the335 entire tree.336 337 asflags-y specifies assembler options.338 339 Example::340 341 #arch/sparc/kernel/Makefile342 asflags-y := -ansi343 344 ldflags-y specifies options for linking with $(LD).345 346 Example::347 348 #arch/cris/boot/compressed/Makefile349 ldflags-y += -T $(src)/decompress_$(arch-y).lds350 351subdir-ccflags-y, subdir-asflags-y352 The two flags listed above are similar to ccflags-y and asflags-y.353 The difference is that the subdir- variants have effect for the kbuild354 file where they are present and all subdirectories.355 Options specified using subdir-* are added to the commandline before356 the options specified using the non-subdir variants.357 358 Example::359 360 subdir-ccflags-y := -Werror361 362ccflags-remove-y, asflags-remove-y363 These flags are used to remove particular flags for the compiler,364 assembler invocations.365 366 Example::367 368 ccflags-remove-$(CONFIG_MCOUNT) += -pg369 370CFLAGS_$@, AFLAGS_$@371 CFLAGS_$@ and AFLAGS_$@ only apply to commands in current372 kbuild makefile.373 374 $(CFLAGS_$@) specifies per-file options for $(CC). The $@375 part has a literal value which specifies the file that it is for.376 377 CFLAGS_$@ has the higher priority than ccflags-remove-y; CFLAGS_$@378 can re-add compiler flags that were removed by ccflags-remove-y.379 380 Example::381 382 # drivers/scsi/Makefile383 CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF384 385 This line specify compilation flags for aha152x.o.386 387 $(AFLAGS_$@) is a similar feature for source files in assembly388 languages.389 390 AFLAGS_$@ has the higher priority than asflags-remove-y; AFLAGS_$@391 can re-add assembler flags that were removed by asflags-remove-y.392 393 Example::394 395 # arch/arm/kernel/Makefile396 AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET)397 AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312398 AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt399 400Dependency tracking401-------------------402 403Kbuild tracks dependencies on the following:404 4051) All prerequisite files (both ``*.c`` and ``*.h``)4062) ``CONFIG_`` options used in all prerequisite files4073) Command-line used to compile target408 409Thus, if you change an option to $(CC) all affected files will410be re-compiled.411 412Custom Rules413------------414 415Custom rules are used when the kbuild infrastructure does416not provide the required support. A typical example is417header files generated during the build process.418Another example are the architecture-specific Makefiles which419need custom rules to prepare boot images etc.420 421Custom rules are written as normal Make rules.422Kbuild is not executing in the directory where the Makefile is423located, so all custom rules shall use a relative424path to prerequisite files and target files.425 426Two variables are used when defining custom rules:427 428$(src)429 $(src) is the directory where the Makefile is located. Always use $(src) when430 referring to files located in the src tree.431 432$(obj)433 $(obj) is the directory where the target is saved. Always use $(obj) when434 referring to generated files. Use $(obj) for pattern rules that need to work435 for both generated files and real sources (VPATH will help to find the436 prerequisites not only in the object tree but also in the source tree).437 438 Example::439 440 #drivers/scsi/Makefile441 $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl442 $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl443 444 This is a custom rule, following the normal syntax445 required by make.446 447 The target file depends on two prerequisite files. References448 to the target file are prefixed with $(obj), references449 to prerequisites are referenced with $(src) (because they are not450 generated files).451 452$(kecho)453 echoing information to user in a rule is often a good practice454 but when execution ``make -s`` one does not expect to see any output455 except for warnings/errors.456 To support this kbuild defines $(kecho) which will echo out the457 text following $(kecho) to stdout except if ``make -s`` is used.458 459 Example::460 461 # arch/arm/Makefile462 $(BOOT_TARGETS): vmlinux463 $(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@464 @$(kecho) ' Kernel: $(boot)/$@ is ready'465 466 When kbuild is executing with KBUILD_VERBOSE unset, then only a shorthand467 of a command is normally displayed.468 To enable this behaviour for custom commands kbuild requires469 two variables to be set::470 471 quiet_cmd_<command> - what shall be echoed472 cmd_<command> - the command to execute473 474 Example::475 476 # lib/Makefile477 quiet_cmd_crc32 = GEN $@478 cmd_crc32 = $< > $@479 480 $(obj)/crc32table.h: $(obj)/gen_crc32table481 $(call cmd,crc32)482 483 When updating the $(obj)/crc32table.h target, the line::484 485 GEN lib/crc32table.h486 487 will be displayed with ``make KBUILD_VERBOSE=``.488 489Command change detection490------------------------491 492When the rule is evaluated, timestamps are compared between the target493and its prerequisite files. GNU Make updates the target when any of the494prerequisites is newer than that.495 496The target should be rebuilt also when the command line has changed497since the last invocation. This is not supported by Make itself, so498Kbuild achieves this by a kind of meta-programming.499 500if_changed is the macro used for this purpose, in the following form::501 502 quiet_cmd_<command> = ...503 cmd_<command> = ...504 505 <target>: <source(s)> FORCE506 $(call if_changed,<command>)507 508Any target that utilizes if_changed must be listed in $(targets),509otherwise the command line check will fail, and the target will510always be built.511 512If the target is already listed in the recognized syntax such as513obj-y/m, lib-y/m, extra-y/m, always-y/m, hostprogs, userprogs, Kbuild514automatically adds it to $(targets). Otherwise, the target must be515explicitly added to $(targets).516 517Assignments to $(targets) are without $(obj)/ prefix. if_changed may be518used in conjunction with custom rules as defined in `Custom Rules`_.519 520Note: It is a typical mistake to forget the FORCE prerequisite.521Another common pitfall is that whitespace is sometimes significant; for522instance, the below will fail (note the extra space after the comma)::523 524 target: source(s) FORCE525 526**WRONG!** $(call if_changed, objcopy)527 528Note:529 if_changed should not be used more than once per target.530 It stores the executed command in a corresponding .cmd531 file and multiple calls would result in overwrites and532 unwanted results when the target is up to date and only the533 tests on changed commands trigger execution of commands.534 535$(CC) support functions536-----------------------537 538The kernel may be built with several different versions of539$(CC), each supporting a unique set of features and options.540kbuild provides basic support to check for valid options for $(CC).541$(CC) is usually the gcc compiler, but other alternatives are542available.543 544as-option545 as-option is used to check if $(CC) -- when used to compile546 assembler (``*.S``) files -- supports the given option. An optional547 second option may be specified if the first option is not supported.548 549 Example::550 551 #arch/sh/Makefile552 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)553 554 In the above example, cflags-y will be assigned the option555 -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).556 The second argument is optional, and if supplied will be used557 if first argument is not supported.558 559as-instr560 as-instr checks if the assembler reports a specific instruction561 and then outputs either option1 or option2562 C escapes are supported in the test instruction563 Note: as-instr-option uses KBUILD_AFLAGS for assembler options564 565cc-option566 cc-option is used to check if $(CC) supports a given option, and if567 not supported to use an optional second option.568 569 Example::570 571 #arch/x86/Makefile572 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)573 574 In the above example, cflags-y will be assigned the option575 -march=pentium-mmx if supported by $(CC), otherwise -march=i586.576 The second argument to cc-option is optional, and if omitted,577 cflags-y will be assigned no value if first option is not supported.578 Note: cc-option uses KBUILD_CFLAGS for $(CC) options579 580cc-option-yn581 cc-option-yn is used to check if $(CC) supports a given option582 and return "y" if supported, otherwise "n".583 584 Example::585 586 #arch/ppc/Makefile587 biarch := $(call cc-option-yn, -m32)588 aflags-$(biarch) += -a32589 cflags-$(biarch) += -m32590 591 In the above example, $(biarch) is set to y if $(CC) supports the -m32592 option. When $(biarch) equals "y", the expanded variables $(aflags-y)593 and $(cflags-y) will be assigned the values -a32 and -m32,594 respectively.595 596 Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options597 598cc-disable-warning599 cc-disable-warning checks if $(CC) supports a given warning and returns600 the commandline switch to disable it. This special function is needed,601 because gcc 4.4 and later accept any unknown -Wno-* option and only602 warn about it if there is another warning in the source file.603 604 Example::605 606 KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)607 608 In the above example, -Wno-unused-but-set-variable will be added to609 KBUILD_CFLAGS only if $(CC) really accepts it.610 611gcc-min-version612 gcc-min-version tests if the value of $(CONFIG_GCC_VERSION) is greater than613 or equal to the provided value and evaluates to y if so.614 615 Example::616 617 cflags-$(call gcc-min-version, 70100) := -foo618 619 In this example, cflags-y will be assigned the value -foo if $(CC) is gcc and620 $(CONFIG_GCC_VERSION) is >= 7.1.621 622clang-min-version623 clang-min-version tests if the value of $(CONFIG_CLANG_VERSION) is greater624 than or equal to the provided value and evaluates to y if so.625 626 Example::627 628 cflags-$(call clang-min-version, 110000) := -foo629 630 In this example, cflags-y will be assigned the value -foo if $(CC) is clang631 and $(CONFIG_CLANG_VERSION) is >= 11.0.0.632 633cc-cross-prefix634 cc-cross-prefix is used to check if there exists a $(CC) in path with635 one of the listed prefixes. The first prefix where there exist a636 prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found637 then nothing is returned.638 639 Additional prefixes are separated by a single space in the640 call of cc-cross-prefix.641 642 This functionality is useful for architecture Makefiles that try643 to set CROSS_COMPILE to well-known values but may have several644 values to select between.645 646 It is recommended only to try to set CROSS_COMPILE if it is a cross647 build (host arch is different from target arch). And if CROSS_COMPILE648 is already set then leave it with the old value.649 650 Example::651 652 #arch/m68k/Makefile653 ifneq ($(SUBARCH),$(ARCH))654 ifeq ($(CROSS_COMPILE),)655 CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)656 endif657 endif658 659$(LD) support functions660-----------------------661 662ld-option663 ld-option is used to check if $(LD) supports the supplied option.664 ld-option takes two options as arguments.665 666 The second argument is an optional option that can be used if the667 first option is not supported by $(LD).668 669 Example::670 671 #Makefile672 LDFLAGS_vmlinux += $(call ld-option, -X)673 674Script invocation675-----------------676 677Make rules may invoke scripts to build the kernel. The rules shall678always provide the appropriate interpreter to execute the script. They679shall not rely on the execute bits being set, and shall not invoke the680script directly. For the convenience of manual script invocation, such681as invoking ./scripts/checkpatch.pl, it is recommended to set execute682bits on the scripts nonetheless.683 684Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL),685and $(PYTHON3) to refer to interpreters for the respective686scripts.687 688Example::689 690 #Makefile691 cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \692 $(KERNELRELEASE)693 694Host Program support695====================696 697Kbuild supports building executables on the host for use during the698compilation stage.699 700Two steps are required in order to use a host executable.701 702The first step is to tell kbuild that a host program exists. This is703done utilising the variable ``hostprogs``.704 705The second step is to add an explicit dependency to the executable.706This can be done in two ways. Either add the dependency in a rule,707or utilise the variable ``always-y``.708Both possibilities are described in the following.709 710Simple Host Program711-------------------712 713In some cases there is a need to compile and run a program on the714computer where the build is running.715 716The following line tells kbuild that the program bin2hex shall be717built on the build host.718 719Example::720 721 hostprogs := bin2hex722 723Kbuild assumes in the above example that bin2hex is made from a single724c-source file named bin2hex.c located in the same directory as725the Makefile.726 727Composite Host Programs728-----------------------729 730Host programs can be made up based on composite objects.731The syntax used to define composite objects for host programs is732similar to the syntax used for kernel objects.733$(<executable>-objs) lists all objects used to link the final734executable.735 736Example::737 738 #scripts/lxdialog/Makefile739 hostprogs := lxdialog740 lxdialog-objs := checklist.o lxdialog.o741 742Objects with extension .o are compiled from the corresponding .c743files. In the above example, checklist.c is compiled to checklist.o744and lxdialog.c is compiled to lxdialog.o.745 746Finally, the two .o files are linked to the executable, lxdialog.747Note: The syntax <executable>-y is not permitted for host-programs.748 749Using C++ for host programs750---------------------------751 752kbuild offers support for host programs written in C++. This was753introduced solely to support kconfig, and is not recommended754for general use.755 756Example::757 758 #scripts/kconfig/Makefile759 hostprogs := qconf760 qconf-cxxobjs := qconf.o761 762In the example above the executable is composed of the C++ file763qconf.cc - identified by $(qconf-cxxobjs).764 765If qconf is composed of a mixture of .c and .cc files, then an766additional line can be used to identify this.767 768Example::769 770 #scripts/kconfig/Makefile771 hostprogs := qconf772 qconf-cxxobjs := qconf.o773 qconf-objs := check.o774 775Using Rust for host programs776----------------------------777 778Kbuild offers support for host programs written in Rust. However,779since a Rust toolchain is not mandatory for kernel compilation,780it may only be used in scenarios where Rust is required to be781available (e.g. when ``CONFIG_RUST`` is enabled).782 783Example::784 785 hostprogs := target786 target-rust := y787 788Kbuild will compile ``target`` using ``target.rs`` as the crate root,789located in the same directory as the ``Makefile``. The crate may790consist of several source files (see ``samples/rust/hostprogs``).791 792Controlling compiler options for host programs793----------------------------------------------794 795When compiling host programs, it is possible to set specific flags.796The programs will always be compiled utilising $(HOSTCC) passed797the options specified in $(KBUILD_HOSTCFLAGS).798 799To set flags that will take effect for all host programs created800in that Makefile, use the variable HOST_EXTRACFLAGS.801 802Example::803 804 #scripts/lxdialog/Makefile805 HOST_EXTRACFLAGS += -I/usr/include/ncurses806 807To set specific flags for a single file the following construction808is used:809 810Example::811 812 #arch/ppc64/boot/Makefile813 HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)814 815It is also possible to specify additional options to the linker.816 817Example::818 819 #scripts/kconfig/Makefile820 HOSTLDLIBS_qconf := -L$(QTDIR)/lib821 822When linking qconf, it will be passed the extra option823``-L$(QTDIR)/lib``.824 825When host programs are actually built826-------------------------------------827 828Kbuild will only build host-programs when they are referenced829as a prerequisite.830 831This is possible in two ways:832 833(1) List the prerequisite explicitly in a custom rule.834 835 Example::836 837 #drivers/pci/Makefile838 hostprogs := gen-devlist839 $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist840 ( cd $(obj); ./gen-devlist ) < $<841 842 The target $(obj)/devlist.h will not be built before843 $(obj)/gen-devlist is updated. Note that references to844 the host programs in custom rules must be prefixed with $(obj).845 846(2) Use always-y847 848 When there is no suitable custom rule, and the host program849 shall be built when a makefile is entered, the always-y850 variable shall be used.851 852 Example::853 854 #scripts/lxdialog/Makefile855 hostprogs := lxdialog856 always-y := $(hostprogs)857 858 Kbuild provides the following shorthand for this::859 860 hostprogs-always-y := lxdialog861 862 This will tell kbuild to build lxdialog even if not referenced in863 any rule.864 865Userspace Program support866=========================867 868Just like host programs, Kbuild also supports building userspace executables869for the target architecture (i.e. the same architecture as you are building870the kernel for).871 872The syntax is quite similar. The difference is to use ``userprogs`` instead of873``hostprogs``.874 875Simple Userspace Program876------------------------877 878The following line tells kbuild that the program bpf-direct shall be879built for the target architecture.880 881Example::882 883 userprogs := bpf-direct884 885Kbuild assumes in the above example that bpf-direct is made from a886single C source file named bpf-direct.c located in the same directory887as the Makefile.888 889Composite Userspace Programs890----------------------------891 892Userspace programs can be made up based on composite objects.893The syntax used to define composite objects for userspace programs is894similar to the syntax used for kernel objects.895$(<executable>-objs) lists all objects used to link the final896executable.897 898Example::899 900 #samples/seccomp/Makefile901 userprogs := bpf-fancy902 bpf-fancy-objs := bpf-fancy.o bpf-helper.o903 904Objects with extension .o are compiled from the corresponding .c905files. In the above example, bpf-fancy.c is compiled to bpf-fancy.o906and bpf-helper.c is compiled to bpf-helper.o.907 908Finally, the two .o files are linked to the executable, bpf-fancy.909Note: The syntax <executable>-y is not permitted for userspace programs.910 911Controlling compiler options for userspace programs912---------------------------------------------------913 914When compiling userspace programs, it is possible to set specific flags.915The programs will always be compiled utilising $(CC) passed916the options specified in $(KBUILD_USERCFLAGS).917 918To set flags that will take effect for all userspace programs created919in that Makefile, use the variable userccflags.920 921Example::922 923 # samples/seccomp/Makefile924 userccflags += -I usr/include925 926To set specific flags for a single file the following construction927is used:928 929Example::930 931 bpf-helper-userccflags += -I user/include932 933It is also possible to specify additional options to the linker.934 935Example::936 937 # net/bpfilter/Makefile938 bpfilter_umh-userldflags += -static939 940To specify libraries linked to a userspace program, you can use941``<executable>-userldlibs``. The ``userldlibs`` syntax specifies libraries942linked to all userspace programs created in the current Makefile.943 944When linking bpfilter_umh, it will be passed the extra option -static.945 946From command line, :ref:`USERCFLAGS and USERLDFLAGS <userkbuildflags>` will also be used.947 948When userspace programs are actually built949------------------------------------------950 951Kbuild builds userspace programs only when told to do so.952There are two ways to do this.953 954(1) Add it as the prerequisite of another file955 956 Example::957 958 #net/bpfilter/Makefile959 userprogs := bpfilter_umh960 $(obj)/bpfilter_umh_blob.o: $(obj)/bpfilter_umh961 962 $(obj)/bpfilter_umh is built before $(obj)/bpfilter_umh_blob.o963 964(2) Use always-y965 966 Example::967 968 userprogs := binderfs_example969 always-y := $(userprogs)970 971 Kbuild provides the following shorthand for this::972 973 userprogs-always-y := binderfs_example974 975 This will tell Kbuild to build binderfs_example when it visits this976 Makefile.977 978Kbuild clean infrastructure979===========================980 981``make clean`` deletes most generated files in the obj tree where the kernel982is compiled. This includes generated files such as host programs.983Kbuild knows targets listed in $(hostprogs), $(always-y), $(always-m),984$(always-), $(extra-y), $(extra-) and $(targets). They are all deleted985during ``make clean``. Files matching the patterns ``*.[oas]``, ``*.ko``, plus986some additional files generated by kbuild are deleted all over the kernel987source tree when ``make clean`` is executed.988 989Additional files or directories can be specified in kbuild makefiles by use of990$(clean-files).991 992Example::993 994 #lib/Makefile995 clean-files := crc32table.h996 997When executing ``make clean``, the file ``crc32table.h`` will be deleted.998Kbuild will assume files to be in the same relative directory as the999Makefile.1000 1001To exclude certain files or directories from make clean, use the1002$(no-clean-files) variable.1003 1004Usually kbuild descends down in subdirectories due to ``obj-* := dir/``,1005but in the architecture makefiles where the kbuild infrastructure1006is not sufficient this sometimes needs to be explicit.1007 1008Example::1009 1010 #arch/x86/boot/Makefile1011 subdir- := compressed1012 1013The above assignment instructs kbuild to descend down in the1014directory compressed/ when ``make clean`` is executed.1015 1016Note 1: arch/$(SRCARCH)/Makefile cannot use ``subdir-``, because that file is1017included in the top level makefile. Instead, arch/$(SRCARCH)/Kbuild can use1018``subdir-``.1019 1020Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will1021be visited during ``make clean``.1022 1023Architecture Makefiles1024======================1025 1026The top level Makefile sets up the environment and does the preparation,1027before starting to descend down in the individual directories.1028 1029The top level makefile contains the generic part, whereas1030arch/$(SRCARCH)/Makefile contains what is required to set up kbuild1031for said architecture.1032 1033To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines1034a few targets.1035 1036When kbuild executes, the following steps are followed (roughly):1037 10381) Configuration of the kernel => produce .config1039 10402) Store kernel version in include/linux/version.h1041 10423) Updating all other prerequisites to the target prepare:1043 1044 - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile1045 10464) Recursively descend down in all directories listed in1047 init-* core* drivers-* net-* libs-* and build all targets.1048 1049 - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile.1050 10515) All object files are then linked and the resulting file vmlinux is1052 located at the root of the obj tree.1053 The very first objects linked are listed in scripts/head-object-list.txt.1054 10556) Finally, the architecture-specific part does any required post processing1056 and builds the final bootimage.1057 1058 - This includes building boot records1059 - Preparing initrd images and the like1060 1061Set variables to tweak the build to the architecture1062----------------------------------------------------1063 1064KBUILD_LDFLAGS1065 Generic $(LD) options1066 1067 Flags used for all invocations of the linker.1068 Often specifying the emulation is sufficient.1069 1070 Example::1071 1072 #arch/s390/Makefile1073 KBUILD_LDFLAGS := -m elf_s3901074 1075 Note: ldflags-y can be used to further customise1076 the flags used. See `Non-builtin vmlinux targets - extra-y`_.1077 1078LDFLAGS_vmlinux1079 Options for $(LD) when linking vmlinux1080 1081 LDFLAGS_vmlinux is used to specify additional flags to pass to1082 the linker when linking the final vmlinux image.1083 1084 LDFLAGS_vmlinux uses the LDFLAGS_$@ support.1085 1086 Example::1087 1088 #arch/x86/Makefile1089 LDFLAGS_vmlinux := -e stext1090 1091OBJCOPYFLAGS1092 objcopy flags1093 1094 When $(call if_changed,objcopy) is used to translate a .o file,1095 the flags specified in OBJCOPYFLAGS will be used.1096 1097 $(call if_changed,objcopy) is often used to generate raw binaries on1098 vmlinux.1099 1100 Example::1101 1102 #arch/s390/Makefile1103 OBJCOPYFLAGS := -O binary1104 1105 #arch/s390/boot/Makefile1106 $(obj)/image: vmlinux FORCE1107 $(call if_changed,objcopy)1108 1109 In this example, the binary $(obj)/image is a binary version of1110 vmlinux. The usage of $(call if_changed,xxx) will be described later.1111 1112KBUILD_AFLAGS1113 Assembler flags1114 1115 Default value - see top level Makefile.1116 1117 Append or modify as required per architecture.1118 1119 Example::1120 1121 #arch/sparc64/Makefile1122 KBUILD_AFLAGS += -m64 -mcpu=ultrasparc1123 1124KBUILD_CFLAGS1125 $(CC) compiler flags1126 1127 Default value - see top level Makefile.1128 1129 Append or modify as required per architecture.1130 1131 Often, the KBUILD_CFLAGS variable depends on the configuration.1132 1133 Example::1134 1135 #arch/x86/boot/compressed/Makefile1136 cflags-$(CONFIG_X86_32) := -march=i3861137 cflags-$(CONFIG_X86_64) := -mcmodel=small1138 KBUILD_CFLAGS += $(cflags-y)1139 1140 Many arch Makefiles dynamically run the target C compiler to1141 probe supported options::1142 1143 #arch/x86/Makefile1144 1145 ...1146 cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\1147 -march=pentium2,-march=i686)1148 ...1149 # Disable unit-at-a-time mode ...1150 KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)1151 ...1152 1153 1154 The first example utilises the trick that a config option expands1155 to "y" when selected.1156 1157KBUILD_RUSTFLAGS1158 $(RUSTC) compiler flags1159 1160 Default value - see top level Makefile.1161 1162 Append or modify as required per architecture.1163 1164 Often, the KBUILD_RUSTFLAGS variable depends on the configuration.1165 1166 Note that target specification file generation (for ``--target``)1167 is handled in ``scripts/generate_rust_target.rs``.1168 1169KBUILD_AFLAGS_KERNEL1170 Assembler options specific for built-in1171 1172 $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile1173 resident kernel code.1174 1175KBUILD_AFLAGS_MODULE1176 Assembler options specific for modules1177 1178 $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that1179 are used for assembler.1180 1181 From commandline AFLAGS_MODULE shall be used (see kbuild.rst).1182 1183KBUILD_CFLAGS_KERNEL1184 $(CC) options specific for built-in1185 1186 $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile1187 resident kernel code.1188 1189KBUILD_CFLAGS_MODULE1190 Options for $(CC) when building modules1191 1192 $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that1193 are used for $(CC).1194 1195 From commandline CFLAGS_MODULE shall be used (see kbuild.rst).1196 1197KBUILD_RUSTFLAGS_KERNEL1198 $(RUSTC) options specific for built-in1199 1200 $(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to1201 compile resident kernel code.1202 1203KBUILD_RUSTFLAGS_MODULE1204 Options for $(RUSTC) when building modules1205 1206 $(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that1207 are used for $(RUSTC).1208 1209 From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst).1210 1211KBUILD_LDFLAGS_MODULE1212 Options for $(LD) when linking modules1213 1214 $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options1215 used when linking modules. This is often a linker script.1216 1217 From commandline LDFLAGS_MODULE shall be used (see kbuild.rst).1218 1219KBUILD_LDS1220 The linker script with full path. Assigned by the top-level Makefile.1221 1222KBUILD_VMLINUX_OBJS1223 All object files for vmlinux. They are linked to vmlinux in the same1224 order as listed in KBUILD_VMLINUX_OBJS.1225 1226 The objects listed in scripts/head-object-list.txt are exceptions;1227 they are placed before the other objects.1228 1229KBUILD_VMLINUX_LIBS1230 All .a ``lib`` files for vmlinux. KBUILD_VMLINUX_OBJS and1231 KBUILD_VMLINUX_LIBS together specify all the object files used to1232 link vmlinux.1233 1234Add prerequisites to archheaders1235--------------------------------1236 1237The archheaders: rule is used to generate header files that1238may be installed into user space by ``make header_install``.1239 1240It is run before ``make archprepare`` when run on the1241architecture itself.1242 1243Add prerequisites to archprepare1244--------------------------------1245 1246The archprepare: rule is used to list prerequisites that need to be1247built before starting to descend down in the subdirectories.1248 1249This is usually used for header files containing assembler constants.1250 1251Example::1252 1253 #arch/arm/Makefile1254 archprepare: maketools1255 1256In this example, the file target maketools will be processed1257before descending down in the subdirectories.1258 1259See also chapter XXX-TODO that describes how kbuild supports1260generating offset header files.1261 1262List directories to visit when descending1263-----------------------------------------1264 1265An arch Makefile cooperates with the top Makefile to define variables1266which specify how to build the vmlinux file. Note that there is no1267corresponding arch-specific section for modules; the module-building1268machinery is all architecture-independent.1269 1270core-y, libs-y, drivers-y1271 $(libs-y) lists directories where a lib.a archive can be located.1272 1273 The rest list directories where a built-in.a object file can be1274 located.1275 1276 Then the rest follows in this order:1277 1278 $(core-y), $(libs-y), $(drivers-y)1279 1280 The top level Makefile defines values for all generic directories,1281 and arch/$(SRCARCH)/Makefile only adds architecture-specific1282 directories.1283 1284 Example::1285 1286 # arch/sparc/Makefile1287 core-y += arch/sparc/1288 1289 libs-y += arch/sparc/prom/1290 libs-y += arch/sparc/lib/1291 1292 drivers-$(CONFIG_PM) += arch/sparc/power/1293 1294Architecture-specific boot images1295---------------------------------1296 1297An arch Makefile specifies goals that take the vmlinux file, compress1298it, wrap it in bootstrapping code, and copy the resulting files1299somewhere. This includes various kinds of installation commands.1300The actual goals are not standardized across architectures.1301 1302It is common to locate any additional processing in a boot/1303directory below arch/$(SRCARCH)/.1304 1305Kbuild does not provide any smart way to support building a1306target specified in boot/. Therefore arch/$(SRCARCH)/Makefile shall1307call make manually to build a target in boot/.1308 1309The recommended approach is to include shortcuts in1310arch/$(SRCARCH)/Makefile, and use the full path when calling down1311into the arch/$(SRCARCH)/boot/Makefile.1312 1313Example::1314 1315 #arch/x86/Makefile1316 boot := arch/x86/boot1317 bzImage: vmlinux1318 $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@1319 1320``$(Q)$(MAKE) $(build)=<dir>`` is the recommended way to invoke1321make in a subdirectory.1322 1323There are no rules for naming architecture-specific targets,1324but executing ``make help`` will list all relevant targets.1325To support this, $(archhelp) must be defined.1326 1327Example::1328 1329 #arch/x86/Makefile1330 define archhelp1331 echo '* bzImage - Compressed kernel image (arch/x86/boot/bzImage)'1332 endif1333 1334When make is executed without arguments, the first goal encountered1335will be built. In the top level Makefile the first goal present1336is all:.1337 1338An architecture shall always, per default, build a bootable image.1339In ``make help``, the default goal is highlighted with a ``*``.1340 1341Add a new prerequisite to all: to select a default goal different1342from vmlinux.1343 1344Example::1345 1346 #arch/x86/Makefile1347 all: bzImage1348 1349When ``make`` is executed without arguments, bzImage will be built.1350 1351Commands useful for building a boot image1352-----------------------------------------1353 1354Kbuild provides a few macros that are useful when building a1355boot image.1356 1357ld1358 Link target. Often, LDFLAGS_$@ is used to set specific options to ld.1359 1360 Example::1361 1362 #arch/x86/boot/Makefile1363 LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary1364 LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext1365 1366 targets += setup setup.o bootsect bootsect.o1367 $(obj)/setup $(obj)/bootsect: %: %.o FORCE1368 $(call if_changed,ld)1369 1370 In this example, there are two possible targets, requiring different1371 options to the linker. The linker options are specified using the1372 LDFLAGS_$@ syntax - one for each potential target.1373 1374 $(targets) are assigned all potential targets, by which kbuild knows1375 the targets and will:1376 1377 1) check for commandline changes1378 2) delete target during make clean1379 1380 The ``: %: %.o`` part of the prerequisite is a shorthand that1381 frees us from listing the setup.o and bootsect.o files.1382 1383 Note:1384 It is a common mistake to forget the ``targets :=`` assignment,1385 resulting in the target file being recompiled for no1386 obvious reason.1387 1388objcopy1389 Copy binary. Uses OBJCOPYFLAGS usually specified in1390 arch/$(SRCARCH)/Makefile.1391 1392 OBJCOPYFLAGS_$@ may be used to set additional options.1393 1394gzip1395 Compress target. Use maximum compression to compress target.1396 1397 Example::1398 1399 #arch/x86/boot/compressed/Makefile1400 $(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE1401 $(call if_changed,gzip)1402 1403dtc1404 Create flattened device tree blob object suitable for linking1405 into vmlinux. Device tree blobs linked into vmlinux are placed1406 in an init section in the image. Platform code *must* copy the1407 blob to non-init memory prior to calling unflatten_device_tree().1408 1409 To use this command, simply add ``*.dtb`` into obj-y or targets, or make1410 some other target depend on ``%.dtb``1411 1412 A central rule exists to create ``$(obj)/%.dtb`` from ``$(src)/%.dts``;1413 architecture Makefiles do no need to explicitly write out that rule.1414 1415 Example::1416 1417 targets += $(dtb-y)1418 DTC_FLAGS ?= -p 10241419 1420Preprocessing linker scripts1421----------------------------1422 1423When the vmlinux image is built, the linker script1424arch/$(SRCARCH)/kernel/vmlinux.lds is used.1425 1426The script is a preprocessed variant of the file vmlinux.lds.S1427located in the same directory.1428 1429kbuild knows .lds files and includes a rule ``*lds.S`` -> ``*lds``.1430 1431Example::1432 1433 #arch/x86/kernel/Makefile1434 extra-y := vmlinux.lds1435 1436The assignment to extra-y is used to tell kbuild to build the1437target vmlinux.lds.1438 1439The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the1440specified options when building the target vmlinux.lds.1441 1442When building the ``*.lds`` target, kbuild uses the variables::1443 1444 KBUILD_CPPFLAGS : Set in top-level Makefile1445 cppflags-y : May be set in the kbuild makefile1446 CPPFLAGS_$(@F) : Target-specific flags.1447 Note that the full filename is used in this1448 assignment.1449 1450The kbuild infrastructure for ``*lds`` files is used in several1451architecture-specific files.1452 1453Generic header files1454--------------------1455 1456The directory include/asm-generic contains the header files1457that may be shared between individual architectures.1458 1459The recommended approach how to use a generic header file is1460to list the file in the Kbuild file.1461 1462See `generic-y`_ for further info on syntax etc.1463 1464Post-link pass1465--------------1466 1467If the file arch/xxx/Makefile.postlink exists, this makefile1468will be invoked for post-link objects (vmlinux and modules.ko)1469for architectures to run post-link passes on. Must also handle1470the clean target.1471 1472This pass runs after kallsyms generation. If the architecture1473needs to modify symbol locations, rather than manipulate the1474kallsyms, it may be easier to add another postlink target for1475.tmp_vmlinux? targets to be called from link-vmlinux.sh.1476 1477For example, powerpc uses this to check relocation sanity of1478the linked vmlinux file.1479 1480Kbuild syntax for exported headers1481==================================1482 1483The kernel includes a set of headers that is exported to userspace.1484Many headers can be exported as-is but other headers require a1485minimal pre-processing before they are ready for user-space.1486 1487The pre-processing does:1488 1489- drop kernel-specific annotations1490- drop include of compiler.h1491- drop all sections that are kernel internal (guarded by ``ifdef __KERNEL__``)1492 1493All headers under include/uapi/, include/generated/uapi/,1494arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/1495are exported.1496 1497A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and1498arch/<arch>/include/asm/ to list asm files coming from asm-generic.1499 1500See subsequent chapter for the syntax of the Kbuild file.1501 1502no-export-headers1503-----------------1504 1505no-export-headers is essentially used by include/uapi/linux/Kbuild to1506avoid exporting specific headers (e.g. kvm.h) on architectures that do1507not support it. It should be avoided as much as possible.1508 1509generic-y1510---------1511 1512If an architecture uses a verbatim copy of a header from1513include/asm-generic then this is listed in the file1514arch/$(SRCARCH)/include/asm/Kbuild like this:1515 1516Example::1517 1518 #arch/x86/include/asm/Kbuild1519 generic-y += termios.h1520 generic-y += rtc.h1521 1522During the prepare phase of the build a wrapper include1523file is generated in the directory::1524 1525 arch/$(SRCARCH)/include/generated/asm1526 1527When a header is exported where the architecture uses1528the generic header a similar wrapper is generated as part1529of the set of exported headers in the directory::1530 1531 usr/include/asm1532 1533The generated wrapper will in both cases look like the following:1534 1535Example: termios.h::1536 1537 #include <asm-generic/termios.h>1538 1539generated-y1540-----------1541 1542If an architecture generates other header files alongside generic-y1543wrappers, generated-y specifies them.1544 1545This prevents them being treated as stale asm-generic wrappers and1546removed.1547 1548Example::1549 1550 #arch/x86/include/asm/Kbuild1551 generated-y += syscalls_32.h1552 1553mandatory-y1554-----------1555 1556mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild1557to define the minimum set of ASM headers that all architectures must have.1558 1559This works like optional generic-y. If a mandatory header is missing1560in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically1561generate a wrapper of the asm-generic one.1562 1563Kbuild Variables1564================1565 1566The top Makefile exports the following variables:1567 1568VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION1569 These variables define the current kernel version. A few arch1570 Makefiles actually use these values directly; they should use1571 $(KERNELRELEASE) instead.1572 1573 $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic1574 three-part version number, such as "2", "4", and "0". These three1575 values are always numeric.1576 1577 $(EXTRAVERSION) defines an even tinier sublevel for pre-patches1578 or additional patches. It is usually some non-numeric string1579 such as "-pre4", and is often blank.1580 1581KERNELRELEASE1582 $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable1583 for constructing installation directory names or showing in1584 version strings. Some arch Makefiles use it for this purpose.1585 1586ARCH1587 This variable defines the target architecture, such as "i386",1588 "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to1589 determine which files to compile.1590 1591 By default, the top Makefile sets $(ARCH) to be the same as the1592 host system architecture. For a cross build, a user may1593 override the value of $(ARCH) on the command line::1594 1595 make ARCH=m68k ...1596 1597SRCARCH1598 This variable specifies the directory in arch/ to build.1599 1600 ARCH and SRCARCH may not necessarily match. A couple of arch1601 directories are biarch, that is, a single ``arch/*/`` directory supports1602 both 32-bit and 64-bit.1603 1604 For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86.1605 For all of them, SRCARCH=x86 because arch/x86/ supports both i386 and1606 x86_64.1607 1608INSTALL_PATH1609 This variable defines a place for the arch Makefiles to install1610 the resident kernel image and System.map file.1611 Use this for architecture-specific install targets.1612 1613INSTALL_MOD_PATH, MODLIB1614 $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module1615 installation. This variable is not defined in the Makefile but1616 may be passed in by the user if desired.1617 1618 $(MODLIB) specifies the directory for module installation.1619 The top Makefile defines $(MODLIB) to1620 $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may1621 override this value on the command line if desired.1622 1623INSTALL_MOD_STRIP1624 If this variable is specified, it will cause modules to be stripped1625 after they are installed. If INSTALL_MOD_STRIP is "1", then the1626 default option --strip-debug will be used. Otherwise, the1627 INSTALL_MOD_STRIP value will be used as the option(s) to the strip1628 command.1629 1630INSTALL_DTBS_PATH1631 This variable specifies a prefix for relocations required by build1632 roots. It defines a place for installing the device tree blobs. Like1633 INSTALL_MOD_PATH, it isn't defined in the Makefile, but can be passed1634 by the user if desired. Otherwise it defaults to the kernel install1635 path.1636 1637Makefile language1638=================1639 1640The kernel Makefiles are designed to be run with GNU Make. The Makefiles1641use only the documented features of GNU Make, but they do use many1642GNU extensions.1643 1644GNU Make supports elementary list-processing functions. The kernel1645Makefiles use a novel style of list building and manipulation with few1646``if`` statements.1647 1648GNU Make has two assignment operators, ``:=`` and ``=``. ``:=`` performs1649immediate evaluation of the right-hand side and stores an actual string1650into the left-hand side. ``=`` is like a formula definition; it stores the1651right-hand side in an unevaluated form and then evaluates this form each1652time the left-hand side is used.1653 1654There are some cases where ``=`` is appropriate. Usually, though, ``:=``1655is the right choice.1656 1657Credits1658=======1659 1660- Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>1661- Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>1662- Updates by Sam Ravnborg <sam@ravnborg.org>1663- Language QA by Jan Engelhardt <jengelh@gmx.de>1664 1665TODO1666====1667 1668- Generating offset header files.1669- Add more variables to chapters 7 or 9?1670