summaryrefslogtreecommitdiff
path: root/Documentation/kbuild
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/kbuild')
-rw-r--r--Documentation/kbuild/makefiles.rst206
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.