Drop the manually updated section numbering. It's hard to maintain, and
indeed hasn't been updated when sections 3.4 and 7.8 were dropped.
Update all the section references to rst references.
Cc: Masahiro Yamada <masahiroy@xxxxxxxxxx>
Signed-off-by: Jani Nikula <jani.nikula@xxxxxxxxx>
---
Documentation/kbuild/makefiles.rst | 206 ++++++++++++++---------------
1 file changed, 103 insertions(+), 103 deletions(-)
diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index 12cf92320e46..0180a49fefbf 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@xxxxxxxxx>
- Updates by Kai Germaschewski <kai@xxxxxxxxxxxxxxxxxxxxxx>
- Updates by Sam Ravnborg <sam@xxxxxxxxxxxx>
- Language QA by Jan Engelhardt <jengelh@xxxxxx>
-12 TODO
-=======
+TODO
+====
- Describe how kbuild supports shipped files with _shipped.
- Generating offset header files.
--
2.34.1
