doc: Adding part 2 of the getting started tutorial

  o doc/examples/running-commands: New example project of a `manual` build element

  o doc/sessions/running-commands.run: New session file to capture bst output

  o doc/source/sessions-stored: Added new generated sessions

  o doc/source/tutorial/running-commands.rst: New tutorial entry describing how
                                              commands are run in the sandbox

  o tests/examples/running-commands.py: Test case validating the tutorial's assertions

doc/examples/running-commands/elements/base.bst

+kind: stack
+description: Base stack
+
+depends:
+- base/alpine.bst

doc/examples/running-commands/elements/base/alpine.bst

+kind: import
+description: |
+
+    Alpine Linux base runtime
+
+sources:
+- kind: tar
+
+  # This is a post doctored, trimmed down system image
+  # of the Alpine linux distribution.
+  #
+  url: alpine:integration-tests-base.v1.x86_64.tar.xz
+  ref: 3eb559250ba82b64a68d86d0636a6b127aa5f6d25d3601a79f79214dc9703639

doc/examples/running-commands/elements/hello.bst

+kind: manual
+description: |
+
+  Building manually
+
+# Depend on the base system
+depends:
+- base.bst
+
+# Stage the files/src directory for building
+sources:
+  - kind: local
+    path: files/src
+
+# Now configure the commands to run
+config:
+
+  build-commands:
+  - make PREFIX="%{prefix}"
+
+  install-commands:
+  - make -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install

doc/examples/running-commands/files/src/Makefile

+# Sample makefile for hello.c
+#
+.PHONY: all install
+
+all: hello
+
+install:
+	install -d ${DESTDIR}${PREFIX}/bin
+	install -m 755 hello ${DESTDIR}${PREFIX}/bin
+
+hello: hello.c
+	$(CC) -Wall -o $@ $<

doc/examples/running-commands/files/src/hello.c

+/*
+ * hello.c - Simple hello world program
+ */
+#include <stdio.h>
+
+int main(int argc, char *argv[])
+{
+  printf("Hello World\n");
+  return 0;
+}

doc/examples/running-commands/project.conf

+# Unique project name
+name: running-commands
+
+# Required BuildStream format version
+format-version: 9
+
+# Subdirectory where elements are stored
+element-path: elements
+
+# Define an alias for our alpine tarball
+aliases:
+  alpine: https://gnome7.codethink.co.uk/tarballs/

doc/sessions/running-commands.run

+
+commands:
+# Make it fetch first
+- directory: ../examples/running-commands
+  command: fetch hello.bst
+
+# Capture a show output
+- directory: ../examples/running-commands
+  output: ../source/sessions/running-commands-show-before.html
+  command: show hello.bst
+
+# Capture a build output
+- directory: ../examples/running-commands
+  output: ../source/sessions/running-commands-build.html
+  command: build hello.bst
+
+# Capture another show output
+- directory: ../examples/running-commands
+  output: ../source/sessions/running-commands-show-after.html
+  command: show hello.bst
+
+# Capture a shell output
+- directory: ../examples/running-commands
+  output: ../source/sessions/running-commands-shell.html
+  command: shell hello.bst -- hello

doc/source/core_plugins.rst

@@ -23,6 +23,8 @@ General elements
    elements/filter
 
 
+.. _plugins_build_elements:
+
 Build elements
 --------------
 .. toctree::

doc/source/sessions-stored/running-commands-shell.html

+<!--
+    WARNING: This file was generated with bst2html.py
+-->
+<div class="highlight" style="font-size:x-small"><pre>
+<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/running-commands</span>$ bst shell hello.bst -- hello
+
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Staging dependencies
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Staging dependencies
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Integrating sandbox
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Integrating sandbox
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">c50da053</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000"> main</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">hello.bst                     </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#06989A"><span style=""><span style="opacity:0.5">STATUS </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Running command
+
+<span style="opacity:0.5">    hello</span>
+
+Hello World
+</pre></div>

doc/source/sessions-stored/running-commands-show-after.html

+<!--
+    WARNING: This file was generated with bst2html.py
+-->
+<div class="highlight" style="font-size:x-small"><pre>
+<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/running-commands</span>$ bst show hello.bst
+
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
+<span style="color:#75507B">      cached</span> <span style="color:#C4A000">a352c93edfc55a41868b4f482758ad3ea1c21571532373542cd20b9135f0718d</span> <span style="color:#3465A4"><span style="">base/alpine.bst</span></span> 
+<span style="color:#75507B">      cached</span> <span style="color:#C4A000">a8eeb045115a4a71c18d09fe14b7b4fc3f3e838414a7d23d7c6d4c3027f28743</span> <span style="color:#3465A4"><span style="">base.bst</span></span> 
+<span style="color:#75507B">      cached</span> <span style="color:#C4A000">c50da0531f050b51a7ddb6f331750642ad222ae6a81a16e091e026aa4d7cc07a</span> <span style="color:#3465A4"><span style="">hello.bst</span></span> 
+</pre></div>

doc/source/sessions-stored/running-commands-show-before.html

+<!--
+    WARNING: This file was generated with bst2html.py
+-->
+<div class="highlight" style="font-size:x-small"><pre>
+<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/running-commands</span>$ bst show hello.bst
+
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
+<span style="color:#4E9A06">   buildable</span> <span style="color:#C4A000">a352c93edfc55a41868b4f482758ad3ea1c21571532373542cd20b9135f0718d</span> <span style="color:#3465A4"><span style="">base/alpine.bst</span></span> 
+<span style="color:#3465A4">     waiting</span> <span style="color:#C4A000">a8eeb045115a4a71c18d09fe14b7b4fc3f3e838414a7d23d7c6d4c3027f28743</span> <span style="color:#3465A4"><span style="">base.bst</span></span> 
+<span style="color:#3465A4">     waiting</span> <span style="color:#C4A000">c50da0531f050b51a7ddb6f331750642ad222ae6a81a16e091e026aa4d7cc07a</span> <span style="color:#3465A4"><span style="">hello.bst</span></span> 
+</pre></div>

doc/source/tutorial/running-commands.rst

+
+
+Running commands
+================
+In :ref:`the first chapter <tutorial_first_project>` we only imported
+a file to create an artifact, this time lets run some commands inside
+the :ref:`isolated build sandbox <sandboxing>`.
+
+.. note::
+
+   This example is distributed with BuildStream
+   in the `doc/examples/running-commands
+   <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/running-commands>`_
+   subdirectory.
+
+
+Overview
+--------
+In this chapter, we'll be running commands inside the sandboxed
+execution environment and producing build output.
+
+We'll be compiling the following simple C file:
+
+
+``files/src/hello.c``
+~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: ../../examples/running-commands/files/src/hello.c
+   :language: c
+
+
+And we're going to build it using ``make``, using the following Makefile:
+
+
+``files/src/Makefile``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/running-commands/files/src/Makefile
+   :language: Makefile
+
+
+We'll be using the most fundamental :ref:`build element <plugins_build_elements>`,
+the :mod:`manual <elements.manual>` build element.
+
+The :mod:`manual <elements.manual>` element is the backbone on which all the other
+build elements are built, so understanding how it works at this level is helpful.
+
+
+Project structure
+-----------------
+In this project we have a ``project.conf``, a directory with some source
+code, and 3 element declarations.
+
+Let's first take a peek at what we need to build using :ref:`bst show <invoking_show>`:
+
+.. raw:: html
+   :file: ../sessions/running-commands-show-before.html
+
+This time we have loaded a pipeline with 3 elements, let's go over what they do
+in detail.
+
+
+``project.conf``
+~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/running-commands/project.conf
+   :language: yaml
+
+Our ``project.conf`` is very much like the last one, except that we
+have defined a :ref:`source alias <project_source_aliases>` for ``alpine``.
+
+.. tip::
+
+   Using :ref:`source aliases <project_source_aliases>` for groups of sources
+   which are generally hosted together is encouraged. This allows one to globally
+   change the access scheme or URL for a group of repositories which belong together.
+
+
+``elements/base/alpine.bst``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/running-commands/elements/base/alpine.bst
+   :language: yaml
+
+This :mod:`import <elements.import>` element uses a :mod:`tar <sources.tar>`
+source to download our Alpine Linux tarball to create our base runtime.
+
+This tarball is a sysroot which provides the C runtime libraries
+and some programs - this is what will be providing the programs we're
+going to run in this example.
+
+
+``elements/base.bst``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/running-commands/elements/base.bst
+   :language: yaml
+
+This is just a symbolic :mod:`stack <elements.stack>` element which declares that
+anything which depends on it, will implicitly depend on ``base/alpine.bst``.
+
+It is typical to use stack elements in places where the implementing logical
+software stack could change, but you rather not have your higher level components
+carry knowledge about those changing components.
+
+Any element which :ref:`runtime depends <format_dependencies_types>` on
+the ``base.bst`` will now be able to execute programs provided by the imported
+``base/alpine.bst`` runtime.
+
+
+``elements/hello.bst``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/running-commands/elements/hello.bst
+   :language: yaml
+
+Finally we have the element which executes commands. Looking at the
+:mod:`manual <elements.manual>` element's documentation, we can see that
+the element configuration exposes four command lists:
+
+* ``configure-commands``
+
+  Commands which are run in preparation of a build. This is where you
+  would normally call any configure stage build tools to configure
+  the build how you like and generate some files needed for the build.
+
+* ``build-commands``
+
+  Commands to run the build, usually a build system will
+  invoke the compiler for you here.
+
+* ``install-commands``
+
+  Commands to install the build results.
+
+  Commands to install the build results into the target system,
+  these should install files somewhere under ``%{install-root}``.
+
+* ``strip-commands``
+
+  Commands to doctor the build results after the install.
+
+  Typically this involves stripping binaries of debugging
+  symbols or stripping timestamps from build results to ensure
+  reproducibility.
+
+.. tip::
+
+   All other :ref:`build elements <plugins_build_elements>`
+   implement exactly the same command lists too, except that they provide
+   default commands specific to invoke the build systems they support.
+
+The :mod:`manual <elements.manual>` element however is the most basic
+and does not provide any default commands, so we have instructed it
+to use ``make`` to build and install our program.
+
+     
+Using the project
+-----------------
+
+
+Build the hello.bst element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To build the project, run :ref:`bst build <invoking_build>` in the
+following way:
+
+.. raw:: html
+   :file: ../sessions/running-commands-build.html
+
+Now we've built our hello world program, using ``make``
+and the C compiler provided by the Alpine Linux image.
+
+In the :ref:`first chapter <tutorial_first_project>` we observed that the inputs
+and output of an element are *directory trees*. In this example, the directory tree
+generated by ``base/alpine.bst`` is consumed by ``hello.bst`` due to the
+:ref:`implicit runtime dependency <format_dependencies_types>` introduced by ``base.bst``.
+
+.. tip::
+
+   All of the :ref:`dependencies <format_dependencies>` which are required to run for
+   the sake of a build, are staged at the root of the build sandbox. These comprise the
+   runtime environment in which the depending element will run commands.
+
+   The result is that the ``make`` program and C compiler provided by ``base/alpine.bst``
+   were already in ``$PATH`` and ready to run when the commands were needed by ``hello.bst``.
+
+Now observe that all of the elements in the loaded pipeline are ``cached``,
+the element is *built*:
+
+.. raw:: html
+   :file: ../sessions/running-commands-show-after.html
+
+
+Run the hello world program
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Now that we've built everything, we can indulge ourselves in running
+the hello world program using :ref:`bst shell <invoking_build>`:
+
+.. raw:: html
+   :file: ../sessions/running-commands-shell.html
+
+Here, :ref:`bst shell <invoking_build>` created a runtime environment for running
+the ``hello.bst`` element. This was done by staging all of the dependencies of
+``hello.bst`` including the ``hello.bst`` output itself into a directory. Once a directory
+with all of the dependencies was staged and ready, we ran the ``hello`` command from
+within the build sandbox environment.

doc/source/using_tutorial.rst

@@ -9,3 +9,4 @@ projects.
    :maxdepth: 1
 
    tutorial/first-project
+   tutorial/running-commands

tests/examples/running-commands.py

+import os
+import pytest
+
+from tests.testutils import cli_integration as cli
+from tests.testutils.integration import assert_contains
+from tests.testutils.site import IS_LINUX
+
+
+pytestmark = pytest.mark.integration
+DATA_DIR = os.path.join(
+    os.path.dirname(os.path.realpath(__file__)), '..', '..', 'doc', 'examples', 'running-commands'
+)
+
+
+@pytest.mark.skipif(not IS_LINUX, reason='Only available on linux')
+@pytest.mark.datafiles(DATA_DIR)
+def test_running_commands_build(cli, tmpdir, datafiles):
+    project = os.path.join(datafiles.dirname, datafiles.basename)
+    checkout = os.path.join(cli.directory, 'checkout')
+
+    result = cli.run(project=project, args=['build', 'hello.bst'])
+    assert result.exit_code == 0
+
+
+# Test running the executable
+@pytest.mark.skipif(not IS_LINUX, reason='Only available on linux')
+@pytest.mark.datafiles(DATA_DIR)
+def test_running_commands_run(cli, tmpdir, datafiles):
+    project = os.path.join(datafiles.dirname, datafiles.basename)
+
+    result = cli.run(project=project, args=['build', 'hello.bst'])
+    assert result.exit_code == 0
+
+    result = cli.run(project=project, args=['shell', 'hello.bst', '--', 'hello'])
+    assert result.exit_code == 0
+    assert result.output == 'Hello World\n'