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@xxxxxxxxxx>
---
Changes in v2:
- fix typos
Documentation/kbuild/makefiles.rst | 94 +++++++++++++++++-------------
1 file changed, 52 insertions(+), 42 deletions(-)
diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index 29101d2a0072..1dde4a096226 100644
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -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, 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.
--
2.27.0
