Commit 39bb232a authored by Masahiro Yamada's avatar Masahiro Yamada
Browse files

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: default avatarMasahiro Yamada <masahiroy@kernel.org>
parent 41cac083

Documentation/kbuild/makefiles.rst

+52 −42
Original line number Diff line number Diff line
@@ -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.

CRA Git | Maintained and supported by SUSTech CRA and CCSE