tutorial, getting started: add the basics of analyse

1 files changed, 163 insertions, 0 deletions

diff --git a/doc/tutorial/getting-started.md b/doc/tutorial/getting-started.md
index 4d64157b..a97aea60 100644
--- a/doc/tutorial/getting-started.md
+++ b/doc/tutorial/getting-started.md
@@ -225,3 +225,166 @@ INFO: Artifacts built, logical paths are:
         upper.txt [83cf24cdfb4891a36bee93421930dd220766299a:6:f]
 $
 ```
+
+Inspecting internals: Analyse
+-----------------------------
+
+For our simple targets, it is easy to remember what they look like,
+and what the build steps are. For more complex projects this might
+no longer be the case. Therefore, *justbuild* tries to be very
+transparent about its understanding of the build. The command
+to do so is called `analyse` and also takes a target as argument.
+It shows all(!) the information available to a target depending
+on it. In the case of `greeter` this is just a single artifact.
+
+``` sh
+$ just analyse greeter
+INFO: Requested target is [["@","","","greeter"],{}]
+INFO: Analysed target [["@","","","greeter"],{}]
+INFO: Result of target [["@","","","greeter"],{}]: {
+        "artifacts": {
+          "out.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"}
+        },
+        "provides": {
+        },
+        "runfiles": {
+        }
+      }
+INFO: Target tainted ["test"].
+```
+
+As we can see, the artifact will be installed at the logical
+path `out.txt`. The artifact itself is generated by a build
+action, more precisely, it is the output `out.txt` of that
+action. Actions, in general, can have more than one output.
+
+For the target `both` we find the same artifact at a different
+output location in this case `hello.txt`.
+
+``` sh
+$ just analyse both
+INFO: Requested target is [["@","","","both"],{}]
+INFO: Analysed target [["@","","","both"],{}]
+INFO: Result of target [["@","","","both"],{}]: {
+        "artifacts": {
+          "hello.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"},
+          "upper.txt": {"data":{"id":"f122c2af488a56c94d08650a9d799dbb910484409116b8e0c071e198082256ef","path":"out.txt"},"type":"ACTION"}
+        },
+        "provides": {
+        },
+        "runfiles": {
+          "hello.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"},
+          "upper.txt": {"data":{"id":"f122c2af488a56c94d08650a9d799dbb910484409116b8e0c071e198082256ef","path":"out.txt"},"type":"ACTION"}
+        }
+      }
+INFO: Target tainted ["test"].
+```
+
+We also see another technical detail. As an `install` target,
+`both` also has the same artifact in the `runfiles` arrangement of
+files. Having two dedicated arrangements of artifacts, that are both
+installed when the target is installed, can be useful to distinguish
+between the main artifact and files needed when building against
+that target (e.g., to distinguish a library from its header files).
+As a very generic built-in rule, however, `install` simply makes
+all files available in both arrangements.
+
+The canonical way to obtain all action definitions is to dump the
+action graph using the `--dump-graph` option.
+
+``` sh
+$ just analyse both --dump-graph all-actions.json
+$ cat all-actions.json
+```
+
+As we know that the action was generated by the `greeter` target,
+was can also ask that target for the actions associated with it
+using the `--dump-actions` option. The `install` target does not
+generate any actions.
+
+``` sh
+$ just analyse greeter --dump-actions -
+INFO: Requested target is [["@","","","greeter"],{}]
+INFO: Analysed target [["@","","","greeter"],{}]
+INFO: Result of target [["@","","","greeter"],{}]: {
+        "artifacts": {
+          "out.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"}
+        },
+        "provides": {
+        },
+        "runfiles": {
+        }
+      }
+INFO: Actions for target [["@","","","greeter"],{}]:
+[
+  {
+    "command": ["sh","-c","echo -n 'Hello ' > out.txt\ncat name.txt >> out.txt\n"],
+    "input": {
+      "name.txt": {
+        "data": {
+          "path": "name.txt",
+          "repository": ""
+        },
+        "type": "LOCAL"
+      }
+    },
+    "output": ["out.txt"]
+  }
+]
+$ just analyse both --dump-actions -
+INFO: Requested target is [["@","","","both"],{}]
+INFO: Analysed target [["@","","","both"],{}]
+INFO: Result of target [["@","","","both"],{}]: {
+        "artifacts": {
+          "hello.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"},
+          "upper.txt": {"data":{"id":"f122c2af488a56c94d08650a9d799dbb910484409116b8e0c071e198082256ef","path":"out.txt"},"type":"ACTION"}
+        },
+        "provides": {
+        },
+        "runfiles": {
+          "hello.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"},
+          "upper.txt": {"data":{"id":"f122c2af488a56c94d08650a9d799dbb910484409116b8e0c071e198082256ef","path":"out.txt"},"type":"ACTION"}
+        }
+      }
+INFO: Actions for target [["@","","","both"],{}]:
+[
+]
+$
+```
+
+However, those actions are not owned by a target in any way.
+Actions are identified by their definition in the same way as
+`git` identifies a blob by its sequence of bytes and names it by
+a suitable hash value. So, let's add another target defining an
+action in the same way.
+
+``` {.jsonc srcname="TARGETS"}
+...
+, "another greeter":
+  { "type": "generic"
+  , "cmds": ["echo -n 'Hello ' > out.txt", "cat name.txt >> out.txt"]
+  , "outs": ["out.txt"]
+  , "deps": ["name.txt"]
+  }
+...
+```
+
+Then we find that it defines the same artifact.
+
+``` sh
+$ just analyse 'another greeter'
+INFO: Requested target is [["@","","","another greeter"],{}]
+INFO: Analysed target [["@","","","another greeter"],{}]
+INFO: Result of target [["@","","","another greeter"],{}]: {
+        "artifacts": {
+          "out.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"}
+        },
+        "provides": {
+        },
+        "runfiles": {
+        }
+      }
+```
+
+This is also the notion of equality used to detect conflicts when
+analysing targets before running any actions.