diff options
Diffstat (limited to 'Documentation/kbuild')
| -rw-r--r-- | Documentation/kbuild/makefiles.rst | 206 |
1 files changed, 103 insertions, 103 deletions
diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 15d2f91d704a..b0ace679a01b 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -4,8 +4,8 @@ Linux Kernel Makefiles This document describes the Linux kernel Makefiles. -1 Overview -========== +Overview +======== The Makefiles have five parts:: @@ -36,8 +36,8 @@ scripts/Makefile.* contains all the definitions/rules etc. that are used to build the kernel based on the kbuild makefiles. -2 Who does what -=============== +Who does what +============= People have four different relationships with the kernel Makefiles. @@ -62,8 +62,8 @@ These people need to know about all aspects of the kernel Makefiles. This document is aimed towards normal developers and arch developers. -3 The kbuild files -================== +The kbuild files +================ Most Makefiles within the kernel are kbuild Makefiles that use the kbuild infrastructure. This chapter introduces the syntax used in the @@ -72,11 +72,11 @@ The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild' file will be used. -Section 3.1 "Goal definitions" is a quick intro; further chapters provide +Section `Goal definitions`_ is a quick intro; further chapters provide more details, with real examples. -3.1 Goal definitions --------------------- +Goal definitions +---------------- Goal definitions are the main part (heart) of the kbuild Makefile. These lines define the files to be built, any special compilation @@ -102,8 +102,8 @@ more details, with real examples. If CONFIG_FOO is neither y nor m, then the file will not be compiled nor linked. -3.2 Built-in object goals - obj-y ---------------------------------- +Built-in object goals - obj-y +----------------------------- The kbuild Makefile specifies object files for vmlinux in the $(obj-y) lists. These lists depend on the kernel @@ -132,8 +132,8 @@ more details, with real examples. obj-$(CONFIG_ISDN_I4L) += isdn.o obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o -3.3 Loadable module goals - obj-m ---------------------------------- +Loadable module goals - obj-m +----------------------------- $(obj-m) specifies object files which are built as loadable kernel modules. @@ -187,8 +187,8 @@ more details, with real examples. kbuild will build an ext2.o file for you out of the individual parts and then link this into built-in.a, as you would expect. -3.5 Library file goals - lib-y ------------------------------- +Library file goals - lib-y +-------------------------- Objects listed with obj-* are used for modules, or combined in a built-in.a for that specific directory. @@ -214,12 +214,12 @@ more details, with real examples. actually recognize that there is a lib.a being built, the directory shall be listed in libs-y. - See also "7.4 List directories to visit when descending". + See also `List directories to visit when descending`_. Use of lib-y is normally restricted to `lib/` and `arch/*/lib`. -3.6 Descending down in directories ----------------------------------- +Descending down in directories +------------------------------ A Makefile is only responsible for building objects in its own directory. Files in subdirectories should be taken care of by @@ -272,8 +272,8 @@ more details, with real examples. names. This allows kbuild to totally skip the directory if the corresponding `CONFIG_` option is neither 'y' nor 'm'. -3.7 Non-builtin vmlinux targets - extra-y ------------------------------------------ +Non-builtin vmlinux targets - extra-y +------------------------------------- extra-y specifies targets which are needed for building vmlinux, but not combined into built-in.a. @@ -298,8 +298,8 @@ more details, with real examples. If you intend to build targets unconditionally, always-y (explained in the next section) is the correct syntax to use. -3.8 Always built goals - always-y ---------------------------------- +Always built goals - always-y +----------------------------- always-y specifies targets which are literally always built when Kbuild visits the Makefile. @@ -309,8 +309,8 @@ more details, with real examples. offsets-file := include/generated/asm-offsets.h always-y += $(offsets-file) -3.9 Compilation flags ---------------------- +Compilation flags +----------------- ccflags-y, asflags-y and ldflags-y These three flags apply only to the kbuild makefile in which they @@ -396,8 +396,8 @@ more details, with real examples. AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt -3.10 Dependency tracking ------------------------- +Dependency tracking +------------------- Kbuild tracks dependencies on the following: @@ -408,8 +408,8 @@ more details, with real examples. Thus, if you change an option to $(CC) all affected files will be re-compiled. -3.11 Custom Rules ------------------ +Custom Rules +------------ Custom rules are used when the kbuild infrastructure does not provide the required support. A typical example is @@ -485,8 +485,8 @@ more details, with real examples. will be displayed with "make KBUILD_VERBOSE=". -3.12 Command change detection ------------------------------ +Command change detection +------------------------ When the rule is evaluated, timestamps are compared between the target and its prerequisite files. GNU Make updates the target when any of the @@ -514,7 +514,7 @@ more details, with real examples. explicitly added to $(targets). Assignments to $(targets) are without $(obj)/ prefix. if_changed may be - used in conjunction with custom rules as defined in "3.11 Custom Rules". + used in conjunction with custom rules as defined in `Custom Rules`_. Note: It is a typical mistake to forget the FORCE prerequisite. Another common pitfall is that whitespace is sometimes significant; for @@ -531,8 +531,8 @@ more details, with real examples. unwanted results when the target is up to date and only the tests on changed commands trigger execution of commands. -3.13 $(CC) support functions ----------------------------- +$(CC) support functions +----------------------- The kernel may be built with several different versions of $(CC), each supporting a unique set of features and options. @@ -651,8 +651,8 @@ more details, with real examples. endif endif -3.14 $(LD) support functions ----------------------------- +$(LD) support functions +----------------------- ld-option ld-option is used to check if $(LD) supports the supplied option. @@ -665,8 +665,8 @@ more details, with real examples. #Makefile LDFLAGS_vmlinux += $(call ld-option, -X) -3.15 Script invocation ----------------------- +Script invocation +----------------- Make rules may invoke scripts to build the kernel. The rules shall always provide the appropriate interpreter to execute the script. They @@ -685,8 +685,8 @@ more details, with real examples. cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \ $(KERNELRELEASE) -4 Host Program support -====================== +Host Program support +==================== Kbuild supports building executables on the host for use during the compilation stage. @@ -700,8 +700,8 @@ This can be done in two ways. Either add the dependency in a rule, or utilise the variable "always-y". Both possibilities are described in the following. -4.1 Simple Host Program ------------------------ +Simple Host Program +------------------- In some cases there is a need to compile and run a program on the computer where the build is running. @@ -716,8 +716,8 @@ Both possibilities are described in the following. c-source file named bin2hex.c located in the same directory as the Makefile. -4.2 Composite Host Programs ---------------------------- +Composite Host Programs +----------------------- Host programs can be made up based on composite objects. The syntax used to define composite objects for host programs is @@ -738,8 +738,8 @@ Both possibilities are described in the following. Finally, the two .o files are linked to the executable, lxdialog. Note: The syntax <executable>-y is not permitted for host-programs. -4.3 Using C++ for host programs -------------------------------- +Using C++ for host programs +--------------------------- kbuild offers support for host programs written in C++. This was introduced solely to support kconfig, and is not recommended @@ -764,8 +764,8 @@ Both possibilities are described in the following. qconf-cxxobjs := qconf.o qconf-objs := check.o -4.4 Using Rust for host programs --------------------------------- +Using Rust for host programs +---------------------------- Kbuild offers support for host programs written in Rust. However, since a Rust toolchain is not mandatory for kernel compilation, @@ -781,8 +781,8 @@ Both possibilities are described in the following. located in the same directory as the ``Makefile``. The crate may consist of several source files (see ``samples/rust/hostprogs``). -4.5 Controlling compiler options for host programs --------------------------------------------------- +Controlling compiler options for host programs +---------------------------------------------- When compiling host programs, it is possible to set specific flags. The programs will always be compiled utilising $(HOSTCC) passed @@ -813,8 +813,8 @@ Both possibilities are described in the following. When linking qconf, it will be passed the extra option "-L$(QTDIR)/lib". -4.6 When host programs are actually built ------------------------------------------ +When host programs are actually built +------------------------------------- Kbuild will only build host-programs when they are referenced as a prerequisite. @@ -852,8 +852,8 @@ Both possibilities are described in the following. This will tell kbuild to build lxdialog even if not referenced in any rule. -5 Userspace Program support -=========================== +Userspace Program support +========================= Just like host programs, Kbuild also supports building userspace executables for the target architecture (i.e. the same architecture as you are building @@ -862,8 +862,8 @@ the kernel for). The syntax is quite similar. The difference is to use "userprogs" instead of "hostprogs". -5.1 Simple Userspace Program ----------------------------- +Simple Userspace Program +------------------------ The following line tells kbuild that the program bpf-direct shall be built for the target architecture. @@ -876,8 +876,8 @@ The syntax is quite similar. The difference is to use "userprogs" instead of single C source file named bpf-direct.c located in the same directory as the Makefile. -5.2 Composite Userspace Programs --------------------------------- +Composite Userspace Programs +---------------------------- Userspace programs can be made up based on composite objects. The syntax used to define composite objects for userspace programs is @@ -898,8 +898,8 @@ The syntax is quite similar. The difference is to use "userprogs" instead of Finally, the two .o files are linked to the executable, bpf-fancy. Note: The syntax <executable>-y is not permitted for userspace programs. -5.3 Controlling compiler options for userspace programs -------------------------------------------------------- +Controlling compiler options for userspace programs +--------------------------------------------------- When compiling userspace programs, it is possible to set specific flags. The programs will always be compiled utilising $(CC) passed @@ -930,8 +930,8 @@ The syntax is quite similar. The difference is to use "userprogs" instead of From command line, :ref:`USERCFLAGS and USERLDFLAGS <userkbuildflags>` will also be used. -5.4 When userspace programs are actually built ----------------------------------------------- +When userspace programs are actually built +------------------------------------------ Kbuild builds userspace programs only when told to do so. There are two ways to do this. @@ -960,8 +960,8 @@ The syntax is quite similar. The difference is to use "userprogs" instead of This will tell Kbuild to build binderfs_example when it visits this Makefile. -6 Kbuild clean infrastructure -============================= +Kbuild clean infrastructure +=========================== "make clean" deletes most generated files in the obj tree where the kernel is compiled. This includes generated files such as host programs. @@ -1005,8 +1005,8 @@ included in the top level makefile. Instead, arch/$(SRCARCH)/Kbuild can use Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will be visited during "make clean". -7 Architecture Makefiles -======================== +Architecture Makefiles +====================== The top level Makefile sets up the environment and does the preparation, before starting to descend down in the individual directories. @@ -1034,8 +1034,8 @@ When kbuild executes, the following steps are followed (roughly): - Preparing initrd images and the like -7.1 Set variables to tweak the build to the architecture --------------------------------------------------------- +Set variables to tweak the build to the architecture +---------------------------------------------------- KBUILD_LDFLAGS Generic $(LD) options @@ -1049,7 +1049,7 @@ When kbuild executes, the following steps are followed (roughly): KBUILD_LDFLAGS := -m elf_s390 Note: ldflags-y can be used to further customise - the flags used. See section 3.7. + the flags used. See `Non-builtin vmlinux targets - extra-y`_. LDFLAGS_vmlinux Options for $(LD) when linking vmlinux @@ -1208,8 +1208,8 @@ When kbuild executes, the following steps are followed (roughly): KBUILD_VMLINUX_LIBS together specify all the object files used to link vmlinux. -7.2 Add prerequisites to archheaders ------------------------------------- +Add prerequisites to archheaders +-------------------------------- The archheaders: rule is used to generate header files that may be installed into user space by "make header_install". @@ -1218,8 +1218,8 @@ When kbuild executes, the following steps are followed (roughly): architecture itself. -7.3 Add prerequisites to archprepare ------------------------------------- +Add prerequisites to archprepare +-------------------------------- The archprepare: rule is used to list prerequisites that need to be built before starting to descend down in the subdirectories. @@ -1236,8 +1236,8 @@ When kbuild executes, the following steps are followed (roughly): generating offset header files. -7.4 List directories to visit when descending ---------------------------------------------- +List directories to visit when descending +----------------------------------------- An arch Makefile cooperates with the top Makefile to define variables which specify how to build the vmlinux file. Note that there is no @@ -1270,8 +1270,8 @@ When kbuild executes, the following steps are followed (roughly): drivers-$(CONFIG_PM) += arch/sparc/power/ -7.5 Architecture-specific boot images -------------------------------------- +Architecture-specific boot images +--------------------------------- An arch Makefile specifies goals that take the vmlinux file, compress it, wrap it in bootstrapping code, and copy the resulting files @@ -1325,8 +1325,8 @@ When kbuild executes, the following steps are followed (roughly): When "make" is executed without arguments, bzImage will be built. -7.7 Commands useful for building a boot image ---------------------------------------------- +Commands useful for building a boot image +----------------------------------------- Kbuild provides a few macros that are useful when building a boot image. @@ -1392,8 +1392,8 @@ When kbuild executes, the following steps are followed (roughly): targets += $(dtb-y) DTC_FLAGS ?= -p 1024 -7.9 Preprocessing linker scripts --------------------------------- +Preprocessing linker scripts +---------------------------- When the vmlinux image is built, the linker script arch/$(SRCARCH)/kernel/vmlinux.lds is used. @@ -1422,17 +1422,17 @@ When kbuild executes, the following steps are followed (roughly): The kbuild infrastructure for `*lds` files is used in several architecture-specific files. -7.10 Generic header files -------------------------- +Generic header files +-------------------- The directory include/asm-generic contains the header files that may be shared between individual architectures. The recommended approach how to use a generic header file is to list the file in the Kbuild file. - See "8.2 generic-y" for further info on syntax etc. + See `generic-y`_ for further info on syntax etc. -7.11 Post-link pass -------------------- +Post-link pass +-------------- If the file arch/xxx/Makefile.postlink exists, this makefile will be invoked for post-link objects (vmlinux and modules.ko) @@ -1447,8 +1447,8 @@ When kbuild executes, the following steps are followed (roughly): For example, powerpc uses this to check relocation sanity of the linked vmlinux file. -8 Kbuild syntax for exported headers -==================================== +Kbuild syntax for exported headers +================================== The kernel includes a set of headers that is exported to userspace. Many headers can be exported as-is but other headers require a @@ -1467,15 +1467,15 @@ A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and arch/<arch>/include/asm/ to list asm files coming from asm-generic. See subsequent chapter for the syntax of the Kbuild file. -8.1 no-export-headers ---------------------- +no-export-headers +----------------- no-export-headers is essentially used by include/uapi/linux/Kbuild to avoid exporting specific headers (e.g. kvm.h) on architectures that do not support it. It should be avoided as much as possible. -8.2 generic-y -------------- +generic-y +--------- If an architecture uses a verbatim copy of a header from include/asm-generic then this is listed in the file @@ -1504,8 +1504,8 @@ See subsequent chapter for the syntax of the Kbuild file. #include <asm-generic/termios.h> -8.3 generated-y ---------------- +generated-y +----------- If an architecture generates other header files alongside generic-y wrappers, generated-y specifies them. @@ -1518,8 +1518,8 @@ See subsequent chapter for the syntax of the Kbuild file. #arch/x86/include/asm/Kbuild generated-y += syscalls_32.h -8.4 mandatory-y ---------------- +mandatory-y +----------- mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild to define the minimum set of ASM headers that all architectures must have. @@ -1528,8 +1528,8 @@ See subsequent chapter for the syntax of the Kbuild file. in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically generate a wrapper of the asm-generic one. -9 Kbuild Variables -================== +Kbuild Variables +================ The top Makefile exports the following variables: @@ -1596,8 +1596,8 @@ The top Makefile exports the following variables: command. -10 Makefile language -==================== +Makefile language +================= The kernel Makefiles are designed to be run with GNU Make. The Makefiles use only the documented features of GNU Make, but they do use many @@ -1616,16 +1616,16 @@ time the left-hand side is used. There are some cases where "=" is appropriate. Usually, though, ":=" is the right choice. -11 Credits -========== +Credits +======= - Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net> - Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de> - Updates by Sam Ravnborg <sam@ravnborg.org> - Language QA by Jan Engelhardt <jengelh@gmx.de> -12 TODO -======= +TODO +==== - Describe how kbuild supports shipped files with _shipped. - Generating offset header files. |