Date:   Mon, 23 Nov 2020 09:51:59 -0800
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Masahiro Yamada <masahiroy@...nel.org>,
        linux-kbuild@...r.kernel.org
Cc:     Jonathan Corbet <corbet@....net>,
        Michal Marek <michal.lkml@...kovi.net>,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 5/7] kbuild: doc: split if_changed explanation to a
 separate section

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 <masahiroy@...nel.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

Powered by blists - more mailing lists