Deprecate `build_always`, add `build_always_stale`

Since `build_always` also adds a target to the set of default targets,
this option is marked deprecated in favour of the new option
`build_always_stale`.

`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 still be achieved by combining
`build_always_stale` with `build_by_default`.

fixes #1942

1 files changed, 4 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