Tutorial getting-started: introduce -P

... as an way of directly obtaining an artifact without
an additional detour through the file system.

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/tutorial/getting-started.org b/doc/tutorial/getting-started.org
index 033309fb..36530d5a 100644
--- a/doc/tutorial/getting-started.org
+++ b/doc/tutorial/getting-started.org
@@ -89,6 +89,26 @@ Note that the ~install~ subcommand initiates the build a second time, without
 executing any actions as all actions are being served from cache. The produced
 artifact is identical, which is indicated by the same hash/size/type.
 
+If one is only interested in a single final artifact, one can
+also request via the ~-P~ option that this artifact be written to
+standard output after the build. As all messages are reported to
+standard error, this can be used for both, interactively reading a
+text file, as well as for piping the artifact to another program.
+
+#+BEGIN_SRC sh
+$ just build greeter -Pout.txt
+INFO: Requested target is [["@","","","greeter"],{}]
+INFO: Analysed target [["@","","","greeter"],{}]
+INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
+INFO: Discovered 1 actions, 0 trees, 0 blobs
+INFO: Building [["@","","","greeter"],{}].
+INFO: Processed 1 actions, 1 cache hits.
+INFO: Artifacts built, logical paths are:
+        out.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
+Hello World
+$
+#+END_SRC
+
 Alternatively, we could also directly request the artifact ~out.txt~ from
 /justbuild/'s CAS (content-addressable storage) and print it on the command line
 via: