diff mbox series

[5/7] kbuild: doc: split if_changed explanation to a separate section

Message ID 20201123045403.63402-5-masahiroy@kernel.org (mailing list archive)
State New
Headers show
Series [1/7] kbuild: doc: update the description about kbuild Makefiles | expand

Commit Message

Masahiro Yamada Nov. 23, 2020, 4:54 a.m. UTC
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>
---

 Documentation/kbuild/makefiles.rst | 94 +++++++++++++++++-------------
 1 file changed, 52 insertions(+), 42 deletions(-)

Comments

Randy Dunlap Nov. 23, 2020, 5:51 p.m. UTC | #1
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@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.
diff mbox series

Patch

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_<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
+	add 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.