Skip to content

Commit 39bb232

Browse files
committed
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: Masahiro Yamada <[email protected]>
1 parent 41cac08 commit 39bb232

File tree

1 file changed

+52
-42
lines changed

1 file changed

+52
-42
lines changed

Documentation/kbuild/makefiles.rst

Lines changed: 52 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,9 @@ This document describes the Linux kernel Makefiles.
1616
--- 3.5 Library file goals - lib-y
1717
--- 3.6 Descending down in directories
1818
--- 3.7 Compilation flags
19-
--- 3.8 <deleted>
20-
--- 3.9 Dependency tracking
21-
--- 3.10 Custom Rules
19+
--- 3.8 Dependency tracking
20+
--- 3.9 Custom Rules
21+
--- 3.10 Command change detection
2222
--- 3.11 $(CC) support functions
2323
--- 3.12 $(LD) support functions
2424
--- 3.13 Script Invocation
@@ -410,7 +410,7 @@ more details, with real examples.
410410
AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
411411

412412

413-
3.9 Dependency tracking
413+
3.8 Dependency tracking
414414
-----------------------
415415

416416
Kbuild tracks dependencies on the following:
@@ -422,8 +422,8 @@ more details, with real examples.
422422
Thus, if you change an option to $(CC) all affected files will
423423
be re-compiled.
424424

425-
3.10 Custom Rules
426-
------------------
425+
3.9 Custom Rules
426+
----------------
427427

428428
Custom rules are used when the kbuild infrastructure does
429429
not provide the required support. A typical example is
@@ -499,6 +499,52 @@ more details, with real examples.
499499

500500
will be displayed with "make KBUILD_VERBOSE=0".
501501

502+
3.10 Command change detection
503+
-----------------------------
504+
505+
When the rule is evaluated, timestamps are compared between the target
506+
and its prerequisite files. GNU Make updates the target when any of the
507+
prerequisites is newer than that.
508+
509+
The target should be rebuilt also when the command line has changed
510+
since the last invocation. This is not supported by Make itself, so
511+
Kbuild achieves this by a kind of meta-programming.
512+
513+
if_changed is the macro used for this purpose, in the following form::
514+
515+
quiet_cmd_<command> = ...
516+
cmd_<command> = ...
517+
518+
<target>: <source(s)> FORCE
519+
$(call if_changed,<command>)
520+
521+
Any target that utilizes if_changed must be listed in $(targets),
522+
otherwise the command line check will fail, and the target will
523+
always be built.
524+
525+
If the target is already listed in the recognized syntax such as
526+
obj-y/m, lib-y/m, extra-y/m, always-y/m, hostprogs, userprogs, Kbuild
527+
automatically adds it to $(targets). Otherwise, the target must be
528+
explicitly added to $(targets).
529+
530+
Assignments to $(targets) are without $(obj)/ prefix. if_changed may be
531+
used in conjunction with custom rules as defined in "3.9 Custom Rules".
532+
533+
Note: It is a typical mistake to forget the FORCE prerequisite.
534+
Another common pitfall is that whitespace is sometimes significant; for
535+
instance, the below will fail (note the extra space after the comma)::
536+
537+
target: source(s) FORCE
538+
539+
**WRONG!** $(call if_changed, objcopy)
540+
541+
Note:
542+
if_changed should not be used more than once per target.
543+
It stores the executed command in a corresponding .cmd
544+
file and multiple calls would result in overwrites and
545+
unwanted results when the target is up to date and only the
546+
tests on changed commands trigger execution of commands.
547+
502548
3.11 $(CC) support functions
503549
----------------------------
504550

@@ -1287,42 +1333,6 @@ When kbuild executes, the following steps are followed (roughly):
12871333
Kbuild provides a few macros that are useful when building a
12881334
boot image.
12891335

1290-
if_changed
1291-
if_changed is the infrastructure used for the following commands.
1292-
1293-
Usage::
1294-
1295-
target: source(s) FORCE
1296-
$(call if_changed,ld/objcopy/gzip/...)
1297-
1298-
When the rule is evaluated, it is checked to see if any files
1299-
need an update, or the command line has changed since the last
1300-
invocation. The latter will force a rebuild if any options
1301-
to the executable have changed.
1302-
Any target that utilises if_changed must be listed in $(targets),
1303-
otherwise the command line check will fail, and the target will
1304-
always be built.
1305-
Assignments to $(targets) are without $(obj)/ prefix.
1306-
if_changed may be used in conjunction with custom rules as
1307-
defined in "3.10 Custom Rules".
1308-
1309-
Note: It is a typical mistake to forget the FORCE prerequisite.
1310-
Another common pitfall is that whitespace is sometimes
1311-
significant; for instance, the below will fail (note the extra space
1312-
after the comma)::
1313-
1314-
target: source(s) FORCE
1315-
1316-
**WRONG!** $(call if_changed, ld/objcopy/gzip/...)
1317-
1318-
Note:
1319-
if_changed should not be used more than once per target.
1320-
It stores the executed command in a corresponding .cmd
1321-
1322-
file and multiple calls would result in overwrites and
1323-
unwanted results when the target is up to date and only the
1324-
tests on changed commands trigger execution of commands.
1325-
13261336
ld
13271337
Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
13281338

0 commit comments

Comments
 (0)