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

6 files changed, 34 insertions, 11 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index f75030f17..bab20e10d 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 000000000..d6e54b5df
--- /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.
diff --git a/mesonbuild/backend/backends.py b/mesonbuild/backend/backends.py
index e423473d4..7eccca4a7 100644
--- a/mesonbuild/backend/backends.py
+++ b/mesonbuild/backend/backends.py
@@ -750,7 +750,7 @@ class Backend:
         result = OrderedDict()
         # Get all build and custom targets that must be built by default
         for name, t in self.build.get_targets().items():
-            if t.build_by_default or t.install or t.build_always:
+            if t.build_by_default or t.install:
                 result[name] = t
         # Get all targets used as test executables and arguments. These must
         # also be built by default. XXX: Sometime in the future these should be
diff --git a/mesonbuild/backend/ninjabackend.py b/mesonbuild/backend/ninjabackend.py
index 48f5fc2fc..9d72225ac 100644
--- a/mesonbuild/backend/ninjabackend.py
+++ b/mesonbuild/backend/ninjabackend.py
@@ -504,7 +504,7 @@ int dummy;
         deps = self.unwrap_dep_list(target)
         deps += self.get_custom_target_depend_files(target)
         desc = 'Generating {0} with a {1} command.'
-        if target.build_always:
+        if target.build_always_stale:
             deps.append('PHONY')
         if target.depfile is None:
             rulename = 'CUSTOM_COMMAND'
diff --git a/mesonbuild/build.py b/mesonbuild/build.py
index 331b5524a..c91bbe6fc 100644
--- a/mesonbuild/build.py
+++ b/mesonbuild/build.py
@@ -309,7 +309,7 @@ a hard error in the future.''' % name)
         self.subproject = subproject
         self.build_by_default = build_by_default
         self.install = False
-        self.build_always = False
+        self.build_always_stale = False
         self.option_overrides = {}
 
     def get_basename(self):
@@ -1636,6 +1636,7 @@ class CustomTarget(Target):
         'install_dir',
         'install_mode',
         'build_always',
+        'build_always_stale',
         'depends',
         'depend_files',
         'depfile',
@@ -1788,9 +1789,16 @@ class CustomTarget(Target):
             self.install = False
             self.install_dir = [None]
             self.install_mode = None
-        self.build_always = kwargs.get('build_always', False)
-        if not isinstance(self.build_always, bool):
-            raise InvalidArguments('Argument build_always must be a boolean.')
+        if 'build_always' in kwargs and 'build_always_stale' in kwargs:
+            raise InvalidArguments('build_always and build_always_stale are mutually exclusive. Combine build_by_default and build_always_stale.')
+        elif 'build_always' in kwargs:
+            mlog.warning('build_always is deprecated. Combine build_by_default and build_always_stale instead.')
+            self.build_by_default = kwargs['build_always']
+            self.build_always_stale = kwargs['build_always']
+        elif 'build_always_stale' in kwargs:
+            self.build_always_stale = kwargs['build_always_stale']
+        if not isinstance(self.build_always_stale, bool):
+            raise InvalidArguments('Argument build_always_stale must be a boolean.')
         extra_deps, depend_files = extract_as_list(kwargs, 'depends', 'depend_files', pop = False)
         for ed in extra_deps:
             while hasattr(ed, 'held_object'):
diff --git a/mesonbuild/interpreter.py b/mesonbuild/interpreter.py
index 343b7a564..eb09f3a89 100644
--- a/mesonbuild/interpreter.py
+++ b/mesonbuild/interpreter.py
@@ -1783,7 +1783,7 @@ permitted_kwargs = {'add_global_arguments': {'language'},
                     'benchmark': {'args', 'env', 'should_fail', 'timeout', 'workdir', 'suite'},
                     'build_target': known_build_target_kwargs,
                     'configure_file': {'input', 'output', 'configuration', 'command', 'copy', 'install_dir', 'install_mode', 'capture', 'install', 'format', 'output_format', 'encoding'},
-                    'custom_target': {'input', 'output', 'command', 'install', 'install_dir', 'install_mode', 'build_always', 'capture', 'depends', 'depend_files', 'depfile', 'build_by_default'},
+                    'custom_target': {'input', 'output', 'command', 'install', 'install_dir', 'install_mode', 'build_always', 'capture', 'depends', 'depend_files', 'depfile', 'build_by_default', 'build_always_stale'},
                     'dependency': {'default_options', 'fallback', 'language', 'main', 'method', 'modules', 'optional_modules', 'native', 'required', 'static', 'version', 'private_headers'},
                     'declare_dependency': {'include_directories', 'link_with', 'sources', 'dependencies', 'compile_args', 'link_args', 'link_whole', 'version'},
                     'executable': build.known_exe_kwargs,
@@ -3012,7 +3012,8 @@ root and issuing %s.
              source_dir,
              replace_string,
              regex_selector] + vcs_cmd
-        kwargs.setdefault('build_always', True)
+        kwargs.setdefault('build_by_default', True)
+        kwargs.setdefault('build_always_stale', True)
         return self.func_custom_target(node, [kwargs['output']], kwargs)
 
     @FeatureNew('subdir_done', '0.46.0')
@@ -3025,7 +3026,7 @@ root and issuing %s.
         raise SubdirDoneRequest()
 
     @stringArgs
-    @FeatureNewKwargs('custom_target', '0.47.0', ['install_mode'])
+    @FeatureNewKwargs('custom_target', '0.47.0', ['install_mode', 'build_always_stale'])
     @FeatureNewKwargs('custom_target', '0.40.0', ['build_by_default'])
     @permittedKwargs(permitted_kwargs['custom_target'])
     def func_custom_target(self, node, args, kwargs):