aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/markdown/Reference-manual.md6
-rw-r--r--docs/markdown/snippets/deprecate_build_always.md12
2 files changed, 16 insertions, 2 deletions
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index f75030f..bab20e1 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -232,9 +232,11 @@ following.
- `build_by_default` *(added 0.38.0)* causes, when set to true, to
have this target be built by default, that is, when invoking plain
`ninja`; the default value is false
-- `build_always` if `true` this target is always considered out of
+- `build_always` (deprecated) if `true` this target is always considered out of
date and is rebuilt every time, useful for things such as build
- timestamps or revision control tags
+ timestamps or revision control tags.
+- `build_always_stale` if `true` the target is always considered out of date.
+ The associated command is run even if the outputs are up to date.
- `capture`, there are some compilers that can't be told to write
their output to a file but instead write it to standard output. When
this argument is set to true, Meson captures `stdout` and writes it
diff --git a/docs/markdown/snippets/deprecate_build_always.md b/docs/markdown/snippets/deprecate_build_always.md
new file mode 100644
index 0000000..d6e54b5
--- /dev/null
+++ b/docs/markdown/snippets/deprecate_build_always.md
@@ -0,0 +1,12 @@
+## Deprecate `build_always`
+
+Setting `build_always` to `true` for a custom target not only marks the target
+to be always considered out of date, but also adds it to the set of default
+targets. This option is therefore deprecated and the new option
+`build_always_stale` is introduced.
+
+`build_always_stale` *only* marks the target to be always considered out of
+date, but does not add it to the set of default targets. The old behaviour can
+be achieved by combining `build_always_stale` with `build_by_default`.
+
+The documentation has been updated accordingly.