From a2dab5439cfbbc2c35c223f0cf6ae2c58e8fd1b9 Mon Sep 17 00:00:00 2001 From: Nirbheek Chauhan Date: Sun, 12 Nov 2017 20:57:53 +0530 Subject: custom targets: Add a 'console' kwarg for long-running commands 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 --- docs/markdown/Reference-manual.md | 6 ++++++ docs/markdown/snippets/custom_target_console_pool.md | 13 +++++++++++++ 2 files changed, 19 insertions(+) create mode 100644 docs/markdown/snippets/custom_target_console_pool.md (limited to 'docs/markdown') diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index db8eed1..9f49831 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 0000000..097b008 --- /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. -- cgit v1.1