--- 3.4 Objects which export symbols
--- 3.5 Library file goals - lib-y
--- 3.6 Descending down in directories
- --- 3.7 Compilation flags
- --- 3.8 <deleted>
- --- 3.9 Dependency tracking
- --- 3.10 Special Rules
- --- 3.11 $(CC) support functions
- --- 3.12 $(LD) support functions
- --- 3.13 Script Invocation
+ --- 3.7 Non-builtin vmlinux targets - extra-y
+ --- 3.8 Always built goals - always-y
+ --- 3.9 Compilation flags
+ --- 3.10 Dependency tracking
+ --- 3.11 Custom Rules
+ --- 3.12 Command change detection
+ --- 3.13 $(CC) support functions
+ --- 3.14 $(LD) support functions
+ --- 3.15 Script Invocation
=== 4 Host Program support
--- 4.1 Simple Host Program
--- 7.5 Architecture-specific boot images
--- 7.6 Building non-kbuild targets
--- 7.7 Commands useful for building a boot image
- --- 7.8 Custom kbuild commands
+ --- 7.8 <deleted>
--- 7.9 Preprocessing linker scripts
--- 7.10 Generic header files
--- 7.11 Post-link pass
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".
+ See also "7.4 List directories to visit when descending".
Use of lib-y is normally restricted to `lib/` and `arch/*/lib`.
that directory specifies obj-y, those objects will be left orphan.
It is very likely a bug of the Makefile or of dependencies in Kconfig.
+ Kbuild also supports dedicated syntax, subdir-y and subdir-m, for
+ descending into subdirectories. It is a good fit when you know they
+ do not contain kernel-space objects at all. A typical usage is to let
+ Kbuild descend into subdirectories to build tools.
+
+ Examples::
+
+ # scripts/Makefile
+ subdir-$(CONFIG_GCC_PLUGINS) += gcc-plugins
+ subdir-$(CONFIG_MODVERSIONS) += genksyms
+ subdir-$(CONFIG_SECURITY_SELINUX) += selinux
+
+ Unlike obj-y/m, subdir-y/m does not need the trailing slash since this
+ syntax is always used for directories.
+
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
+3.7 Non-builtin vmlinux targets - extra-y
+-----------------------------------------
+
+ extra-y specifies targets which are needed for building vmlinux,
+ but not combined into built-in.a.
+
+ Examples are:
+
+ 1) head objects
+
+ Some objects must be placed at the head of vmlinux. They are
+ directly linked to vmlinux without going through built-in.a
+ A typical use-case is an object that contains the entry point.
+
+ arch/$(SRCARCH)/Makefile should specify such objects as head-y.
+
+ Discussion:
+ Given that we can control the section order in the linker script,
+ why do we need head-y?
+
+ 2) vmlinux linker script
+
+ The linker script for vmlinux is located at
+ arch/$(SRCARCH)/kernel/vmlinux.lds
+
+ Example::
+
+ # arch/x86/kernel/Makefile
+ extra-y := head_$(BITS).o
+ extra-y += head$(BITS).o
+ extra-y += ebda.o
+ extra-y += platform-quirks.o
+ extra-y += vmlinux.lds
+
+ $(extra-y) should only contain targets needed for vmlinux.
+
+ Kbuild skips extra-y when vmlinux is apparently not a final goal.
+ (e.g. 'make modules', or building external modules)
+
+ 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-y specifies targets which are literally always built when
+ Kbuild visits the Makefile.
+
+ Example::
+ # ./Kbuild
+ offsets-file := include/generated/asm-offsets.h
+ always-y += $(offsets-file)
+
+3.9 Compilation flags
---------------------
ccflags-y, asflags-y and ldflags-y
AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
-3.9 Dependency tracking
------------------------
+3.10 Dependency tracking
+------------------------
Kbuild tracks dependencies on the following:
Thus, if you change an option to $(CC) all affected files will
be re-compiled.
-3.10 Special Rules
-------------------
+3.11 Custom Rules
+-----------------
- Special rules are used when the kbuild infrastructure does
+ Custom rules are used when the kbuild infrastructure does
not provide the required support. A typical example is
header files generated during the build process.
Another example are the architecture-specific Makefiles which
- need special rules to prepare boot images etc.
+ need custom rules to prepare boot images etc.
- Special rules are written as normal Make rules.
+ Custom rules are written as normal Make rules.
Kbuild is not executing in the directory where the Makefile is
- located, so all special rules shall provide a relative
+ located, so all custom rules shall use a relative
path to prerequisite files and target files.
- Two variables are used when defining special rules:
+ Two variables are used when defining custom rules:
$(src)
$(src) is a relative path which points to the directory
$(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
+ This is a custom rule, following the normal syntax
required by make.
The target file depends on two prerequisite files. References
Example::
- #arch/blackfin/boot/Makefile
- $(obj)/vmImage: $(obj)/vmlinux.gz
- $(call if_changed,uimage)
- @$(kecho) 'Kernel: $@ is ready'
+ # arch/arm/Makefile
+ $(BOOT_TARGETS): vmlinux
+ $(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@
+ @$(kecho) ' Kernel: $(boot)/$@ is ready'
+
+ 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::
+
+ # lib/Makefile
+ quiet_cmd_crc32 = GEN $@
+ cmd_crc32 = $< > $@
+
+ $(obj)/crc32table.h: $(obj)/gen_crc32table
+ $(call cmd,crc32)
+
+ When updating the $(obj)/crc32table.h target, the line:
+
+ GEN lib/crc32table.h
+
+ will be displayed with "make KBUILD_VERBOSE=0".
+
+3.12 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
+ prerequisites is newer than that.
+
+ The target should be rebuilt also when the command line has changed
+ since the last invocation. This is not supported by Make itself, so
+ Kbuild achieves this by a kind of meta-programming.
+
+ if_changed is the macro used for this purpose, in the following form::
+
+ quiet_cmd_<command> = ...
+ cmd_<command> = ...
+
+ <target>: <source(s)> FORCE
+ $(call if_changed,<command>)
+
+ Any target that utilizes if_changed must be listed in $(targets),
+ otherwise the command line check will fail, and the target will
+ always be built.
+
+ If the target is already listed in the recognized syntax such as
+ obj-y/m, lib-y/m, extra-y/m, always-y/m, hostprogs, userprogs, Kbuild
+ automatically adds it to $(targets). Otherwise, the target must be
+ 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.9 Custom Rules".
+ 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, objcopy)
-3.11 $(CC) support functions
+ Note:
+ if_changed should not be used more than once per target.
+ It stores the executed command in a corresponding .cmd
+ file and multiple calls would result in overwrites and
+ 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
----------------------------
The kernel may be built with several different versions of
endif
endif
-3.12 $(LD) support functions
+3.14 $(LD) support functions
----------------------------
ld-option
#Makefile
LDFLAGS_vmlinux += $(call ld-option, -X)
-3.13 Script invocation
+3.15 Script invocation
----------------------
Make rules may invoke scripts to build the kernel. The rules shall
as a prerequisite.
This is possible in two ways:
- (1) List the prerequisite explicitly in a special rule.
+ (1) List the prerequisite explicitly in a custom rule.
Example::
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).
+ the host programs in custom rules must be prefixed with $(obj).
(2) Use always-y
- When there is no suitable special rule, and the host program
+ When there is no suitable custom rule, and the host program
shall be built when a makefile is entered, the always-y
variable shall be used.
machinery is all architecture-independent.
- head-y, init-y, core-y, libs-y, drivers-y, net-y
+ head-y, core-y, libs-y, drivers-y
$(head-y) lists objects to be linked first in vmlinux.
$(libs-y) lists directories where a lib.a archive can be located.
The rest list directories where a built-in.a object file can be
located.
- $(init-y) objects will be located after $(head-y).
-
Then the rest follows in this order:
- $(core-y), $(libs-y), $(drivers-y) and $(net-y).
+ $(core-y), $(libs-y), $(drivers-y)
The top level Makefile defines values for all generic directories,
and arch/$(SRCARCH)/Makefile only adds architecture-specific
Example::
- #arch/sparc64/Makefile
- core-y += arch/sparc64/kernel/
- libs-y += arch/sparc64/prom/ arch/sparc64/lib/
- drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
+ # arch/sparc/Makefile
+ core-y += arch/sparc/
+
+ libs-y += arch/sparc/prom/
+ libs-y += arch/sparc/lib/
+ drivers-$(CONFIG_PM) += arch/sparc/power/
+ drivers-$(CONFIG_OPROFILE) += arch/sparc/oprofile/
7.5 Architecture-specific boot images
-------------------------------------
When "make" is executed without arguments, bzImage will be built.
-7.6 Building non-kbuild targets
--------------------------------
-
- extra-y
- extra-y specifies additional targets created in the current
- directory, in addition to any targets specified by `obj-*`.
-
- Listing all targets in extra-y is required for two purposes:
-
- 1) Enable kbuild to check changes in command lines
-
- - When $(call if_changed,xxx) is used
-
- 2) kbuild knows what files to delete during "make clean"
-
- Example::
-
- #arch/x86/kernel/Makefile
- extra-y := head.o init_task.o
-
- In this example, extra-y is used to list object files that
- shall be built, but shall not be linked as part of built-in.a.
-
7.7 Commands useful for building a boot image
---------------------------------------------
Kbuild provides a few macros that are useful when building a
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 7.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/...)
-
- Note:
- if_changed should not be used more than once per target.
- It stores the executed command in a corresponding .cmd
-
- file and multiple calls would result in overwrites and
- unwanted results when the target is up to date and only the
- tests on changed commands trigger execution of commands.
-
ld
Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
targets += $(dtb-y)
DTC_FLAGS ?= -p 1024
-7.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".
-
-
7.9 Preprocessing linker scripts
--------------------------------