This document describes the Linux kernel Makefiles.
-1 Overview
-==========
+Overview
+========
The Makefiles have five parts::
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.
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
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
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
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.
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.
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
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.
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.
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
AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
-3.10 Dependency tracking
-------------------------
+Dependency tracking
+-------------------
Kbuild tracks dependencies on the following:
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
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
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
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.
endif
endif
-3.14 $(LD) support functions
-----------------------------
+$(LD) support functions
+-----------------------
ld-option
ld-option is used to check if $(LD) supports the supplied option.
#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
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.
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.
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
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
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,
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
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.
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
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.
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
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
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.
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.
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.
- 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
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
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".
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.
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
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
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.
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.
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)
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
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
#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.
#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.
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:
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
There are some cases where "=" is appropriate. Usually, though, ":="
is the right choice.
-11 Credits
-==========
+Credits
+=======
-12 TODO
-=======
+TODO
+====
- Describe how kbuild supports shipped files with _shipped.
- Generating offset header files.
projects / linux.git / commitdiff