kbuild: doc: split if_changed explanation to a separate section
The if_changed macro is currently explained in the section "Commands useful for building a boot image", but the use of if_changed is not limited to the boot image. It is often used together with custom rules. Let's split it as a separate section, and insert it after the "Custom Rules" section. I slightly reworded the explanation, re-numbered to fill the <deleted> section, and also fixed the broken indentation of the Note: part. Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>zero-sugar-mainline-defconfig
Masahiro Yamada
parent
41cac0834f
commit
39bb232ae6
|
|
@ -16,9 +16,9 @@ This document describes the Linux kernel Makefiles.
|
|||
--- 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 Custom Rules
|
||||
--- 3.8 Dependency tracking
|
||||
--- 3.9 Custom Rules
|
||||
--- 3.10 Command change detection
|
||||
--- 3.11 $(CC) support functions
|
||||
--- 3.12 $(LD) support functions
|
||||
--- 3.13 Script Invocation
|
||||
|
|
@ -410,7 +410,7 @@ more details, with real examples.
|
|||
AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
|
||||
|
||||
|
||||
3.9 Dependency tracking
|
||||
3.8 Dependency tracking
|
||||
-----------------------
|
||||
|
||||
Kbuild tracks dependencies on the following:
|
||||
|
|
@ -422,8 +422,8 @@ more details, with real examples.
|
|||
Thus, if you change an option to $(CC) all affected files will
|
||||
be re-compiled.
|
||||
|
||||
3.10 Custom Rules
|
||||
------------------
|
||||
3.9 Custom Rules
|
||||
----------------
|
||||
|
||||
Custom rules are used when the kbuild infrastructure does
|
||||
not provide the required support. A typical example is
|
||||
|
|
@ -499,6 +499,52 @@ more details, with real examples.
|
|||
|
||||
will be displayed with "make KBUILD_VERBOSE=0".
|
||||
|
||||
3.10 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)
|
||||
|
||||
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.11 $(CC) support functions
|
||||
----------------------------
|
||||
|
||||
|
|
@ -1287,42 +1333,6 @@ When kbuild executes, the following steps are followed (roughly):
|
|||
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 rules as
|
||||
defined in "3.10 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, 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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue