custom targets: Add a 'console' kwarg for long-running commandsnirbheek/custom-target-verbose

Ninja buffers all commands and prints them only after they are
complete. Because of this, long-running commands such as `cargo
build` show no output at all and it's impossible to know if the
command is merely taking too long or is stuck somewhere.

To cater to such use-cases, Ninja has a 'pool' with depth 1 called
'console', and all processes in this pool have the following
properties:

1. stdout is connected to the program, so output can be seen in
   real-time
2. The output of all other commands is buffered and displayed after
   a command in this pool finishes running
3. Commands in this pool are executed serially (normal commands
   continue to run in the background)

This feature is available since Ninja v1.5

https://ninja-build.org/manual.html#_the_literal_console_literal_pool

5 files changed, 29 insertions, 1 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index e3ae111dc..166cc73ac 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -244,6 +244,12 @@ following.
   this argument is set to true, Meson captures `stdout` and writes it
   to the target file. Note that your command argument list may not
   contain `@OUTPUT@` when capture mode is active.
+- `console` keyword argument conflicts with `capture`, and is meant
+  for commands that are resource-intensive and take a long time to
+  finish. With the Ninja backend, setting this will add this target
+  to [Ninja's `console` pool](https://ninja-build.org/manual.html#_the_literal_console_literal_pool),
+  which has special properties such as not buffering stdout and
+  serializing all targets in this pool.
 - `command` command to run to create outputs from inputs. The command
   may be strings or the return value of functions that return file-like
   objects such as [`find_program()`](#find_program),
diff --git a/docs/markdown/snippets/custom_target_console_pool.md b/docs/markdown/snippets/custom_target_console_pool.md
new file mode 100644
index 000000000..097b0081f
--- /dev/null
+++ b/docs/markdown/snippets/custom_target_console_pool.md
@@ -0,0 +1,13 @@
+## New kwarg `console` for `custom_target()`
+
+This keyword argument conflicts with `capture`, and is meant for commands
+that are resource-intensive and take a long time to finish. With the Ninja
+backend, setting this will add this target to [Ninja's `console`
+pool](https://ninja-build.org/manual.html#_the_literal_console_literal_pool),
+which has special properties such as not buffering stdout and serializing all
+targets in this pool.
+
+The primary use-case for this is to be able to run external package managers
+such as `cargo` to produce build artifacts. Without setting this, the user does
+not receive any feedback about what the package manager is doing, which can
+take a very long time to download and build packages.
diff --git a/mesonbuild/backend/ninjabackend.py b/mesonbuild/backend/ninjabackend.py
index 09c49049d..ac48b54b1 100644
--- a/mesonbuild/backend/ninjabackend.py
+++ b/mesonbuild/backend/ninjabackend.py
@@ -560,6 +560,8 @@ int dummy;
             abs_pdir = os.path.join(self.environment.get_build_dir(), self.get_target_dir(target))
             os.makedirs(abs_pdir, exist_ok=True)
             elem.add_item('DEPFILE', rel_dfile)
+        if target.console:
+            elem.add_item('pool', 'console')
         cmd = self.replace_paths(target, cmd)
         elem.add_item('COMMAND', cmd)
         elem.add_item('description', desc.format(target.name, cmd_type))
diff --git a/mesonbuild/build.py b/mesonbuild/build.py
index 65438b005..a3cd9933d 100644
--- a/mesonbuild/build.py
+++ b/mesonbuild/build.py
@@ -1638,6 +1638,7 @@ class CustomTarget(Target):
         'depfile',
         'build_by_default',
         'override_options',
+        'console',
     ])
 
     def __init__(self, name, subdir, subproject, kwargs, absolute_paths=False):
@@ -1756,6 +1757,11 @@ class CustomTarget(Target):
         self.capture = kwargs.get('capture', False)
         if self.capture and len(self.outputs) != 1:
             raise InvalidArguments('Capturing can only output to a single file.')
+        self.console = kwargs.get('console', False)
+        if not isinstance(self.console, bool):
+            raise InvalidArguments('"console" kwarg only accepts booleans')
+        if self.capture and self.console:
+            raise InvalidArguments("Can't both capture output and output to console")
         if 'command' not in kwargs:
             raise InvalidArguments('Missing keyword argument "command".')
         if 'depfile' in kwargs:
diff --git a/mesonbuild/interpreter.py b/mesonbuild/interpreter.py
index 2c54eaeca..abbe66572 100644
--- a/mesonbuild/interpreter.py
+++ b/mesonbuild/interpreter.py
@@ -1812,7 +1812,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', 'build_always_stale'},
+                    'custom_target': {'input', 'output', 'command', 'install', 'install_dir', 'install_mode', 'build_always', 'capture', 'depends', 'depend_files', 'depfile', 'build_by_default', 'build_always_stale', 'console'},
                     '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,
@@ -3096,6 +3096,7 @@ root and issuing %s.
         raise SubdirDoneRequest()
 
     @stringArgs
+    @FeatureNewKwargs('custom_target', '0.48.0', ['console'])
     @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'])