Tutorial: Add minimalistic getting started section

2 files changed, 99 insertions, 33 deletions

diff --git a/doc/tutorial/getting-started.org b/doc/tutorial/getting-started.org
new file mode 100644
index 00000000..2ca8cb29
--- /dev/null
+++ b/doc/tutorial/getting-started.org
@@ -0,0 +1,98 @@
+* Getting Started
+
+In order to use /justbuild/, first make sure that ~just~ is available in your
+~PATH~.
+
+** Creating a new project
+
+/justbuild/ needs to know the root of the project worked on. By default, it
+searches upwards from the current directory till it finds a marker. Currently,
+we support three different markers: the files ~ROOT~ and ~WORKSPACE~ or the
+directory ~.git~. Lets create a new project by creating one of those markers:
+
+#+BEGIN_SRC sh
+$ touch ROOT
+#+END_SRC
+
+** Creating a generic target
+
+By default, targets are described in ~TARGETS~ files. These files contain a
+~JSON~ object with the target name as key and the target description as value. A
+target description is an object with at least a single mandatory field:
+~"type"~. This field specifies which rule (built-in or user-defined) to apply
+for this target.
+
+A simple target that only executes commands can be created using the built-in
+~"generic"~ rule, which requires at least one command and one output file or
+directory. To create such a target, create the file ~TARGETS~ with the following
+content:
+
+#+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"]
+  }
+}
+#+END_SRC
+
+In this example, the ~"greeter"~ target will run two commands to produce the
+output file ~out.txt~. The second command depends on the input file ~name.txt~
+that we need to create as well:
+
+#+BEGIN_SRC sh
+$ echo World > name.txt
+#+END_SRC
+
+** Building a generic target
+
+To build a target, we need to run ~just~ with the subcommand ~build~:
+
+#+BEGIN_SRC sh
+$ just build greeter
+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, 0 cache hits.
+INFO: Artifacts built, logical paths are:
+        out.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
+$
+#+END_SRC
+
+The subcommand ~build~ just builds the binary but does not stage it to any
+user-defined location on the file system. To also stage the produced artifact to
+the working directory, use the ~install~ subcommand and specify the output
+directory:
+
+#+BEGIN_SRC sh
+$ just install greeter -o .
+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 can be found in:
+        /tmp/tutorial/out.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
+$ cat out.txt
+Hello World
+$
+#+END_SRC
+
+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.
+
+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:
+
+#+BEGIN_SRC sh
+$ just install-cas [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
+Hello World
+$
+#+END_SRC
diff --git a/doc/tutorial/hello-world.org b/doc/tutorial/hello-world.org
index e10782f8..eddc7634 100644
--- a/doc/tutorial/hello-world.org
+++ b/doc/tutorial/hello-world.org
@@ -1,4 +1,4 @@
-* Building Hello World
+* Building C++ Hello World
 
 /justbuild/ is a true language-agnostic (there are no more-equal languages) and
 multi-repository build system. As a consequence, high-level concepts (e.g., C++
@@ -58,14 +58,6 @@ an empty file ~ROOT~:
 $ touch ROOT
 #+END_SRC
 
-By default, targets are described in ~TARGETS~ files. These files contain a
-~JSON~ object with the target name as key and the target description as value. A
-target description is an object with at least a single mandatory field:
-~"type"~. This field specifies which rule (built-in or user-defined) to apply
-for this target. Depending on which rule is used, specifying additional fields
-may be required. For all user-defined rules, the content of each field must be
-a list of either strings or targets.
-
 For this tutorial, we want to create a target ~helloworld~ that produces a
 binary from the C++ source ~main.cpp~. To define such a target, create a
 ~TARGETS~ file with the following content:
@@ -154,30 +146,6 @@ INFO: Artifacts built, logical paths are:
 $
 #+END_SRC
 
-Note that this command just builds the binary but does not stage it to any
-user-defined location on the file system. To also stage the produced artifact to
-the working directory, use the ~install~ subcommand and specify the output
-directory:
-
-#+BEGIN_SRC sh
-$ just install -C $CONF helloworld -o .
-INFO: Requested target is [["@","tutorial","","helloworld"],{}]
-INFO: Analysed target [["@","tutorial","","helloworld"],{}]
-INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
-INFO: Discovered 2 actions, 1 trees, 0 blobs
-INFO: Building [["@","tutorial","","helloworld"],{}].
-INFO: Processed 2 actions, 2 cache hits.
-INFO: Artifacts can be found in:
-        /tmp/tutorial/helloworld [b5cfca8b810adc4686f5cac00258a137c5d4a3ba:17088:x]
-$ ./helloworld
-Hello world!
-$
-#+END_SRC
-
-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
-binary is identical, which is indicated by the same hash/size/type.
-
 By default, the BSD-default compiler front-ends (which are also defined for most
 Linux distributions) ~cc~ and ~c++~ are used for C and C++ (variables ~"CC"~ and
 ~"CXX"~). If you want to temporarily use different defaults, you can use ~-D~ to