===Documentation/kbuild/makefiles.txt===
The Makefiles have five parts:
- Makefile the top Makefile.
- .config the kernel configuration file.
- arch/$(ARCH)/Makefile the arch Makefile.
- scripts/Makefile.* common rules etc. for all kbuild Makefiles.
- kbuild Makefiles there are about 500 of these.
The top Makefile reads the .config file, which comes from the kernel
configuration process.
The top Makefile is responsible for building two major products: vmlinux
(the resident kernel image) and modules (any module files).
(the resident kernel image) and modules (any module files).
顶层Makefile负责编译vmlinux和内核模块modules.
It builds these goals by recursively descending into the subdirectories of
the kernel source tree.
the kernel source tree.
通过从内核源码树向下递归各级子目录来完成vmlinux和modues的编译。
The list of subdirectories which are visited depends upon the kernel
configuration.
configuration.
各级子目录列表依赖于内核配置。这个configuration具体是指什么暂不确定。(.config)
The top Makefile textually includes an arch Makefile with the name arch/$(ARCH)/Makefile. The arch Makefile supplies
architecture-specific information to the top Makefile.
architecture-specific information to the top Makefile.
顶层Makefile包含arch/$(ARCH)/Makefile。arch Makefile 向顶层Makefile提供具体的架构信息。
Each subdirectory has a kbuild Makefile which carries out the commands passed down from above. The kbuild Makefile uses information from the .config file to construct various file lists used by kbuild to build any built-in or modular targets.
每个子目录有一个kbuild Makefile,kbuild Makefile 执行上一级目录传递下来的命令。kbuild Makefile 使用.config中的配置信息来生成不同的文件列表，这些列表被用来编译指明相应的对象是编译进内核还是编译成模块。
scripts/Makefile.* contains all the definitions/rules etc. that are used to build the kernel based on the kbuild makefiles.
scripts/Makefile.*可看成是一些编译工具。
=== 2 Who does what
People have four different relationships with the kernel Makefiles.
*Users* are people who build kernels. These people type commands such as
"make menuconfig" or "make". They usually do not read or edit
any kernel Makefiles (or any other source files).
*Normal developers* are people who work on features such as device
drivers, file systems, and network protocols. These people need to
maintain the kbuild Makefiles for the subsystem they are
working on. In order to do this effectively, they need some overall
knowledge about the kernel Makefiles, plus detailed knowledge about the
public interface for kbuild.
*Arch developers* are people who work on an entire architecture, such
as sparc or ia64. Arch developers need to know about the arch Makefile
as well as kbuild Makefiles.
*Kbuild developers* are people who work on the kernel build system itself.
These people need to know about all aspects of the kernel Makefiles.
This document is aimed towards normal developers and arch developers.
People have four different relationships with the kernel Makefiles.
*Users* are people who build kernels. These people type commands such as
"make menuconfig" or "make". They usually do not read or edit
any kernel Makefiles (or any other source files).
*Normal developers* are people who work on features such as device
drivers, file systems, and network protocols. These people need to
maintain the kbuild Makefiles for the subsystem they are
working on. In order to do this effectively, they need some overall
knowledge about the kernel Makefiles, plus detailed knowledge about the
public interface for kbuild.
*Arch developers* are people who work on an entire architecture, such
as sparc or ia64. Arch developers need to know about the arch Makefile
as well as kbuild Makefiles.
*Kbuild developers* are people who work on the kernel build system itself.
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
Most Makefiles within the kernel are kbuild Makefiles that use the kbuild infrastructure. This chapter introduces the syntax used in the kbuild makefiles. 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.
内核中的大多数Makefile文件都是kbuild Makefiles。kbuild Makefiles有自己特有的语法。kbuild 文件的名字优先使用Makefile,Kbuild也可以使用。当Makefile和Kbuild同时存在时，Kbuild系统会使用Kbuild文件。
Section 3.1 "Goal definitions" is a quick intro, further chapters provide
more details, with real examples.
--- 3.1 Goal definitions
Goal definitions are the main part (heart) of the kbuild Makefile. 全局变量是kbuild Makefile的主要部分。
These lines define the files to be built, any special compilation 定义哪些文件将被编译，指定编译选项，向下递归的子目录
options, and any subdirectories to be entered recursively.
The most simple kbuild makefile contains one line:
Example:
obj-y += foo.o
This tells kbuild that there is one object in that directory, named obj-y告诉kbuild系统，当前目录下将编译生成一个名为foo.o
more details, with real examples.
--- 3.1 Goal definitions
Goal definitions are the main part (heart) of the kbuild Makefile. 全局变量是kbuild Makefile的主要部分。
These lines define the files to be built, any special compilation 定义哪些文件将被编译，指定编译选项，向下递归的子目录
options, and any subdirectories to be entered recursively.
The most simple kbuild makefile contains one line:
Example:
obj-y += foo.o
This tells kbuild that there is one object in that directory, named obj-y告诉kbuild系统，当前目录下将编译生成一个名为foo.o
foo.o. foo.o will be built from foo.c or foo.S. 的对象 由foo.c or foo.S 编译得到，且该对象将被编译进内核
If foo.o shall be built as a module, the variable obj-m is used. 如果将该对象编译成modules,则使用obj-m变量。
Therefore the following pattern is often used:
Example:
obj-$(CONFIG_FOO) += foo.o
$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module). $(CONFIG_FOO) 决定当前对象是编译进内核还是模块
If CONFIG_FOO is neither y nor m, then the file will not be compiled 或是该文件不会被编译或链接。
nor linked.
Therefore the following pattern is often used:
Example:
obj-$(CONFIG_FOO) += foo.o
$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module). $(CONFIG_FOO) 决定当前对象是编译进内核还是模块
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
The kbuild Makefile specifies object files for vmlinux vmlinux中的目标文件包含在$(obj-y) lists 中，
in the $(obj-y) lists. These lists depend on the kernel $(obj-？) lists 中的目标是否编译进内核取决于.config。
The kbuild Makefile specifies object files for vmlinux vmlinux中的目标文件包含在$(obj-y) lists 中，
in the $(obj-y) lists. These lists depend on the kernel $(obj-？) lists 中的目标是否编译进内核取决于.config。
configuration.
Kbuild compiles all the $(obj-y) files. It then calls Kbuild会编译所有的 $(obj-y) files ，并用"$(LD) -r" 将各级子目录
"$(LD) -r" to merge these files into one built-in.o file. 下的built-in.o 连接成顶层目录下的一个built-in.o ，
built-in.o is later linked into vmlinux by the parent Makefile. 上一级目录的Makefile将负责打包子目录的各个built-in.o，依此类推
The order of files in $(obj-y) is significant. Duplicates in $(obj-y) 中的文件是有一定次序的。列表中允许重复的目标，
the lists are allowed: the first instance will be linked into 最先遇到的目标将被链接进built-in.o，之后的重复目标将被忽略。
built-in.o and succeeding instances will be ignored.
Link order is significant, because certain functions 链接也是有序的。在boot过程中，有些函数将根据其出现的次序被
(module_init() / __initcall) will be called during boot in the 依次调用。 (如module_init() / __initcall)
order they appear. So keep in mind that changing the link 改变链接次序可能导致SCSI控制器的次序，将会使磁盘
order may e.g. change the order in which your SCSI 被重新编号。
controllers are detected, and thus your disks are renumbered.
Example:
#drivers/isdn/i4l/Makefile
# Makefile for the kernel ISDN subsystem and device drivers.
# Each configuration option enables a list of files.
obj-$(CONFIG_ISDN_I4L) += isdn.o
obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
Kbuild compiles all the $(obj-y) files. It then calls Kbuild会编译所有的 $(obj-y) files ，并用"$(LD) -r" 将各级子目录
"$(LD) -r" to merge these files into one built-in.o file. 下的built-in.o 连接成顶层目录下的一个built-in.o ，
built-in.o is later linked into vmlinux by the parent Makefile. 上一级目录的Makefile将负责打包子目录的各个built-in.o，依此类推
The order of files in $(obj-y) is significant. Duplicates in $(obj-y) 中的文件是有一定次序的。列表中允许重复的目标，
the lists are allowed: the first instance will be linked into 最先遇到的目标将被链接进built-in.o，之后的重复目标将被忽略。
built-in.o and succeeding instances will be ignored.
Link order is significant, because certain functions 链接也是有序的。在boot过程中，有些函数将根据其出现的次序被
(module_init() / __initcall) will be called during boot in the 依次调用。 (如module_init() / __initcall)
order they appear. So keep in mind that changing the link 改变链接次序可能导致SCSI控制器的次序，将会使磁盘
order may e.g. change the order in which your SCSI 被重新编号。
controllers are detected, and thus your disks are renumbered.
Example:
#drivers/isdn/i4l/Makefile
# Makefile for the kernel ISDN subsystem and device drivers.
# Each configuration option enables a list of files.
obj-$(CONFIG_ISDN_I4L) += isdn.o
obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
--- 3.3 Loadable module goals - obj-m
$(obj-m) specify object files which are built as loadable $(obj-m) 指定的目标文件将被编译成可加载的内核模块
kernel modules.
A module may be built from one source file or several source 仅有一个源文件的内核模块的简单Makefile的写法
files. In the case of one source file, the kbuild makefile
simply adds the file to $(obj-m).
Example:
#drivers/isdn/i4l/Makefile
obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
If a kernel module is built from several source files, you specify 当一个内核模块是由多个目标文件构成时，需要通过
that you want to build a module in the same way as above; however, $(<module_name>-y)变量设置需要编译的目标文件。
kbuild needs to know which object files you want to build your
module from, so you have to tell it by setting a $(<module_name>-y)
variable.
Example:
#drivers/isdn/i4l/Makefile
obj-$(CONFIG_ISDN_I4L) += isdn.o
isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
In this example, the module name will be isdn.o. Kbuild will 在这个例子中，模块名是isdn.o，Kbuild将编译
compile the objects listed in $(isdn-y) and then run $(isdn-y)中的对象，然后执行"$(LD) -r"将这些目标文件
"$(LD) -r" on the list of these files to generate isdn.o. 链接成isdn.o。
Due to kbuild recognizing $(<module_name>-y) for composite objects,
you can use the value of a CONFIG_ symbol to optionally include an
object file as part of a composite object.
Example:
#fs/ext2/Makefile
obj-$(CONFIG_EXT2_FS) += ext2.o
ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o
namei.o super.o symlink.o
ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o
xattr_trusted.o
In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
evaluates to 'y'.
Note: Of course, when you are building objects into the kernel,
the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
kbuild will build an ext2.o file for you out of the individual
parts and then link this into built-in.o, as you would expect.
$(obj-m) specify object files which are built as loadable $(obj-m) 指定的目标文件将被编译成可加载的内核模块
kernel modules.
A module may be built from one source file or several source 仅有一个源文件的内核模块的简单Makefile的写法
files. In the case of one source file, the kbuild makefile
simply adds the file to $(obj-m).
Example:
#drivers/isdn/i4l/Makefile
obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
If a kernel module is built from several source files, you specify 当一个内核模块是由多个目标文件构成时，需要通过
that you want to build a module in the same way as above; however, $(<module_name>-y)变量设置需要编译的目标文件。
kbuild needs to know which object files you want to build your
module from, so you have to tell it by setting a $(<module_name>-y)
variable.
Example:
#drivers/isdn/i4l/Makefile
obj-$(CONFIG_ISDN_I4L) += isdn.o
isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
In this example, the module name will be isdn.o. Kbuild will 在这个例子中，模块名是isdn.o，Kbuild将编译
compile the objects listed in $(isdn-y) and then run $(isdn-y)中的对象，然后执行"$(LD) -r"将这些目标文件
"$(LD) -r" on the list of these files to generate isdn.o. 链接成isdn.o。
Due to kbuild recognizing $(<module_name>-y) for composite objects,
you can use the value of a CONFIG_ symbol to optionally include an
object file as part of a composite object.
Example:
#fs/ext2/Makefile
obj-$(CONFIG_EXT2_FS) += ext2.o
ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o
namei.o super.o symlink.o
ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o
xattr_trusted.o
In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
evaluates to 'y'.
Note: Of course, when you are building objects into the kernel,
the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
kbuild will build an ext2.o file for you out of the individual
parts and then link this into built-in.o, as you would expect.
--- 3.4 Objects which export symbols
No special notation is required in the makefiles for
modules exporting symbols.
No special notation is required in the makefiles for
modules exporting symbols.
--- 3.5 Library file goals - lib-y
Objects listed with obj-* are used for modules, or
combined in a built-in.o for that specific directory.
There is also the possibility to list objects that will
be included in a library, lib.a.
All objects listed with lib-y are combined in a single lib-y中的目标将被组合成一个lib.a库，放在当前目录下
library for that directory.
Objects that are listed in obj-y and additionally listed in 既在obj-y 列表中又在lib-y 列表中的目标将不会被包含在库中
lib-y will not be included in the library, since they will 因为obj-y中的目标总能访问到。
be accessible anyway.
For consistency, objects listed in lib-m will be included in lib.a. lib-m 中的目标会包含在lib.a中。
Note that the same kbuild makefile may list files to be built-in
and to be part of a library. Therefore the same directory
may contain both a built-in.o and a lib.a file.
Example:
#arch/x86/lib/Makefile
lib-y := delay.o
This will create a library lib.a based on delay.o. For kbuild to
actually recognize that there is a lib.a being built, the directory
shall be listed in libs-y.
See also "6.4 List directories to visit when descending".
Use of lib-y is normally restricted to lib/ and arch/*/lib.
Objects listed with obj-* are used for modules, or
combined in a built-in.o for that specific directory.
There is also the possibility to list objects that will
be included in a library, lib.a.
All objects listed with lib-y are combined in a single lib-y中的目标将被组合成一个lib.a库，放在当前目录下
library for that directory.
Objects that are listed in obj-y and additionally listed in 既在obj-y 列表中又在lib-y 列表中的目标将不会被包含在库中
lib-y will not be included in the library, since they will 因为obj-y中的目标总能访问到。
be accessible anyway.
For consistency, objects listed in lib-m will be included in lib.a. lib-m 中的目标会包含在lib.a中。
Note that the same kbuild makefile may list files to be built-in
and to be part of a library. Therefore the same directory
may contain both a built-in.o and a lib.a file.
Example:
#arch/x86/lib/Makefile
lib-y := delay.o
This will create a library lib.a based on delay.o. For kbuild to
actually recognize that there is a lib.a being built, the directory
shall be listed in libs-y.
See also "6.4 List directories to visit when descending".
Use of lib-y is normally restricted to lib/ and arch/*/lib.
--- 3.6 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
Makefiles in these subdirs. The build system will automatically
invoke make recursively in subdirectories, provided you let it know of
them.
To do so, obj-y and obj-m are used.
ext2 lives in a separate directory, and the Makefile present in fs/
tells kbuild to descend down using the following assignment. fs
A Makefile is only responsible for building objects in its own
directory. Files in subdirectories should be taken care of by
Makefiles in these subdirs. The build system will automatically
invoke make recursively in subdirectories, provided you let it know of
them.
To do so, obj-y and obj-m are used.
ext2 lives in a separate directory, and the Makefile present in fs/
tells kbuild to descend down using the following assignment. fs
|-- Makefile
Example: `-- ext2
#fs/Makefile |-- Makefile
obj-$(CONFIG_EXT2_FS) += ext2/ |-- *
If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
the corresponding obj- variable will be set, and kbuild will descend
down in the ext2 directory.
Kbuild only uses this information to decide that it needs to visit Kbuild只是根据该信息判断要访问子目录，
the directory, it is the Makefile in the subdirectory that 至于在子目录下做什么，有子目录的Makefile决定。
specifies what is modules and what is built-in.
It is good practice to use a CONFIG_ variable when assigning directory
names. This allows kbuild to totally skip the directory if the
corresponding CONFIG_ option is neither 'y' nor 'm'.
Example: `-- ext2
#fs/Makefile |-- Makefile
obj-$(CONFIG_EXT2_FS) += ext2/ |-- *
If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
the corresponding obj- variable will be set, and kbuild will descend
down in the ext2 directory.
Kbuild only uses this information to decide that it needs to visit Kbuild只是根据该信息判断要访问子目录，
the directory, it is the Makefile in the subdirectory that 至于在子目录下做什么，有子目录的Makefile决定。
specifies what is modules and what is built-in.
It is good practice to use a CONFIG_ variable when assigning directory
names. This allows kbuild to totally skip the directory if the
corresponding CONFIG_ option is neither 'y' nor 'm'.
--- 3.7 Compilation flags
ccflags-y, asflags-y and ldflags-y
These three flags apply only to the kbuild makefile in which they ccflags-y, asflags-y and ldflags-y 只在当前被指定
are assigned. They are used for all the normal cc, as and ld Makefile中有效。当前Makefile的所有目标的cc,as,ld
invocations happening during a recursive build. 均有效。
Note: Flags with the same behaviour were previously named:
EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
They are still supported but their usage is deprecated.
ccflags-y specifies options for compiling with $(CC).
Example:
# drivers/acpi/Makefile
ccflags-y := -Os
ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT
This variable is necessary because the top Makefile owns the
variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
entire tree.
asflags-y specifies options for assembling with $(AS).
Example:
#arch/sparc/kernel/Makefile
asflags-y := -ansi
ldflags-y specifies options for linking with $(LD).
Example:
#arch/cris/boot/compressed/Makefile
ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
subdir-ccflags-y, subdir-asflags-y
The two flags listed above are similar to ccflags-y and asflags-y.
The difference is that the subdir- variants have effect for the kbuild 对当前目录和所有子目录均有效
file where they are present and all subdirectories.
Options specified using subdir-* are added to the commandline before
the options specified using the non-subdir variants.
Example:
subdir-ccflags-y := -Werror
CFLAGS_$@, AFLAGS_$@
CFLAGS_$@ and AFLAGS_$@ only apply to commands in current 仅对当前Makefile有效，并只对指定的目标有效。
kbuild makefile.
$(CFLAGS_$@) specifies per-file options for $(CC). The $@
part has a literal value which specifies the file that it is for.
Example:
# drivers/scsi/Makefile
CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF
CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__
-DGDTH_STATISTICS
These two lines specify compilation flags for aha152x.o and gdth.o.
$(AFLAGS_$@) is a similar feature for source files in assembly
languages.
Example:
# arch/arm/kernel/Makefile
AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET)
AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
ccflags-y, asflags-y and ldflags-y
These three flags apply only to the kbuild makefile in which they ccflags-y, asflags-y and ldflags-y 只在当前被指定
are assigned. They are used for all the normal cc, as and ld Makefile中有效。当前Makefile的所有目标的cc,as,ld
invocations happening during a recursive build. 均有效。
Note: Flags with the same behaviour were previously named:
EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
They are still supported but their usage is deprecated.
ccflags-y specifies options for compiling with $(CC).
Example:
# drivers/acpi/Makefile
ccflags-y := -Os
ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT
This variable is necessary because the top Makefile owns the
variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
entire tree.
asflags-y specifies options for assembling with $(AS).
Example:
#arch/sparc/kernel/Makefile
asflags-y := -ansi
ldflags-y specifies options for linking with $(LD).
Example:
#arch/cris/boot/compressed/Makefile
ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
subdir-ccflags-y, subdir-asflags-y
The two flags listed above are similar to ccflags-y and asflags-y.
The difference is that the subdir- variants have effect for the kbuild 对当前目录和所有子目录均有效
file where they are present and all subdirectories.
Options specified using subdir-* are added to the commandline before
the options specified using the non-subdir variants.
Example:
subdir-ccflags-y := -Werror
CFLAGS_$@, AFLAGS_$@
CFLAGS_$@ and AFLAGS_$@ only apply to commands in current 仅对当前Makefile有效，并只对指定的目标有效。
kbuild makefile.
$(CFLAGS_$@) specifies per-file options for $(CC). The $@
part has a literal value which specifies the file that it is for.
Example:
# drivers/scsi/Makefile
CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF
CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__
-DGDTH_STATISTICS
These two lines specify compilation flags for aha152x.o and gdth.o.
$(AFLAGS_$@) is a similar feature for source files in assembly
languages.
Example:
# arch/arm/kernel/Makefile
AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET)
AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
作用范围：
subdir-ccflags-y, subdir-asflags-y > ccflags-y, asflags-y and ldflags-y > CFLAGS_$@, AFLAGS_$@
--- 3.9 Dependency tracking
Kbuild tracks dependencies on the following:
1) All prerequisite files (both *.c and *.h)
2) CONFIG_ options used in all prerequisite files
3) Command-line used to compile target
Thus, if you change an option to $(CC) all affected files will
be re-compiled.
Kbuild tracks dependencies on the following:
1) All prerequisite files (both *.c and *.h)
2) CONFIG_ options used in all prerequisite files
3) Command-line used to compile target
Thus, if you change an option to $(CC) all affected files will
be re-compiled.
--- 3.10 Special Rules
Special rules are used when the kbuild infrastructure does 当kbuild 结构不能提供相应请求的支持时需要使用一些特殊
not provide the required support. A typical example is 规则。一个典型的例子是编译过程中生成头文件。另一个例子
header files generated during the build process. 是某些架构的Makefile需要一些特殊规则制作引导镜像
Another example are the architecture-specific Makefiles which
need special rules to prepare boot images etc.
Special rules are written as normal Make rules. 特殊规则的语法和普通Make规则相同。
Kbuild is not executing in the directory where the Makefile is 在Makefile所在的目录中，Kbuild不会执行，所以
located, so all special rules shall provide a relative 需使用特殊规则为依赖文件和目标文件提供相对路径。
path to prerequisite files and target files.
Two variables are used when defining special rules: 定义特殊规则时将用到一下两个变量
$(src)
$(src) is a relative path which points to the directory $(src) 指向Makefile所在路径，
where the Makefile is located. Always use $(src) when 通常在使用源码树中的代码时，需使用$(src)
referring to files located in the src tree.
$(obj)
$(obj) is a relative path which points to the directory $(obj)指向保存目标文件的相对路径
Special rules are used when the kbuild infrastructure does 当kbuild 结构不能提供相应请求的支持时需要使用一些特殊
not provide the required support. A typical example is 规则。一个典型的例子是编译过程中生成头文件。另一个例子
header files generated during the build process. 是某些架构的Makefile需要一些特殊规则制作引导镜像
Another example are the architecture-specific Makefiles which
need special rules to prepare boot images etc.
Special rules are written as normal Make rules. 特殊规则的语法和普通Make规则相同。
Kbuild is not executing in the directory where the Makefile is 在Makefile所在的目录中，Kbuild不会执行，所以
located, so all special rules shall provide a relative 需使用特殊规则为依赖文件和目标文件提供相对路径。
path to prerequisite files and target files.
Two variables are used when defining special rules: 定义特殊规则时将用到一下两个变量
$(src)
$(src) is a relative path which points to the directory $(src) 指向Makefile所在路径，
where the Makefile is located. Always use $(src) when 通常在使用源码树中的代码时，需使用$(src)
referring to files located in the src tree.
$(obj)
$(obj) is a relative path which points to the directory $(obj)指向保存目标文件的相对路径
where the target is saved. Always use $(obj) when
referring to generated files.
Example:
#drivers/scsi/Makefile
$(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
$(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
This is a special rule, following the normal syntax 上面就是一个特殊规则，其语法和make语法规则相同。
required by make.
The target file depends on two prerequisite files. References 目标文件依赖于两个依赖文件。目标文件以$(obj)为前缀，
to the target file are prefixed with $(obj), references 依赖文件以$(src)为前缀
to prerequisites are referenced with $(src) (because they are not
generated files).
$(kecho)
echoing information to user in a rule is often a good practice 在规则中打印信息给用户是一种好的体验，但是当
but when execution "make -s" one does not expect to see any output 执行“make -s”后将不用输出打印信息，
except for warnings/errors. 除了警告/错误信息外。
To support this kbuild define $(kecho) which will echo out the kbuild将使用$(kecho) 打印输出信息，除非
text following $(kecho) to stdout except if "make -s" is used. "make -s"被使用。
Example:
#arch/blackfin/boot/Makefile
$(obj)/vmImage: $(obj)/vmlinux.gz
$(call if_changed,uimage)
@$(kecho) 'Kernel: $@ is ready'
referring to generated files.
Example:
#drivers/scsi/Makefile
$(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
$(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
This is a special rule, following the normal syntax 上面就是一个特殊规则，其语法和make语法规则相同。
required by make.
The target file depends on two prerequisite files. References 目标文件依赖于两个依赖文件。目标文件以$(obj)为前缀，
to the target file are prefixed with $(obj), references 依赖文件以$(src)为前缀
to prerequisites are referenced with $(src) (because they are not
generated files).
$(kecho)
echoing information to user in a rule is often a good practice 在规则中打印信息给用户是一种好的体验，但是当
but when execution "make -s" one does not expect to see any output 执行“make -s”后将不用输出打印信息，
except for warnings/errors. 除了警告/错误信息外。
To support this kbuild define $(kecho) which will echo out the kbuild将使用$(kecho) 打印输出信息，除非
text following $(kecho) to stdout except if "make -s" is used. "make -s"被使用。
Example:
#arch/blackfin/boot/Makefile
$(obj)/vmImage: $(obj)/vmlinux.gz
$(call if_changed,uimage)
@$(kecho) 'Kernel: $@ is ready'
--- 3.11 $(CC) support functions
The kernel may be built with several different versions of 内核可能由不同版本的$(CC)编译，而每个版本的编译器都
$(CC), each supporting a unique set of features and options. 有一些特有的功能和选项。kbuild提供了一些基础支持来检测
kbuild provide basic support to check for valid options for $(CC). $(CC)的选项是否有效。通常$(CC)是gcc 编译器，但也可以
$(CC) is usually the gcc compiler, but other alternatives are 是其他编译器。
available.
as-option
as-option is used to check if $(CC) -- when used to compile as-option 用于检测$(CC)在汇编*.S文件时，
assembler (*.S) files -- supports the given option. An optional 是否支持给定的选项 。如果第一个选项不支持的话，
second option may be specified if the first option is not supported. 则指定第二个选项。
Example:
#arch/sh/Makefile
cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
In the above example, cflags-y will be assigned the option
-Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
The second argument is optional, and if supplied will be used 第二个参数是可选的，当第一个参数不支持，就会用参数。
if first argument is not supported.
cc-ldoption
cc-ldoption is used to check if $(CC) when used to link object files cc-ldoption 用于检测$(CC) 在链接时，是否支持给定
supports the given option. An optional second option may be 的选项。如果第一个选项不支持的话，
specified if first option are not supported. 则可指定第二个选项。
Example:
#arch/x86/kernel/Makefile
vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
In the above example, vsyscall-flags will be assigned the option
-Wl$(comma)--hash-style=sysv if it is supported by $(CC).
The second argument is optional, and if supplied will be used
if first argument is not supported.
as-instr
as-instr checks if the assembler reports a specific instruction 汇编器是否支持报告指定的指令，
and then outputs either option1 or option2 然后输出option1或option2
C escapes are supported in the test instruction 在测试指令中，支持C 转义字符
Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options as-instr-option在$(AS)选项中使用KBUILD_AFLAGS变量.
The kernel may be built with several different versions of 内核可能由不同版本的$(CC)编译，而每个版本的编译器都
$(CC), each supporting a unique set of features and options. 有一些特有的功能和选项。kbuild提供了一些基础支持来检测
kbuild provide basic support to check for valid options for $(CC). $(CC)的选项是否有效。通常$(CC)是gcc 编译器，但也可以
$(CC) is usually the gcc compiler, but other alternatives are 是其他编译器。
available.
as-option
as-option is used to check if $(CC) -- when used to compile as-option 用于检测$(CC)在汇编*.S文件时，
assembler (*.S) files -- supports the given option. An optional 是否支持给定的选项 。如果第一个选项不支持的话，
second option may be specified if the first option is not supported. 则指定第二个选项。
Example:
#arch/sh/Makefile
cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
In the above example, cflags-y will be assigned the option
-Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
The second argument is optional, and if supplied will be used 第二个参数是可选的，当第一个参数不支持，就会用参数。
if first argument is not supported.
cc-ldoption
cc-ldoption is used to check if $(CC) when used to link object files cc-ldoption 用于检测$(CC) 在链接时，是否支持给定
supports the given option. An optional second option may be 的选项。如果第一个选项不支持的话，
specified if first option are not supported. 则可指定第二个选项。
Example:
#arch/x86/kernel/Makefile
vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
In the above example, vsyscall-flags will be assigned the option
-Wl$(comma)--hash-style=sysv if it is supported by $(CC).
The second argument is optional, and if supplied will be used
if first argument is not supported.
as-instr
as-instr checks if the assembler reports a specific instruction 汇编器是否支持报告指定的指令，
and then outputs either option1 or option2 然后输出option1或option2
C escapes are supported in the test instruction 在测试指令中，支持C 转义字符
Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options as-instr-option在$(AS)选项中使用KBUILD_AFLAGS变量.
cc-option
cc-option is used to check if $(CC) supports a given option, and not 检查$(CC)是否支特定选项,并且不支持使用可选的第二项
supported to use an optional second option.
Example:
#arch/x86/Makefile
cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
In the above example, cflags-y will be assigned the option
-march=pentium-mmx if supported by $(CC), otherwise -march=i586.
The second argument to cc-option is optional, and if omitted,
cflags-y will be assigned no value if first option is not supported.
Note: cc-option uses KBUILD_CFLAGS for $(CC) options
cc-option-yn
cc-option-yn is used to check if gcc supports a given option
and return 'y' if supported, otherwise 'n'.
Example:
#arch/ppc/Makefile
biarch := $(call cc-option-yn, -m32)
aflags-$(biarch) += -a32
cflags-$(biarch) += -m32
In the above example, $(biarch) is set to y if $(CC) supports the -m32
option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
and $(cflags-y) will be assigned the values -a32 and -m32,
respectively.
Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
cc-option-align
gcc versions >= 3.0 changed the type of options used to specify 大于3.0版本的gcc编译器,.
alignment of functions, loops etc. $(cc-option-align), when used 改变了对函数/循环中用于指定内存对齐的选项类型
as prefix to the align options, will select the right prefix: $(cc-option-align)就作为对齐选项的前缀,
gcc < 3.00 当用到对齐选项时,$(cc-option-align)用来选择正确的前缀
cc-option-align = -malign
gcc >= 3.00
cc-option-align = -falign
Example:
KBUILD_CFLAGS += $(cc-option-align)-functions=4
In the above example, the option -falign-functions=4 is used for
gcc >= 3.00. For gcc < 3.00, -malign-functions=4 is used.
Note: cc-option-align uses KBUILD_CFLAGS for $(CC) options
cc-disable-warning
cc-disable-warning checks if gcc supports a given warning and returns
the commandline switch to disable it. This special function is needed,
because gcc 4.4 and later accept any unknown -Wno-* option and only
warn about it if there is another warning in the source file.
Example:
KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)
In the above example, -Wno-unused-but-set-variable will be added to
KBUILD_CFLAGS only if gcc really accepts it.
cc-version
cc-version returns a numerical version of the $(CC) compiler version.
The format is <major><minor> where both are two digits. So for example
gcc 3.41 would return 0341.
cc-version is useful when a specific $(CC) version is faulty in one
area, for example -mregparm=3 was broken in some gcc versions
even though the option was accepted by gcc.
Example:
#arch/x86/Makefile
cflags-y += $(shell
if [ $(call cc-version) -ge 0300 ] ; then
echo "-mregparm=3"; fi ;)
In the above example, -mregparm=3 is only used for gcc version greater
than or equal to gcc 3.0.
cc-ifversion
cc-ifversion tests the version of $(CC) and equals last argument if
version expression is true.
Example:
#fs/reiserfs/Makefile
ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
In this example, ccflags-y will be assigned the value -O1 if the
$(CC) version is less than 4.2.
cc-ifversion takes all the shell operators:
-eq, -ne, -lt, -le, -gt, and -ge
The third parameter may be a text as in this example, but it may also
be an expanded variable or a macro.
cc-fullversion
cc-fullversion is useful when the exact version of gcc is needed.
One typical use-case is when a specific GCC version is broken.
cc-fullversion points out a more specific version than cc-version does.
Example:
#arch/powerpc/Makefile
$(Q)if test "$(call cc-fullversion)" = "040200" ; then
echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ;
false ;
fi
In this example for a specific GCC version the build will error out explaining
to the user why it stops.
cc-cross-prefix
cc-cross-prefix is used to check if there exists a $(CC) in path with 检测PATH中的$(CC)是否存在包含前缀列表之一.
one of the listed prefixes. The first prefix where there exist a PATH中如果prefix$(CC)的前缀和第一个参数前缀
prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found 匹配，则返回在前缀。
then nothing is returned.
Additional prefixes are separated by a single space in the 附加前缀由一个空格分开。
call of cc-cross-prefix.
This functionality is useful for architecture Makefiles that try
to set CROSS_COMPILE to well-known values but may have several
values to select between.
It is recommended only to try to set CROSS_COMPILE if it is a cross
build (host arch is different from target arch). And if CROSS_COMPILE
is already set then leave it with the old value.
Example:
#arch/m68k/Makefile
ifneq ($(SUBARCH),$(ARCH))
ifeq ($(CROSS_COMPILE),)
CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
endif
endif
prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found 匹配，则返回在前缀。
then nothing is returned.
Additional prefixes are separated by a single space in the 附加前缀由一个空格分开。
call of cc-cross-prefix.
This functionality is useful for architecture Makefiles that try
to set CROSS_COMPILE to well-known values but may have several
values to select between.
It is recommended only to try to set CROSS_COMPILE if it is a cross
build (host arch is different from target arch). And if CROSS_COMPILE
is already set then leave it with the old value.
Example:
#arch/m68k/Makefile
ifneq ($(SUBARCH),$(ARCH))
ifeq ($(CROSS_COMPILE),)
CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
endif
endif
--- 3.12 $(LD) support functions
ld-option
ld-option is used to check if $(LD) supports the supplied option. 检测$(LD) 是否支持参数选项
ld-option takes two options as arguments.
The second argument is an optional option that can be used if the
first option is not supported by $(LD).
Example:
#Makefile
LDFLAGS_vmlinux += $(call really-ld-option, -X)
ld-option
ld-option is used to check if $(LD) supports the supplied option. 检测$(LD) 是否支持参数选项
ld-option takes two options as arguments.
The second argument is an optional option that can be used if the
first option is not supported by $(LD).
Example:
#Makefile
LDFLAGS_vmlinux += $(call really-ld-option, -X)
=== 4 Host Program support
Kbuild supports building executables on the host for use during the 在编译内核的同时可生成主机的可执行程序。
compilation stage.
Two steps are required in order to use a host executable.
The first step is to tell kbuild that a host program exists. This is 第一步：使用变量hostprogs-y
done utilising the variable hostprogs-y. 告诉kbuild系统要生成一个host program.
The second step is to add an explicit dependency to the executable.
This can be done in two ways. Either add the dependency in a rule,
or utilise the variable $(always).
Both possibilities are described in the following.
Kbuild supports building executables on the host for use during the 在编译内核的同时可生成主机的可执行程序。
compilation stage.
Two steps are required in order to use a host executable.
The first step is to tell kbuild that a host program exists. This is 第一步：使用变量hostprogs-y
done utilising the variable hostprogs-y. 告诉kbuild系统要生成一个host program.
The second step is to add an explicit dependency to the executable.
This can be done in two ways. Either add the dependency in a rule,
or utilise the variable $(always).
Both possibilities are described in the following.
--- 4.1 Simple Host Program
In some cases there is a need to compile and run a program on the 在某些情况下，编译正在进行时需要运行一个程序。
computer where the build is running.
The following line tells kbuild that the program bin2hex shall be 下面的一句告诉kbuild,需要编译生成bin2hex可执行程序。
built on the build host.
Example:
hostprogs-y := bin2hex
Kbuild assumes in the above example that bin2hex is made from a single kbuild编译bin2hex.c在当前目录生成bin2hex
c-source file named bin2hex.c located in the same directory as
the Makefile.
In some cases there is a need to compile and run a program on the 在某些情况下，编译正在进行时需要运行一个程序。
computer where the build is running.
The following line tells kbuild that the program bin2hex shall be 下面的一句告诉kbuild,需要编译生成bin2hex可执行程序。
built on the build host.
Example:
hostprogs-y := bin2hex
Kbuild assumes in the above example that bin2hex is made from a single kbuild编译bin2hex.c在当前目录生成bin2hex
c-source file named bin2hex.c located in the same directory as
the Makefile.
--- 4.2 Composite Host Programs
Host programs can be made up based on composite objects.
The syntax used to define composite objects for host programs is
similar to the syntax used for kernel objects.
$(<executable>-objs) lists all objects used to link the final
executable.
Example:
#scripts/lxdialog/Makefile
hostprogs-y := lxdialog
lxdialog-objs := checklist.o lxdialog.o
Objects with extension .o are compiled from the corresponding .c
files. In the above example, checklist.c is compiled to checklist.o
and lxdialog.c is compiled to lxdialog.o.
Finally, the two .o files are linked to the executable, lxdialog.
Note: The syntax <executable>-y is not permitted for host-programs.
Host programs can be made up based on composite objects.
The syntax used to define composite objects for host programs is
similar to the syntax used for kernel objects.
$(<executable>-objs) lists all objects used to link the final
executable.
Example:
#scripts/lxdialog/Makefile
hostprogs-y := lxdialog
lxdialog-objs := checklist.o lxdialog.o
Objects with extension .o are compiled from the corresponding .c
files. In the above example, checklist.c is compiled to checklist.o
and lxdialog.c is compiled to lxdialog.o.
Finally, the two .o files are linked to the executable, lxdialog.
Note: The syntax <executable>-y is not permitted for host-programs.
--- 4.3 Defining shared libraries
Objects with extension .so are considered shared libraries, and
will be compiled as position independent objects.
Kbuild provides support for shared libraries, but the usage
shall be restricted.
In the following example the libkconfig.so shared library is used
to link the executable conf.
Example:
#scripts/kconfig/Makefile
hostprogs-y := conf
conf-objs := conf.o libkconfig.so
libkconfig-objs := expr.o type.o
Shared libraries always require a corresponding -objs line, and
in the example above the shared library libkconfig is composed by
the two objects expr.o and type.o.
expr.o and type.o will be built as position independent code and
linked as a shared library libkconfig.so. C++ is not supported for
shared libraries.
Objects with extension .so are considered shared libraries, and
will be compiled as position independent objects.
Kbuild provides support for shared libraries, but the usage
shall be restricted.
In the following example the libkconfig.so shared library is used
to link the executable conf.
Example:
#scripts/kconfig/Makefile
hostprogs-y := conf
conf-objs := conf.o libkconfig.so
libkconfig-objs := expr.o type.o
Shared libraries always require a corresponding -objs line, and
in the example above the shared library libkconfig is composed by
the two objects expr.o and type.o.
expr.o and type.o will be built as position independent code and
linked as a shared library libkconfig.so. C++ is not supported for
shared libraries.
--- 4.4 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
for general use.
Example:
#scripts/kconfig/Makefile
hostprogs-y := qconf
qconf-cxxobjs := qconf.o
In the example above the executable is composed of the C++ file
qconf.cc - identified by $(qconf-cxxobjs).
If qconf is composed by a mixture of .c and .cc files, then an
additional line can be used to identify this.
Example:
#scripts/kconfig/Makefile
hostprogs-y := qconf
qconf-cxxobjs := qconf.o
qconf-objs := check.o
kbuild offers support for host programs written in C++. This was
introduced solely to support kconfig, and is not recommended
for general use.
Example:
#scripts/kconfig/Makefile
hostprogs-y := qconf
qconf-cxxobjs := qconf.o
In the example above the executable is composed of the C++ file
qconf.cc - identified by $(qconf-cxxobjs).
If qconf is composed by a mixture of .c and .cc files, then an
additional line can be used to identify this.
Example:
#scripts/kconfig/Makefile
hostprogs-y := qconf
qconf-cxxobjs := qconf.o
qconf-objs := check.o
--- 4.5 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 $(HOSTCC)和$(HOSTCFLAGS)全局有效
the options specified in $(HOSTCFLAGS).
To set flags that will take effect for all host programs created HOST_EXTRACFLAGS对当前Makefile生成的host programs 均
in that Makefile, use the variable HOST_EXTRACFLAGS. 有效。
Example:
#scripts/lxdialog/Makefile
HOST_EXTRACFLAGS += -I/usr/include/ncurses
To set specific flags for a single file the following construction 针对某个目标的编译选项指定的方法：
is used:
Example:
#arch/ppc64/boot/Makefile
HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
It is also possible to specify additional options to the linker.
Example:
#scripts/kconfig/Makefile
HOSTLOADLIBES_qconf := -L$(QTDIR)/lib
When linking qconf, it will be passed the extra option
"-L$(QTDIR)/lib".
When compiling host programs, it is possible to set specific flags.
The programs will always be compiled utilising $(HOSTCC) passed $(HOSTCC)和$(HOSTCFLAGS)全局有效
the options specified in $(HOSTCFLAGS).
To set flags that will take effect for all host programs created HOST_EXTRACFLAGS对当前Makefile生成的host programs 均
in that Makefile, use the variable HOST_EXTRACFLAGS. 有效。
Example:
#scripts/lxdialog/Makefile
HOST_EXTRACFLAGS += -I/usr/include/ncurses
To set specific flags for a single file the following construction 针对某个目标的编译选项指定的方法：
is used:
Example:
#arch/ppc64/boot/Makefile
HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
It is also possible to specify additional options to the linker.
Example:
#scripts/kconfig/Makefile
HOSTLOADLIBES_qconf := -L$(QTDIR)/lib
When linking qconf, it will be passed the extra option
"-L$(QTDIR)/lib".
--- 4.6 When host programs are actually built
Kbuild will only build host-programs when they are referenced
as a prerequisite.
This is possible in two ways:
(1) List the prerequisite explicitly in a special rule.
Example:
#drivers/pci/Makefile
hostprogs-y := gen-devlist
$(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
( cd $(obj); ./gen-devlist ) < $<
The target $(obj)/devlist.h will not be built before
$(obj)/gen-devlist is updated. Note that references to
the host programs in special rules must be prefixed with $(obj).
(2) Use $(always)
When there is no suitable special rule, and the host program
shall be built when a makefile is entered, the $(always)
variable shall be used.
Example:
#scripts/lxdialog/Makefile
hostprogs-y := lxdialog
always := $(hostprogs-y)
This will tell kbuild to build lxdialog even if not referenced in
any rule.
Kbuild will only build host-programs when they are referenced
as a prerequisite.
This is possible in two ways:
(1) List the prerequisite explicitly in a special rule.
Example:
#drivers/pci/Makefile
hostprogs-y := gen-devlist
$(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
( cd $(obj); ./gen-devlist ) < $<
The target $(obj)/devlist.h will not be built before
$(obj)/gen-devlist is updated. Note that references to
the host programs in special rules must be prefixed with $(obj).
(2) Use $(always)
When there is no suitable special rule, and the host program
shall be built when a makefile is entered, the $(always)
variable shall be used.
Example:
#scripts/lxdialog/Makefile
hostprogs-y := lxdialog
always := $(hostprogs-y)
This will tell kbuild to build lxdialog even if not referenced in
any rule.
--- 4.7 Using hostprogs-$(CONFIG_FOO)
A typical pattern in a Kbuild file looks like this:
Example:
#scripts/Makefile
hostprogs-$(CONFIG_KALLSYMS) += kallsyms
Kbuild knows about both 'y' for built-in and 'm' for module.
So if a config symbol evaluate to 'm', kbuild will still build
the binary. In other words, Kbuild handles hostprogs-m exactly
like hostprogs-y. But only hostprogs-y is recommended to be used
when no CONFIG symbols are involved.
A typical pattern in a Kbuild file looks like this:
Example:
#scripts/Makefile
hostprogs-$(CONFIG_KALLSYMS) += kallsyms
Kbuild knows about both 'y' for built-in and 'm' for module.
So if a config symbol evaluate to 'm', kbuild will still build
the binary. In other words, Kbuild handles hostprogs-m exactly
like hostprogs-y. But only hostprogs-y is recommended to be used
when no CONFIG symbols are involved.
=== 5 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.
Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
$(extra-y) and $(targets). They are all deleted during "make clean".
Files matching the patterns "*.[oas]", "*.ko", plus some additional files
generated by kbuild are deleted all over the kernel src tree when
"make clean" is executed.
Additional files can be specified in kbuild makefiles by use of $(clean-files). $(clean-files) 可指定要删除的文件
Example:
#drivers/pci/Makefile
clean-files := devlist.h classlist.h
When executing "make clean", the two files "devlist.h classlist.h" will
be deleted. Kbuild will assume files to be in same relative directory as the
Makefile except if an absolute path is specified (path starting with '/').
To delete a directory hierarchy use:
Example:
#scripts/package/Makefile
clean-dirs := $(objtree)/debian/
This will delete the directory debian, including all subdirectories.
Kbuild will assume the directories to be in the same relative path as the
Makefile if no absolute path is specified (path does not start with '/').
To exclude certain files from make clean, use the $(no-clean-files) variable.
This is only a special case used in the top level Kbuild file:
Example:
#Kbuild
no-clean-files := $(bounds-file) $(offsets-file)
Usually kbuild descends down in subdirectories due to "obj-* := dir/",
but in the architecture makefiles where the kbuild infrastructure
is not sufficient this sometimes needs to be explicit.
Example:
#arch/x86/boot/Makefile
subdir- := compressed/
The above assignment instructs kbuild to descend down in the
directory compressed/ when "make clean" is executed.
To support the clean infrastructure in the Makefiles that builds the
final bootimage there is an optional target named archclean:
Example:
#arch/x86/Makefile
archclean:
$(Q)$(MAKE) $(clean)=arch/x86/boot
When "make clean" is executed, make will descend down in arch/x86/boot,
and clean as usual. The Makefile located in arch/x86/boot/ may use
the subdir- trick to descend further down.
Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is
included in the top level makefile, and the kbuild infrastructure
is not operational at that point.
Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
be visited during "make clean".
"make clean" deletes most generated files in the obj tree where the kernel
is compiled. This includes generated files such as host programs.
Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
$(extra-y) and $(targets). They are all deleted during "make clean".
Files matching the patterns "*.[oas]", "*.ko", plus some additional files
generated by kbuild are deleted all over the kernel src tree when
"make clean" is executed.
Additional files can be specified in kbuild makefiles by use of $(clean-files). $(clean-files) 可指定要删除的文件
Example:
#drivers/pci/Makefile
clean-files := devlist.h classlist.h
When executing "make clean", the two files "devlist.h classlist.h" will
be deleted. Kbuild will assume files to be in same relative directory as the
Makefile except if an absolute path is specified (path starting with '/').
To delete a directory hierarchy use:
Example:
#scripts/package/Makefile
clean-dirs := $(objtree)/debian/
This will delete the directory debian, including all subdirectories.
Kbuild will assume the directories to be in the same relative path as the
Makefile if no absolute path is specified (path does not start with '/').
To exclude certain files from make clean, use the $(no-clean-files) variable.
This is only a special case used in the top level Kbuild file:
Example:
#Kbuild
no-clean-files := $(bounds-file) $(offsets-file)
Usually kbuild descends down in subdirectories due to "obj-* := dir/",
but in the architecture makefiles where the kbuild infrastructure
is not sufficient this sometimes needs to be explicit.
Example:
#arch/x86/boot/Makefile
subdir- := compressed/
The above assignment instructs kbuild to descend down in the
directory compressed/ when "make clean" is executed.
To support the clean infrastructure in the Makefiles that builds the
final bootimage there is an optional target named archclean:
Example:
#arch/x86/Makefile
archclean:
$(Q)$(MAKE) $(clean)=arch/x86/boot
When "make clean" is executed, make will descend down in arch/x86/boot,
and clean as usual. The Makefile located in arch/x86/boot/ may use
the subdir- trick to descend further down.
Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is
included in the top level makefile, and the kbuild infrastructure
is not operational at that point.
Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
be visited during "make clean".
=== 6 Architecture Makefiles
The top level Makefile sets up the environment and does the preparation,
before starting to descend down in the individual directories.
The top level makefile contains the generic part, whereas
arch/$(ARCH)/Makefile contains what is required to set up kbuild
for said architecture.
To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
a few targets.
When kbuild executes, the following steps are followed (roughly):
1) Configuration of the kernel => produce .config 配置内核==〉生成 .config
2) Store kernel version in include/linux/version.h 写入内核版本信息到include/linux/version.h
3) Symlink include/asm to include/asm-$(ARCH) 将include/asm符号链接为include/asm-$(ARCH)
The top level Makefile sets up the environment and does the preparation,
before starting to descend down in the individual directories.
The top level makefile contains the generic part, whereas
arch/$(ARCH)/Makefile contains what is required to set up kbuild
for said architecture.
To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
a few targets.
When kbuild executes, the following steps are followed (roughly):
1) Configuration of the kernel => produce .config 配置内核==〉生成 .config
2) Store kernel version in include/linux/version.h 写入内核版本信息到include/linux/version.h
3) Symlink include/asm to include/asm-$(ARCH) 将include/asm符号链接为include/asm-$(ARCH)
4) Updating all other prerequisites to the target prepare: 更新所有目标依赖，附加依赖在
- Additional prerequisites are specified in arch/$(ARCH)/Makefile arch/$(ARCH)/Makefile中指定
5) Recursively descend down in all directories listed in 递归进入init-* core* drivers-* net-* libs-*中的
init-* core* drivers-* net-* libs-* and build all targets. 所有子目录并编译所有的目标对象
- The values of the above variables are expanded in arch/$(ARCH)/Makefile. 可在arch/$(ARCH)/Makefile扩展以上变量的值
6) All object files are then linked and the resulting file vmlinux is 链接所有的object文件生成vmlinux文件,
located at the root of the obj tree. 在代码树根目录下。
The very first objects linked are listed in head-y, assigned by 最先链接的几个object文件是在
arch/$(ARCH)/Makefile. arch/$(ARCH)/Makefile文件的head-y变量中指定
7) Finally, the architecture-specific part does any required post processing 指定体系架构部分完成任何需要的后期处理，
and builds the final bootimage. 生成bootimage
- This includes building boot records 包含生成boot引导记录
- Preparing initrd images and the like 准备initrd镜像等类似的事情
- Additional prerequisites are specified in arch/$(ARCH)/Makefile arch/$(ARCH)/Makefile中指定
5) Recursively descend down in all directories listed in 递归进入init-* core* drivers-* net-* libs-*中的
init-* core* drivers-* net-* libs-* and build all targets. 所有子目录并编译所有的目标对象
- The values of the above variables are expanded in arch/$(ARCH)/Makefile. 可在arch/$(ARCH)/Makefile扩展以上变量的值
6) All object files are then linked and the resulting file vmlinux is 链接所有的object文件生成vmlinux文件,
located at the root of the obj tree. 在代码树根目录下。
The very first objects linked are listed in head-y, assigned by 最先链接的几个object文件是在
arch/$(ARCH)/Makefile. arch/$(ARCH)/Makefile文件的head-y变量中指定
7) Finally, the architecture-specific part does any required post processing 指定体系架构部分完成任何需要的后期处理，
and builds the final bootimage. 生成bootimage
- This includes building boot records 包含生成boot引导记录
- Preparing initrd images and the like 准备initrd镜像等类似的事情
--- 6.1 Set variables to tweak the build to the architecture
LDFLAGS Generic $(LD) options
Flags used for all invocations of the linker.
Often specifying the emulation is sufficient.
Example:
#arch/s390/Makefile
LDFLAGS := -m elf_s390
Note: ldflags-y can be used to further customise
the flags used. See chapter 3.7.
LDFLAGS_MODULE Options for $(LD) when linking modules
LDFLAGS_MODULE is used to set specific flags for $(LD) when
linking the .ko files used for modules.
Default is "-r", for relocatable output.
LDFLAGS_vmlinux Options for $(LD) when linking vmlinux
LDFLAGS_vmlinux is used to specify additional flags to pass to
the linker when linking the final vmlinux image.
LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
Example:
#arch/x86/Makefile
LDFLAGS_vmlinux := -e stext
OBJCOPYFLAGS objcopy flags
When $(call if_changed,objcopy) is used to translate a .o file,
the flags specified in OBJCOPYFLAGS will be used.
$(call if_changed,objcopy) is often used to generate raw binaries on
vmlinux.
Example:
#arch/s390/Makefile
OBJCOPYFLAGS := -O binary
#arch/s390/boot/Makefile
$(obj)/image: vmlinux FORCE
$(call if_changed,objcopy)
In this example, the binary $(obj)/image is a binary version of
vmlinux. The usage of $(call if_changed,xxx) will be described later.
KBUILD_AFLAGS $(AS) assembler flags
Default value - see top level Makefile
Append or modify as required per architecture.
Example:
#arch/sparc64/Makefile
KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
KBUILD_CFLAGS $(CC) compiler flags
Default value - see top level Makefile
Append or modify as required per architecture.
Often, the KBUILD_CFLAGS variable depends on the configuration.
Example:
#arch/x86/Makefile
cflags-$(CONFIG_M386) += -march=i386
KBUILD_CFLAGS += $(cflags-y)
Many arch Makefiles dynamically run the target C compiler to
probe supported options:
#arch/x86/Makefile
...
cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,
-march=pentium2,-march=i686)
...
# Disable unit-at-a-time mode ...
KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
...
The first example utilises the trick that a config option expands
to 'y' when selected.
KBUILD_AFLAGS_KERNEL $(AS) options specific for built-in
$(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
resident kernel code.
KBUILD_AFLAGS_MODULE Options for $(AS) when building modules
$(KBUILD_AFLAGS_MODULE) is used to add arch specific options that
are used for $(AS).
From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
KBUILD_CFLAGS_KERNEL $(CC) options specific for built-in
$(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
resident kernel code.
KBUILD_CFLAGS_MODULE Options for $(CC) when building modules
$(KBUILD_CFLAGS_MODULE) is used to add arch specific options that
are used for $(CC).
From commandline CFLAGS_MODULE shall be used (see kbuild.txt).
KBUILD_LDFLAGS_MODULE Options for $(LD) when linking modules
$(KBUILD_LDFLAGS_MODULE) is used to add arch specific options
used when linking modules. This is often a linker script.
From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).
KBUILD_ARFLAGS Options for $(AR) when creating archives
$(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic
mode) if this option is supported by $(AR).
LDFLAGS Generic $(LD) options
Flags used for all invocations of the linker.
Often specifying the emulation is sufficient.
Example:
#arch/s390/Makefile
LDFLAGS := -m elf_s390
Note: ldflags-y can be used to further customise
the flags used. See chapter 3.7.
LDFLAGS_MODULE Options for $(LD) when linking modules
LDFLAGS_MODULE is used to set specific flags for $(LD) when
linking the .ko files used for modules.
Default is "-r", for relocatable output.
LDFLAGS_vmlinux Options for $(LD) when linking vmlinux
LDFLAGS_vmlinux is used to specify additional flags to pass to
the linker when linking the final vmlinux image.
LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
Example:
#arch/x86/Makefile
LDFLAGS_vmlinux := -e stext
OBJCOPYFLAGS objcopy flags
When $(call if_changed,objcopy) is used to translate a .o file,
the flags specified in OBJCOPYFLAGS will be used.
$(call if_changed,objcopy) is often used to generate raw binaries on
vmlinux.
Example:
#arch/s390/Makefile
OBJCOPYFLAGS := -O binary
#arch/s390/boot/Makefile
$(obj)/image: vmlinux FORCE
$(call if_changed,objcopy)
In this example, the binary $(obj)/image is a binary version of
vmlinux. The usage of $(call if_changed,xxx) will be described later.
KBUILD_AFLAGS $(AS) assembler flags
Default value - see top level Makefile
Append or modify as required per architecture.
Example:
#arch/sparc64/Makefile
KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
KBUILD_CFLAGS $(CC) compiler flags
Default value - see top level Makefile
Append or modify as required per architecture.
Often, the KBUILD_CFLAGS variable depends on the configuration.
Example:
#arch/x86/Makefile
cflags-$(CONFIG_M386) += -march=i386
KBUILD_CFLAGS += $(cflags-y)
Many arch Makefiles dynamically run the target C compiler to
probe supported options:
#arch/x86/Makefile
...
cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,
-march=pentium2,-march=i686)
...
# Disable unit-at-a-time mode ...
KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
...
The first example utilises the trick that a config option expands
to 'y' when selected.
KBUILD_AFLAGS_KERNEL $(AS) options specific for built-in
$(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
resident kernel code.
KBUILD_AFLAGS_MODULE Options for $(AS) when building modules
$(KBUILD_AFLAGS_MODULE) is used to add arch specific options that
are used for $(AS).
From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
KBUILD_CFLAGS_KERNEL $(CC) options specific for built-in
$(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
resident kernel code.
KBUILD_CFLAGS_MODULE Options for $(CC) when building modules
$(KBUILD_CFLAGS_MODULE) is used to add arch specific options that
are used for $(CC).
From commandline CFLAGS_MODULE shall be used (see kbuild.txt).
KBUILD_LDFLAGS_MODULE Options for $(LD) when linking modules
$(KBUILD_LDFLAGS_MODULE) is used to add arch specific options
used when linking modules. This is often a linker script.
From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).
KBUILD_ARFLAGS Options for $(AR) when creating archives
$(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic
mode) if this option is supported by $(AR).
--- 6.2 Add prerequisites to archheaders: 为目标archheaders: 增加依赖
The archheaders: rule is used to generate header files that archheaders: 规则用于生成头文件，这些头文件可能会通过
may be installed into user space by "make header_install" or "make header_install" or "make headers_install_all" 安装到
"make headers_install_all". In order to support 用户空间。为了支持"make headers_install_all" ，该目标必须
"make headers_install_all", this target has to be able to run 能运行在一个未配置的树或是其他架构的树上。
on an unconfigured tree, or a tree configured for another
architecture.
It is run before "make archprepare" when run on the 该目标在"make archprepare" 之前运行。
architecture itself.
The archheaders: rule is used to generate header files that archheaders: 规则用于生成头文件，这些头文件可能会通过
may be installed into user space by "make header_install" or "make header_install" or "make headers_install_all" 安装到
"make headers_install_all". In order to support 用户空间。为了支持"make headers_install_all" ，该目标必须
"make headers_install_all", this target has to be able to run 能运行在一个未配置的树或是其他架构的树上。
on an unconfigured tree, or a tree configured for another
architecture.
It is run before "make archprepare" when run on the 该目标在"make archprepare" 之前运行。
architecture itself.
--- 6.3 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.
This is usually used for header files containing assembler constants. 该规则通常用于包含汇编常量的头文件。(暂不明白什么意思?)
Example:
#arch/arm/Makefile
archprepare: maketools
In this example, the file target maketools will be processed 在递归子目录前先处理maketools
before descending down in the subdirectories.
See also chapter XXX-TODO that describe how kbuild supports
generating offset header files.
--- 6.4 List directories to visit when descending
An arch Makefile cooperates with the top Makefile to define variables arch Makefile 配合顶层Makefile定义一些用于编译vmlinux的变量。
which specify how to build the vmlinux file. Note that there is no
corresponding arch-specific section for modules; the module-building 内核模块编译都是与架构无关的。
machinery is all architecture-independent.
head-y, init-y, core-y, libs-y, drivers-y, net-y
$(head-y) lists objects to be linked first in vmlinux. $(head-y) 列出最先被编译进vmlinux的对象
$(libs-y) lists directories where a lib.a archive can be located. $(libs-y)列出包含lib.a的目录
The rest list directories where a built-in.o object file can be 其他部分列出built-in.o
located.
$(init-y) objects will be located after $(head-y). $(head-y)--->$(init-y) --->$(core-y), $(libs-y), $(drivers-y) and $(net-y)
Then the rest follows in this order:
$(core-y), $(libs-y), $(drivers-y) and $(net-y).
The top level Makefile defines values for all generic directories,
and arch/$(ARCH)/Makefile only adds architecture-specific directories.
Example:
#arch/sparc64/Makefile
core-y += arch/sparc64/kernel/
libs-y += arch/sparc64/prom/ arch/sparc64/lib/
drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
--- 6.5 Architecture-specific boot images
An arch Makefile specifies goals that take the vmlinux file, compress arch Makefile 的作用是生成并压缩vmlinux,然后打包进引导启动代码，最后复制到合适的位置。
it, wrap it in bootstrapping code, and copy the resulting files
somewhere. This includes various kinds of installation commands. 该目标的完成需要各种安装命令。
The actual goals are not standardized across architectures. 实际的目标对象不能在各体系架构间形成标准化。
It is common to locate any additional processing in a boot/ 一般在arch/$(ARCH）/boot目录下进行额外的处理。
directory below arch/$(ARCH)/.
Kbuild does not provide any smart way to support building a Kbuild并没有为构建boot/下的目标提供自动化的方法。
target specified in boot/. Therefore arch/$(ARCH)/Makefile shall 因此需要手动执行arch/$(ARCH)/Makefile来构建boot/下的目标
call make manually to build a target in boot/.
The recommended approach is to include shortcuts in 推荐的方式是在arch/$(ARCH)/Makefile中添加快捷方式，
arch/$(ARCH)/Makefile, and use the full path when calling down 然后在arch/$(ARCH)/boot/Makefile中使用绝对路径。
into the arch/$(ARCH)/boot/Makefile.
Example:
#arch/x86/Makefile
boot := arch/x86/boot
bzImage: vmlinux
$(Q)$(MAKE) $(build)=$(boot) $(boot)/$@
"$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
make in a subdirectory.
There are no rules for naming architecture-specific targets,
but executing "make help" will list all relevant targets.
To support this, $(archhelp) must be defined.
Example:
#arch/x86/Makefile
define archhelp
echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)'
endif
When make is executed without arguments, the first goal encountered 当执行不带参数的make时，在脚本中最先遇到的目标将会被编译。
will be built. In the top level Makefile the first goal present 顶层Makefile的第一个目标是all:
is all:.
An architecture shall always, per default, build a bootable image. 默认每个架构下都要构建一个可引导镜像。
In "make help", the default goal is highlighted with a '*'. 在"make help"中，默认目标用"*"高亮
Add a new prerequisite to all: to select a default goal different 给目标all:添加一个新的依赖来构建一个不同于vmlinux的默认目标。
from vmlinux.
Example:
#arch/x86/Makefile
all: bzImage
When "make" is executed without arguments, bzImage will be built.
--- 6.6 Building non-kbuild targets
extra-y
extra-y specify additional targets created in the current extra-y指定了在当前目录下，生成除了obj-*指定的目标之外的其他目标。
directory, in addition to any targets specified by obj-*.
Listing all targets in extra-y is required for two purposes: extra-y列举的目标有两个目的：
1) Enable kbuild to check changes in command lines 1.使Kbuild可以检查命令行是否变化
- When $(call if_changed,xxx) is used
2) kbuild knows what files to delete during "make clean" 2.在make clean时，使Kbuild知道要删除哪些文件。
Example:
#arch/x86/kernel/Makefile
extra-y := head.o init_task.o
In this example, extra-y is used to list object files that 上例中，extra-y用于列出应被编译但不能链接进built-in.o的对象
shall be built, but shall not be linked as part of built-in.o.
--- 6.7 Commands useful for building a boot image
Kbuild provides a few macros that are useful when building a Kbuild 提供一些有用的宏来编译boot image
boot image.
if_changed
if_changed is the infrastructure used for the following commands.
Usage:
target: source(s) FORCE
$(call if_changed,ld/objcopy/gzip)
When the rule is evaluated, it is checked to see if any files
need an update, or the command line has changed since the last
invocation. The latter will force a rebuild if any options
to the executable have changed.
Any target that utilises if_changed must be listed in $(targets),
otherwise the command line check will fail, and the target will
always be built.
Assignments to $(targets) are without $(obj)/ prefix.
if_changed may be used in conjunction with custom commands as
defined in 6.8 "Custom kbuild commands".
Note: It is a typical mistake to forget the FORCE prerequisite.
Another common pitfall is that whitespace is sometimes
significant; for instance, the below will fail (note the extra space
after the comma):
target: source(s) FORCE
#WRONG!# $(call if_changed, ld/objcopy/gzip)
ld
Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
objcopy
Copy binary. Uses OBJCOPYFLAGS usually specified in
arch/$(ARCH)/Makefile.
OBJCOPYFLAGS_$@ may be used to set additional options.
gzip
Compress target. Use maximum compression to compress target.
Example:
#arch/x86/boot/Makefile
LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext
targets += setup setup.o bootsect bootsect.o
$(obj)/setup $(obj)/bootsect: %: %.o FORCE
$(call if_changed,ld)
In this example, there are two possible targets, requiring different
options to the linker. The linker options are specified using the
LDFLAGS_$@ syntax - one for each potential target.
$(targets) are assigned all potential targets, by which kbuild knows
the targets and will:
1) check for commandline changes
2) delete target during make clean
The ": %: %.o" part of the prerequisite is a shorthand that
free us from listing the setup.o and bootsect.o files.
Note: It is a common mistake to forget the "target :=" assignment,
resulting in the target file being recompiled for no
obvious reason.
dtc
Create flattened device tree blob object suitable for linking
into vmlinux. Device tree blobs linked into vmlinux are placed
in an init section in the image. Platform code *must* copy the
blob to non-init memory prior to calling unflatten_device_tree().
Example:
#arch/x86/platform/ce4100/Makefile
clean-files := *dtb.S
DTC_FLAGS := -p 1024
obj-y += foo.dtb.o
$(obj)/%.dtb: $(src)/%.dts
$(call cmd,dtc)
--- 6.8 Custom kbuild commands
When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
of a command is normally displayed.
To enable this behaviour for custom commands kbuild requires
two variables to be set:
quiet_cmd_<command> - what shall be echoed
cmd_<command> - the command to execute
Example:
#
quiet_cmd_image = BUILD $@
cmd_image = $(obj)/tools/build $(BUILDFLAGS)
$(obj)/vmlinux.bin > $@
targets += bzImage
$(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
$(call if_changed,image)
@echo 'Kernel: $@ is ready'
When updating the $(obj)/bzImage target, the line
BUILD arch/x86/boot/bzImage
will be displayed with "make KBUILD_VERBOSE=0".
--- 6.9 Preprocessing linker scripts
When the vmlinux image is built, the linker script
arch/$(ARCH)/kernel/vmlinux.lds is used.
The script is a preprocessed variant of the file vmlinux.lds.S
located in the same directory.
kbuild knows .lds files and includes a rule *lds.S -> *lds.
Example:
#arch/x86/kernel/Makefile
always := vmlinux.lds
#Makefile
export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
The assignment to $(always) is used to tell kbuild to build the
target vmlinux.lds.
The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
specified options when building the target vmlinux.lds.
When building the *.lds target, kbuild uses the variables:
KBUILD_CPPFLAGS : Set in top-level Makefile
cppflags-y : May be set in the kbuild makefile
CPPFLAGS_$(@F) : Target specific flags.
Note that the full filename is used in this
assignment.
The kbuild infrastructure for *lds file are used in several
architecture-specific files.
--- 6.10 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 "7.4 generic-y" for further info on syntax etc.
The archprepare: rule is used to list prerequisites that need to be 这个规则用于列举开始进入子目录前编译时需要的依赖文件。
built before starting to descend down in the subdirectories.
This is usually used for header files containing assembler constants. 该规则通常用于包含汇编常量的头文件。(暂不明白什么意思?)
Example:
#arch/arm/Makefile
archprepare: maketools
In this example, the file target maketools will be processed 在递归子目录前先处理maketools
before descending down in the subdirectories.
See also chapter XXX-TODO that describe how kbuild supports
generating offset header files.
--- 6.4 List directories to visit when descending
An arch Makefile cooperates with the top Makefile to define variables arch Makefile 配合顶层Makefile定义一些用于编译vmlinux的变量。
which specify how to build the vmlinux file. Note that there is no
corresponding arch-specific section for modules; the module-building 内核模块编译都是与架构无关的。
machinery is all architecture-independent.
head-y, init-y, core-y, libs-y, drivers-y, net-y
$(head-y) lists objects to be linked first in vmlinux. $(head-y) 列出最先被编译进vmlinux的对象
$(libs-y) lists directories where a lib.a archive can be located. $(libs-y)列出包含lib.a的目录
The rest list directories where a built-in.o object file can be 其他部分列出built-in.o
located.
$(init-y) objects will be located after $(head-y). $(head-y)--->$(init-y) --->$(core-y), $(libs-y), $(drivers-y) and $(net-y)
Then the rest follows in this order:
$(core-y), $(libs-y), $(drivers-y) and $(net-y).
The top level Makefile defines values for all generic directories,
and arch/$(ARCH)/Makefile only adds architecture-specific directories.
Example:
#arch/sparc64/Makefile
core-y += arch/sparc64/kernel/
libs-y += arch/sparc64/prom/ arch/sparc64/lib/
drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
--- 6.5 Architecture-specific boot images
An arch Makefile specifies goals that take the vmlinux file, compress arch Makefile 的作用是生成并压缩vmlinux,然后打包进引导启动代码，最后复制到合适的位置。
it, wrap it in bootstrapping code, and copy the resulting files
somewhere. This includes various kinds of installation commands. 该目标的完成需要各种安装命令。
The actual goals are not standardized across architectures. 实际的目标对象不能在各体系架构间形成标准化。
It is common to locate any additional processing in a boot/ 一般在arch/$(ARCH）/boot目录下进行额外的处理。
directory below arch/$(ARCH)/.
Kbuild does not provide any smart way to support building a Kbuild并没有为构建boot/下的目标提供自动化的方法。
target specified in boot/. Therefore arch/$(ARCH)/Makefile shall 因此需要手动执行arch/$(ARCH)/Makefile来构建boot/下的目标
call make manually to build a target in boot/.
The recommended approach is to include shortcuts in 推荐的方式是在arch/$(ARCH)/Makefile中添加快捷方式，
arch/$(ARCH)/Makefile, and use the full path when calling down 然后在arch/$(ARCH)/boot/Makefile中使用绝对路径。
into the arch/$(ARCH)/boot/Makefile.
Example:
#arch/x86/Makefile
boot := arch/x86/boot
bzImage: vmlinux
$(Q)$(MAKE) $(build)=$(boot) $(boot)/$@
"$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
make in a subdirectory.
There are no rules for naming architecture-specific targets,
but executing "make help" will list all relevant targets.
To support this, $(archhelp) must be defined.
Example:
#arch/x86/Makefile
define archhelp
echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)'
endif
When make is executed without arguments, the first goal encountered 当执行不带参数的make时，在脚本中最先遇到的目标将会被编译。
will be built. In the top level Makefile the first goal present 顶层Makefile的第一个目标是all:
is all:.
An architecture shall always, per default, build a bootable image. 默认每个架构下都要构建一个可引导镜像。
In "make help", the default goal is highlighted with a '*'. 在"make help"中，默认目标用"*"高亮
Add a new prerequisite to all: to select a default goal different 给目标all:添加一个新的依赖来构建一个不同于vmlinux的默认目标。
from vmlinux.
Example:
#arch/x86/Makefile
all: bzImage
When "make" is executed without arguments, bzImage will be built.
--- 6.6 Building non-kbuild targets
extra-y
extra-y specify additional targets created in the current extra-y指定了在当前目录下，生成除了obj-*指定的目标之外的其他目标。
directory, in addition to any targets specified by obj-*.
Listing all targets in extra-y is required for two purposes: extra-y列举的目标有两个目的：
1) Enable kbuild to check changes in command lines 1.使Kbuild可以检查命令行是否变化
- When $(call if_changed,xxx) is used
2) kbuild knows what files to delete during "make clean" 2.在make clean时，使Kbuild知道要删除哪些文件。
Example:
#arch/x86/kernel/Makefile
extra-y := head.o init_task.o
In this example, extra-y is used to list object files that 上例中，extra-y用于列出应被编译但不能链接进built-in.o的对象
shall be built, but shall not be linked as part of built-in.o.
--- 6.7 Commands useful for building a boot image
Kbuild provides a few macros that are useful when building a Kbuild 提供一些有用的宏来编译boot image
boot image.
if_changed
if_changed is the infrastructure used for the following commands.
Usage:
target: source(s) FORCE
$(call if_changed,ld/objcopy/gzip)
When the rule is evaluated, it is checked to see if any files
need an update, or the command line has changed since the last
invocation. The latter will force a rebuild if any options
to the executable have changed.
Any target that utilises if_changed must be listed in $(targets),
otherwise the command line check will fail, and the target will
always be built.
Assignments to $(targets) are without $(obj)/ prefix.
if_changed may be used in conjunction with custom commands as
defined in 6.8 "Custom kbuild commands".
Note: It is a typical mistake to forget the FORCE prerequisite.
Another common pitfall is that whitespace is sometimes
significant; for instance, the below will fail (note the extra space
after the comma):
target: source(s) FORCE
#WRONG!# $(call if_changed, ld/objcopy/gzip)
ld
Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
objcopy
Copy binary. Uses OBJCOPYFLAGS usually specified in
arch/$(ARCH)/Makefile.
OBJCOPYFLAGS_$@ may be used to set additional options.
gzip
Compress target. Use maximum compression to compress target.
Example:
#arch/x86/boot/Makefile
LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext
targets += setup setup.o bootsect bootsect.o
$(obj)/setup $(obj)/bootsect: %: %.o FORCE
$(call if_changed,ld)
In this example, there are two possible targets, requiring different
options to the linker. The linker options are specified using the
LDFLAGS_$@ syntax - one for each potential target.
$(targets) are assigned all potential targets, by which kbuild knows
the targets and will:
1) check for commandline changes
2) delete target during make clean
The ": %: %.o" part of the prerequisite is a shorthand that
free us from listing the setup.o and bootsect.o files.
Note: It is a common mistake to forget the "target :=" assignment,
resulting in the target file being recompiled for no
obvious reason.
dtc
Create flattened device tree blob object suitable for linking
into vmlinux. Device tree blobs linked into vmlinux are placed
in an init section in the image. Platform code *must* copy the
blob to non-init memory prior to calling unflatten_device_tree().
Example:
#arch/x86/platform/ce4100/Makefile
clean-files := *dtb.S
DTC_FLAGS := -p 1024
obj-y += foo.dtb.o
$(obj)/%.dtb: $(src)/%.dts
$(call cmd,dtc)
--- 6.8 Custom kbuild commands
When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
of a command is normally displayed.
To enable this behaviour for custom commands kbuild requires
two variables to be set:
quiet_cmd_<command> - what shall be echoed
cmd_<command> - the command to execute
Example:
#
quiet_cmd_image = BUILD $@
cmd_image = $(obj)/tools/build $(BUILDFLAGS)
$(obj)/vmlinux.bin > $@
targets += bzImage
$(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
$(call if_changed,image)
@echo 'Kernel: $@ is ready'
When updating the $(obj)/bzImage target, the line
BUILD arch/x86/boot/bzImage
will be displayed with "make KBUILD_VERBOSE=0".
--- 6.9 Preprocessing linker scripts
When the vmlinux image is built, the linker script
arch/$(ARCH)/kernel/vmlinux.lds is used.
The script is a preprocessed variant of the file vmlinux.lds.S
located in the same directory.
kbuild knows .lds files and includes a rule *lds.S -> *lds.
Example:
#arch/x86/kernel/Makefile
always := vmlinux.lds
#Makefile
export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
The assignment to $(always) is used to tell kbuild to build the
target vmlinux.lds.
The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
specified options when building the target vmlinux.lds.
When building the *.lds target, kbuild uses the variables:
KBUILD_CPPFLAGS : Set in top-level Makefile
cppflags-y : May be set in the kbuild makefile
CPPFLAGS_$(@F) : Target specific flags.
Note that the full filename is used in this
assignment.
The kbuild infrastructure for *lds file are used in several
architecture-specific files.
--- 6.10 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 "7.4 generic-y" for further info on syntax etc.
=== 7 Kbuild syntax for exported headers
The kernel include a set of headers that is exported to userspace. 内核包含一组可以导出到用户空间的头文件.
Many headers can be exported as-is but other headers require a 许多头文件可以原样导出
minimal pre-processing before they are ready for user-space. 但是有一部分头文件在用户空间读取之前,需要做一些简单的预处理.
The pre-processing does:
- drop kernel specific annotations 去掉内核特定的注释
- drop include of compiler.h 去掉compiler.h头文件的包含
- drop all sections that are kernel internal (guarded by ifdef __KERNEL__) 去掉内核内部段(即，使用ifdef __KERNEL__声明的部分)
Each relevant directory contains a file name "Kbuild" which specifies the 每个相关的目录都包含一个名为”Kbuild”的文件
headers to be exported. ,该文件指定了那些头文件要被导出.
See subsequent chapter for the syntax of the Kbuild file.
The kernel include a set of headers that is exported to userspace. 内核包含一组可以导出到用户空间的头文件.
Many headers can be exported as-is but other headers require a 许多头文件可以原样导出
minimal pre-processing before they are ready for user-space. 但是有一部分头文件在用户空间读取之前,需要做一些简单的预处理.
The pre-processing does:
- drop kernel specific annotations 去掉内核特定的注释
- drop include of compiler.h 去掉compiler.h头文件的包含
- drop all sections that are kernel internal (guarded by ifdef __KERNEL__) 去掉内核内部段(即，使用ifdef __KERNEL__声明的部分)
Each relevant directory contains a file name "Kbuild" which specifies the 每个相关的目录都包含一个名为”Kbuild”的文件
headers to be exported. ,该文件指定了那些头文件要被导出.
See subsequent chapter for the syntax of the Kbuild file.
--- 7.1 header-y
header-y specify header files to be exported.
Example:
#include/linux/Kbuild
header-y += usb/
header-y += aio_abi.h
The convention is to list one file per line and
preferably in alphabetic order.
header-y also specify which subdirectories to visit.
A subdirectory is identified by a trailing '/' which
can be seen in the example above for the usb subdirectory.
Subdirectories are visited before their parent directories.
--- 7.2 objhdr-y
objhdr-y specifies generated files to be exported.
Generated files are special as they need to be looked
up in another directory when doing 'make O=...' builds.
Example:
#include/linux/Kbuild
objhdr-y += version.h
--- 7.3 destination-y
When an architecture have a set of exported headers that needs to be
exported to a different directory destination-y is used.
destination-y specify the destination directory for all exported
headers in the file where it is present.
Example:
#arch/xtensa/platforms/s6105/include/platform/Kbuild
destination-y := include/linux
In the example above all exported headers in the Kbuild file
will be located in the directory "include/linux" when exported.
objhdr-y specifies generated files to be exported.
Generated files are special as they need to be looked
up in another directory when doing 'make O=...' builds.
Example:
#include/linux/Kbuild
objhdr-y += version.h
--- 7.3 destination-y
When an architecture have a set of exported headers that needs to be
exported to a different directory destination-y is used.
destination-y specify the destination directory for all exported
headers in the file where it is present.
Example:
#arch/xtensa/platforms/s6105/include/platform/Kbuild
destination-y := include/linux
In the example above all exported headers in the Kbuild file
will be located in the directory "include/linux" when exported.
--- 7.4 generic-y
If an architecture uses a verbatim copy of a header from
include/asm-generic then this is listed in the file
arch/$(ARCH)/include/asm/Kbuild like this:
Example:
#arch/x86/include/asm/Kbuild
generic-y += termios.h
generic-y += rtc.h
During the prepare phase of the build a wrapper include
file is generated in the directory:
arch/$(ARCH)/include/generated/asm
When a header is exported where the architecture uses
the generic header a similar wrapper is generated as part
of the set of exported headers in the directory:
usr/include/asm
The generated wrapper will in both cases look like the following:
Example: termios.h
#include <asm-generic/termios.h>
If an architecture uses a verbatim copy of a header from
include/asm-generic then this is listed in the file
arch/$(ARCH)/include/asm/Kbuild like this:
Example:
#arch/x86/include/asm/Kbuild
generic-y += termios.h
generic-y += rtc.h
During the prepare phase of the build a wrapper include
file is generated in the directory:
arch/$(ARCH)/include/generated/asm
When a header is exported where the architecture uses
the generic header a similar wrapper is generated as part
of the set of exported headers in the directory:
usr/include/asm
The generated wrapper will in both cases look like the following:
Example: termios.h
#include <asm-generic/termios.h>
=== 8 Kbuild Variables
The top Makefile exports the following variables:
VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
These variables define the current kernel version. A few arch
Makefiles actually use these values directly; they should use
$(KERNELRELEASE) instead.
$(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
three-part version number, such as "2", "4", and "0". These three
values are always numeric.
$(EXTRAVERSION) defines an even tinier sublevel for pre-patches
or additional patches. It is usually some non-numeric string
such as "-pre4", and is often blank.
KERNELRELEASE
$(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
for constructing installation directory names or showing in
version strings. Some arch Makefiles use it for this purpose.
ARCH
This variable defines the target architecture, such as "i386",
"arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
determine which files to compile.
By default, the top Makefile sets $(ARCH) to be the same as the
host system architecture. For a cross build, a user may
override the value of $(ARCH) on the command line:
make ARCH=m68k ...
INSTALL_PATH
This variable defines a place for the arch Makefiles to install
the resident kernel image and System.map file.
Use this for architecture-specific install targets.
INSTALL_MOD_PATH, MODLIB
$(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
installation. This variable is not defined in the Makefile but
may be passed in by the user if desired.
$(MODLIB) specifies the directory for module installation.
The top Makefile defines $(MODLIB) to
$(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may
override this value on the command line if desired.
INSTALL_MOD_STRIP
If this variable is specified, will cause modules to be stripped
after they are installed. If INSTALL_MOD_STRIP is '1', then the
default option --strip-debug will be used. Otherwise,
INSTALL_MOD_STRIP value will be used as the option(s) to the strip
command.
The top Makefile exports the following variables:
VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
These variables define the current kernel version. A few arch
Makefiles actually use these values directly; they should use
$(KERNELRELEASE) instead.
$(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
three-part version number, such as "2", "4", and "0". These three
values are always numeric.
$(EXTRAVERSION) defines an even tinier sublevel for pre-patches
or additional patches. It is usually some non-numeric string
such as "-pre4", and is often blank.
KERNELRELEASE
$(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
for constructing installation directory names or showing in
version strings. Some arch Makefiles use it for this purpose.
ARCH
This variable defines the target architecture, such as "i386",
"arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
determine which files to compile.
By default, the top Makefile sets $(ARCH) to be the same as the
host system architecture. For a cross build, a user may
override the value of $(ARCH) on the command line:
make ARCH=m68k ...
INSTALL_PATH
This variable defines a place for the arch Makefiles to install
the resident kernel image and System.map file.
Use this for architecture-specific install targets.
INSTALL_MOD_PATH, MODLIB
$(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
installation. This variable is not defined in the Makefile but
may be passed in by the user if desired.
$(MODLIB) specifies the directory for module installation.
The top Makefile defines $(MODLIB) to
$(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may
override this value on the command line if desired.
INSTALL_MOD_STRIP
If this variable is specified, will cause modules to be stripped
after they are installed. If INSTALL_MOD_STRIP is '1', then the
default option --strip-debug will be used. Otherwise,
INSTALL_MOD_STRIP value will be used as the option(s) to the strip
command.