tutorial/getting-started: Also introduce the concept of staging

Staging is quite a fundamental concept of just. Therefore, introduce
it early in the tutorial. In this way, it also becomes obvious, why
only targets are requested and files are not installed by default.

1 files changed, 93 insertions, 0 deletions

diff --git a/doc/tutorial/getting-started.org b/doc/tutorial/getting-started.org
index 36530d5a..1573a8b9 100644
--- a/doc/tutorial/getting-started.org
+++ b/doc/tutorial/getting-started.org
@@ -133,3 +133,96 @@ $ just install-cas 557db03de997c86a4a028e1ebd3a1ceb225be238
 Hello World
 $
 #+END_SRC
+
+** Targets versus Files: The Stage
+
+When invoking the ~build~ command, we had to specify the target ~greeter~,
+not the output file ~out.txt~. While other build systems allow requests
+specifying an output file, for /justbuild/ this would conflict with a
+fundamental design principle: staging; each target has its own logical
+output space, the "stage", where it can put its artifacts. We can, without
+any problem, add a second target also generating a file ~out.txt~.
+
+#+SRCNAME: TARGETS
+#+BEGIN_SRC js
+{ "greeter":
+  { "type": "generic"
+  , "cmds": ["echo -n 'Hello ' > out.txt", "cat name.txt >> out.txt"]
+  , "outs": ["out.txt"]
+  , "deps": ["name.txt"]
+  }
+, "upper":
+  { "type": "generic"
+  , "cmds": ["cat name.txt | tr a-z A-Z > out.txt"]
+  , "outs": ["out.txt"]
+  , "deps": ["name.txt"]
+  }
+}
+#+END_SRC
+
+As we only request targets, no conflicts arise.
+
+#+BEGIN_SRC sh
+$ just build upper -P out.txt
+INFO: Requested target is [["@","","","upper"],{}]
+INFO: Analysed target [["@","","","upper"],{}]
+INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
+INFO: Discovered 1 actions, 0 trees, 0 blobs
+INFO: Building [["@","","","upper"],{}].
+INFO: Processed 1 actions, 0 cache hits.
+INFO: Artifacts built, logical paths are:
+        out.txt [83cf24cdfb4891a36bee93421930dd220766299a:6:f]
+WORLD
+$ just build greeter -P out.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
+
+While one normally tries to design targets in such a way that they
+don't have conflicting files if they should be used together, it is
+up to the receiving target to decide what to do with those artifacts.
+A built-in rule allowing to rearrange artifacts is ~"install"~; a
+detailed description of this rule can be found in the documentation.
+In the simple case of a target producing precisely one file, the
+argument ~"files"~ can be used to map that file to a new location.
+
+#+SRCNAME: TARGETS
+#+BEGIN_SRC js
+{ "greeter":
+  { "type": "generic"
+  , "cmds": ["echo -n 'Hello ' > out.txt", "cat name.txt >> out.txt"]
+  , "outs": ["out.txt"]
+  , "deps": ["name.txt"]
+  }
+, "upper":
+  { "type": "generic"
+  , "cmds": ["cat name.txt | tr a-z A-Z > out.txt"]
+  , "outs": ["out.txt"]
+  , "deps": ["name.txt"]
+  }
+, "both":
+  {"type": "install", "files": {"hello.txt": "greeter", "upper.txt": "upper"}}
+}
+#+END_SRC
+
+#+BEGIN_SRC sh
+$ just build both
+INFO: Requested target is [["@","","","both"],{}]
+INFO: Analysed target [["@","","","both"],{}]
+INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
+INFO: Discovered 2 actions, 0 trees, 0 blobs
+INFO: Building [["@","","","both"],{}].
+INFO: Processed 2 actions, 2 cache hits.
+INFO: Artifacts built, logical paths are:
+        hello.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
+        upper.txt [83cf24cdfb4891a36bee93421930dd220766299a:6:f]
+$
+#+END_SRC