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