Document action restat behavior.
The question came up recently about how to enable "restat = 1" for
action commands in GN. This is set automatically but is never mentioned.
Document this behavior of action and action_foreach.
Change-Id: I3c9fced5b6ca9090835f506bfaa2226003bc46d3
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/7320
Reviewed-by: Scott Graham <scottmg@chromium.org>
Commit-Queue: Brett Wilson <brettw@chromium.org>
diff --git a/docs/reference.md b/docs/reference.md
index 5c2223a..5222fb8 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -1186,6 +1186,14 @@
file names to be relative to the build directory (file names in the
sources, outputs, and inputs will be all treated as relative to the
current build file and converted as needed automatically).
+
+ GN sets Ninja's flag 'restat = 1` for all action commands. This means
+ that Ninja will check the timestamp of the output after the action
+ completes. If output timestamp is unchanged, the step will be treated
+ as if it never needed to be rebuilt, potentially eliminating some
+ downstream steps for incremental builds. Scripts can improve build
+ performance by taking care not to change the timstamp of the output
+ file(s) if the contents have not changed.
```
#### **File name handling**
@@ -1267,6 +1275,14 @@
file names to be relative to the build directory (file names in the
sources, outputs, and inputs will be all treated as relative to the
current build file and converted as needed automatically).
+
+ GN sets Ninja's flag 'restat = 1` for all action commands. This means
+ that Ninja will check the timestamp of the output after the action
+ completes. If output timestamp is unchanged, the step will be treated
+ as if it never needed to be rebuilt, potentially eliminating some
+ downstream steps for incremental builds. Scripts can improve build
+ performance by taking care not to change the timstamp of the output
+ file(s) if the contents have not changed.
```
#### **File name handling**
diff --git a/src/gn/functions_target.cc b/src/gn/functions_target.cc
index 2c880c0..5ce0901 100644
--- a/src/gn/functions_target.cc
+++ b/src/gn/functions_target.cc
@@ -72,7 +72,15 @@
" to your script, see \"gn help rebase_path\" for how to convert\n" \
" file names to be relative to the build directory (file names in the\n" \
" sources, outputs, and inputs will be all treated as relative to the\n" \
- " current build file and converted as needed automatically).\n"
+ " current build file and converted as needed automatically).\n" \
+ "\n" \
+ " GN sets Ninja's flag 'restat = 1` for all action commands. This means\n" \
+ " that Ninja will check the timestamp of the output after the action\n" \
+ " completes. If output timestamp is unchanged, the step will be treated\n" \
+ " as if it never needed to be rebuilt, potentially eliminating some\n" \
+ " downstream steps for incremental builds. Scripts can improve build\n" \
+ " performance by taking care not to change the timstamp of the output\n" \
+ " file(s) if the contents have not changed.\n"
// Common help paragraph on script output directories.
#define SCRIPT_EXECUTION_OUTPUTS \
