On 11/22/20 8:54 PM, Masahiro Yamada wrote:
> 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 <masahi...@kernel.org>
> ---
>
> 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 f5a983709df7..49afcb1d3695 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_cmt_<command> = ...
cmd
> + 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, hostprogs, userprogs, Kbuild automatically
then Kbuild
automatically
> + add it to $(targets). Otherwise, the target must be explicitly added
adds
> + 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.
>
>
thanks.
--
~Randy
