You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildstream.apache.org by gi...@apache.org on 2020/12/29 13:15:59 UTC
[buildstream] 01/01: Adding Out of Source Build Example

This is an automated email from the ASF dual-hosted git repository.

github-bot pushed a commit to branch willsalmon/outOfSourecBuilddocs
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit 61dc4f251138ebdf52c581ac52534dd3ee8e4205
Author: William Salmon <wi...@codethink.co.uk>
AuthorDate: Mon Sep 10 15:46:46 2018 +0100

    Adding Out of Source Build Example
    
    For issue #695 in Gitlab.
---
 doc/examples/out-of-source-build/elements/base.bst |   5 +
 .../out-of-source-build/elements/base/alpine.bst   |  13 ++
 .../out-of-source-build/elements/sourceroot.bst    |  14 ++
 .../out-of-source-build/elements/subfolder.bst     |  14 ++
 .../files/OutOfSourceProject/CMakeLists.txt        |  14 ++
 .../files/OutOfSourceProject/README                |   5 +
 .../files/OutOfSourceProject/main/CMakeLists.txt   |  14 ++
 .../files/OutOfSourceProject/main/main.c           |  11 ++
 doc/examples/out-of-source-build/project.conf      |  13 ++
 doc/sessions/out-of-source-build.run               |  41 +++++
 doc/source/examples/out-of-source-build.rst        | 173 +++++++++++++++++++++
 .../out-of-source-build-build-main.html            |  99 ++++++++++++
 .../out-of-source-build-build-subfolder.html       |  99 ++++++++++++
 .../sessions-stored/out-of-source-build-build.html | 109 +++++++++++++
 .../out-of-source-build-shell-main.html            |  22 +++
 .../out-of-source-build-shell-subfolder.html       |  22 +++
 .../sessions-stored/out-of-source-build-shell.html |  22 +++
 .../out-of-source-build-show-variables.html        |  64 ++++++++
 doc/source/using_examples.rst                      |   1 +
 tests/examples/out-of-source.py                    |  78 ++++++++++
 20 files changed, 833 insertions(+)

diff --git a/doc/examples/out-of-source-build/elements/base.bst b/doc/examples/out-of-source-build/elements/base.bst
new file mode 100644
index 0000000..1b85a9e
--- /dev/null
+++ b/doc/examples/out-of-source-build/elements/base.bst
@@ -0,0 +1,5 @@
+kind: stack
+description: Base stack
+
+depends:
+- base/alpine.bst
diff --git a/doc/examples/out-of-source-build/elements/base/alpine.bst b/doc/examples/out-of-source-build/elements/base/alpine.bst
new file mode 100644
index 0000000..cf85df5
--- /dev/null
+++ b/doc/examples/out-of-source-build/elements/base/alpine.bst
@@ -0,0 +1,13 @@
+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
diff --git a/doc/examples/out-of-source-build/elements/sourceroot.bst b/doc/examples/out-of-source-build/elements/sourceroot.bst
new file mode 100644
index 0000000..aadcf09
--- /dev/null
+++ b/doc/examples/out-of-source-build/elements/sourceroot.bst
@@ -0,0 +1,14 @@
+depends:
+- base.bst
+description: |2
+
+  Hello world example from cmake
+kind: cmake
+sources:
+- kind: local
+  path: files/OutOfSourceProject
+  directory: Source
+variables:
+  command-subdir: build
+  conf-root: "%{build-root}/Source/"
+
diff --git a/doc/examples/out-of-source-build/elements/subfolder.bst b/doc/examples/out-of-source-build/elements/subfolder.bst
new file mode 100644
index 0000000..d2e241f
--- /dev/null
+++ b/doc/examples/out-of-source-build/elements/subfolder.bst
@@ -0,0 +1,14 @@
+depends:
+- base.bst
+description: |2
+
+  Hello world example from cmake
+kind: cmake
+sources:
+- kind: local
+  path: files/OutOfSourceProject
+  directory: Source
+variables:
+  command-subdir: build
+  conf-root: "%{build-root}/Source/main"
+
diff --git a/doc/examples/out-of-source-build/files/OutOfSourceProject/CMakeLists.txt b/doc/examples/out-of-source-build/files/OutOfSourceProject/CMakeLists.txt
new file mode 100644
index 0000000..287c783
--- /dev/null
+++ b/doc/examples/out-of-source-build/files/OutOfSourceProject/CMakeLists.txt
@@ -0,0 +1,14 @@
+
+# Set the minimum version of CMake that can be used
+# To find the cmake version run
+# $ cmake --version
+cmake_minimum_required(VERSION 2.8)
+
+# Set the project name
+project (hello_main C)
+
+# Set something so that we can see if main.c was compiled from this cmake
+# projcet
+set(CMAKE_C_FLAGS "-DFULL_PROJECT")
+
+add_subdirectory(main)
diff --git a/doc/examples/out-of-source-build/files/OutOfSourceProject/README b/doc/examples/out-of-source-build/files/OutOfSourceProject/README
new file mode 100644
index 0000000..4948937
--- /dev/null
+++ b/doc/examples/out-of-source-build/files/OutOfSourceProject/README
@@ -0,0 +1,5 @@
+This is a simple example project for using buildstream to build software that is
+located in different parts of it sources
+
+The source code will produce different code depending on which directory you
+specify to cmake
diff --git a/doc/examples/out-of-source-build/files/OutOfSourceProject/main/CMakeLists.txt b/doc/examples/out-of-source-build/files/OutOfSourceProject/main/CMakeLists.txt
new file mode 100644
index 0000000..4176932
--- /dev/null
+++ b/doc/examples/out-of-source-build/files/OutOfSourceProject/main/CMakeLists.txt
@@ -0,0 +1,14 @@
+
+# Set the minimum version of CMake that can be used
+# To find the cmake version run
+# $ cmake --version
+cmake_minimum_required(VERSION 2.8)
+
+# Set the project name
+project (hello_buildstreams C)
+
+# Add an executable
+add_executable(hello_buildstream main.c)
+
+
+install(TARGETS hello_buildstream DESTINATION /bin) 
diff --git a/doc/examples/out-of-source-build/files/OutOfSourceProject/main/main.c b/doc/examples/out-of-source-build/files/OutOfSourceProject/main/main.c
new file mode 100644
index 0000000..a114945
--- /dev/null
+++ b/doc/examples/out-of-source-build/files/OutOfSourceProject/main/main.c
@@ -0,0 +1,11 @@
+#include <stdio.h>
+int main()
+{
+   // printf() displays the string inside quotation
+#ifdef FULL_PROJECT
+   printf("Hello, World! Built from the source root.\n");
+#else
+   printf("Hello, World! Built from a subdirectory of the source.\n");
+#endif   
+   return 0;
+}
diff --git a/doc/examples/out-of-source-build/project.conf b/doc/examples/out-of-source-build/project.conf
new file mode 100644
index 0000000..047ab7f
--- /dev/null
+++ b/doc/examples/out-of-source-build/project.conf
@@ -0,0 +1,13 @@
+# Unique project name
+name: cmake-out-of-source-build 
+
+# Required BuildStream format version
+format-version: 9
+
+# Subdirectory where elements are stored
+element-path: elements
+
+# Define some aliases for the tarballs we download
+aliases:
+  alpine: https://gnome7.codethink.co.uk/tarballs/
+  gnu: https://ftp.gnu.org/gnu/automake/
diff --git a/doc/sessions/out-of-source-build.run b/doc/sessions/out-of-source-build.run
new file mode 100644
index 0000000..31b7b17
--- /dev/null
+++ b/doc/sessions/out-of-source-build.run
@@ -0,0 +1,41 @@
+
+commands:
+# This section is for the hello.bst element
+# Make it fetch first
+- directory: ../examples/out-of-source-build
+  command: fetch sourceroot.bst
+
+# Capture a `bst show` of the variables
+- directory: ../examples/out-of-source-build
+  output: ../source/sessions/out-of-source-build-show-variables.html
+  command: show --deps none --format "%{vars}" sourceroot.bst
+
+# Capture a `bst build`
+- directory: ../examples/out-of-source-build
+  output: ../source/sessions/out-of-source-build-build.html
+  command: build sourceroot.bst
+
+# Capture a shell output
+- directory: ../examples/out-of-source-build
+  output: ../source/sessions/out-of-source-build-shell-ls.html
+  command: shell sourceroot.bst --build --  ls .. 
+
+# Capture a shell output
+- directory: ../examples/out-of-source-build
+  output: ../source/sessions/out-of-source-build-shell.html
+  command: shell sourceroot.bst --  hello_buildstream 
+
+# This section if for the hello_main.bst element
+# Make it fetch first
+- directory: ../examples/out-of-source-build
+  command: fetch subfolder.bst
+
+# Capture a `bst build`
+- directory: ../examples/out-of-source-build
+  output: ../source/sessions/out-of-source-build-build-subfolder.html
+  command: build subfolder.bst
+
+# Capture a shell output
+- directory: ../examples/out-of-source-build
+  output: ../source/sessions/out-of-source-build-shell-subfolder.html
+  command: shell subfolder.bst --  hello_buildstream 
diff --git a/doc/source/examples/out-of-source-build.rst b/doc/source/examples/out-of-source-build.rst
new file mode 100644
index 0000000..b857339
--- /dev/null
+++ b/doc/source/examples/out-of-source-build.rst
@@ -0,0 +1,173 @@
+
+.. _examples_out-of-source-build.rst:
+
+Building out of source
+======================
+
+Intro
+-----
+
+This example aims to:
+
+ * Give a basic overview of how out of source builds work. This is done by 
+   collecting the relevant bits of information spread across different sections
+   of the documentation that tend to group information by element rather than
+   task.
+ * Give Examples of how to use out of source builds.
+   
+Buildstream aims to make out of source builds easy and consistent across as
+many build systems as possible. However it should be noted that not all build
+systems support `out of source builds`.
+
+Key Variables
+-------------
+
+Out of source builds are configured by setting:
+ 
+ * ``directory`` of the source, this sets the source to extract to a folder in
+   the build root.
+ * ``command-subdir`` variable, sets the directory were the build commands
+   will be run.
+ * ``conf-root`` variable, tells the configuration tool were to find the root of
+   the source code.
+   
+``conf-root`` is given to the configuration tool which is run in
+``command-subdir``. It can either be given as a relative path from 
+``command-subdir`` to the location of the source code. Or as an absolute
+location.
+
+By setting ``conf-root`` as a absolute path we can change ``command-subdir``
+with out having to change ``conf-root``.
+
+If a absolute path is given it must be from the root of the sandbox.
+To specify a absolute path from the root of the build-root the build-root
+variable can be used eg. ``conf-root`` can be set to ``"%{build-root}/Source"``
+to specify the ``Source`` folder in the root of the build-root.
+
+These variables can be use for many of the buildstream build element kinds.
+Indeed converting to out of source builds should be as simple as adding these
+variables to the individual bst files and in some circumstance most of the
+variables could be set at a project level.
+
+ 
+Examples
+--------
+
+The out of source examples can be found in the buildstream source code in 
+``doc/examples/out-of-source`` folder in the buildstream source. The two cmake
+elements we will use as examples are `sourceroot.bst` and `subfolder.bst`.
+
+It is very simple to create a build element that loads a source in to the
+`build-root` and then uses the standard build tools to build the project in the
+same folder. Buildstream has lots of build element plugs so that a new element
+may only need to set its `kind` to the relevant build system and then define a
+source, the `sourceroot.bst` example element takes a cmake exmaple and expands
+it to a out of source build.
+
+An alternative build elements might build in a sub folder of the source. The
+`hello.bst` element in the `autotools` example dose this. And a out of source
+version is given in the `subfolder.bst` element of the out of source example
+project.
+
+
+Build project defined in source root
+------------------------------------
+
+This example points cmake at the root of the source.
+
+In this example, the CMakeLis.txt in the root folder of the source
+causes the helloworld program to state that it was build from the root of the 
+source project when called.
+
+To make the software build in a folder outside of the source code we set the
+source to be in a sub folder of the build-root folder rather than in its root,
+in our case this folder will be called ``source``.
+
+The build tools are then set to run a separate folder in the build-root folder,
+this will be called ``build``. We must then tell the build tools were to
+find the source code, this is done with the ``conf-root`` variable.
+
+This is done by:
+ 
+ * Setting the sources ``directory`` property to ``Source``
+ * Setting the element variable ``command-subdir`` to ``build``
+ * Setting the element variable ``conf-root`` to ``"%{build-root}/Source"``
+
+
+``sourceroot.bst``
+~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-build/elements/sourceroot.bst
+   :language: yaml
+
+We can then use the ``bst show`` command to see how variable like ``conf-root``
+are expanded.
+
+.. raw:: html
+   :file: ../sessions/out-of-source-build-show-variables.html
+
+
+Using a workspace or a shell with `--build` can be used to see the folder
+structure that gets created. When bst shell is launched it runs in the
+``command-subdir`` directory. If ``ls ..`` is run we can see that the build-root
+now contains the ``build`` folder and the ``Source`` folder.
+
+.. raw:: html
+   :file: ../sessions//out-of-source-build-shell-ls.html
+
+
+
+Build project defined in source subdirectory
+--------------------------------------------
+
+This example points cmake at he `main` directory inside the source.
+
+In this example, the CMakeLis.txt in the folder main in the root of the
+source causes the helloworld program to state that it was build from a subfolder
+of the source project when called. 
+
+To make the software build in a folder outside of the source code we set the
+source to be in a sub folder of the build-root folder rather than in its root,
+in our case this folder will be called ``source``.
+
+The build tools are then set to run a separate folder in the build-root folder,
+this will be called ``build``. We must then tell the build tools were to
+find the source code, this is done with the ``conf-root`` variable.
+Unlike the previous example we need ``conf-root`` to point the sub directory of
+the source project rather than the root.
+
+
+
+This is done by:
+ 
+ * Setting the sources ``directory`` property to ``Source``
+ * Setting the element variable ``command-subdir`` to ``build``
+ * Setting the element variable ``conf-root`` to
+   ``"%{build-root}/Source/main"``
+
+``subfolder.bst``
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-build/elements/subfolder.bst
+   :language: yaml
+
+
+Run the hello world program
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We can see the output of the two different binaries created from the same
+source by invoking the shell of the respective elements with the new programs
+name.
+
+When the binary from the build that included the file that defined the extra build
+flag ``FULL_PROJECT`` is run, we get the following output:
+
+.. raw:: html
+   :file: ../sessions/out-of-source-build-shell.html
+
+When the binary from the build that pointed to the CMakeList.txt that
+just adds the source without defining any extra build flags is run, we get the
+following output:
+
+.. raw:: html
+   :file: ../sessions/out-of-source-build-shell-subfolder.html
diff --git a/doc/source/sessions-stored/out-of-source-build-build-main.html b/doc/source/sessions-stored/out-of-source-build-build-main.html
new file mode 100644
index 0000000..2ac3763
--- /dev/null
+++ b/doc/source/sessions-stored/out-of-source-build-build-main.html
@@ -0,0 +1,99 @@
+<!--
+    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">~/out-of-source-build</span>$ bst build hello_main.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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+
+<span style="color:#C4A000"><span style="">BuildStream Version 1.3.0+867.gb1ab7d77.dirty
+</span></span><span style="color:#06989A"><span style="opacity:0.5">  Session Start: </span></span><span style="color:#C4A000">Friday, 09-11-2018 at 16:03:46</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Project:       </span></span><span style="color:#C4A000">cmake-out-of-source-build (/home/user/projects/buildstream/buildstream/doc/examples/out-of-source-build)</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Targets:       </span></span><span style="color:#C4A000">hello_main.bst</span>
+
+<span style="color:#C4A000"><span style="">User Configuration
+</span></span><span style="color:#06989A"><span style="opacity:0.5">  Configuration File:      </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/buildstream.conf</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Log Files:               </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/logs</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Source Mirrors:          </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/sources</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Build Area:              </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/build</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Artifact Cache:          </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/artifacts</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Strict Build Plan:       </span></span><span style="color:#C4A000">Yes</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Fetch Tasks:     </span></span><span style="color:#C4A000">10</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Build Tasks:     </span></span><span style="color:#C4A000">4</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Push Tasks:      </span></span><span style="color:#C4A000">4</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Network Retries: </span></span><span style="color:#C4A000">2</span>
+
+<span style="color:#C4A000"><span style="">Pipeline
+</span></span><span style="color:#75507B">      cached</span> <span style="color:#C4A000">9afe69d645f0bee106749bc2101aae16ef437bb51e1b343ef1f16f04f0572efb</span> <span style="color:#3465A4"><span style="">base/alpine.bst</span></span> 
+<span style="color:#75507B">      cached</span> <span style="color:#C4A000">19f7c50c7a1db9ae4babe9d1f34f4cdbbf2428827d48673861fd1452d6c7e16b</span> <span style="color:#3465A4"><span style="">base.bst</span></span> 
+<span style="color:#4E9A06">   buildable</span> <span style="color:#C4A000">4ab8120b3cfb80e993b1efe8af5fa5d49bcba5aaf67e1ee4f5ede735a6cfcf4e</span> <span style="color:#3465A4"><span style="">hello_main.bst</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:#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">4ab8120b</span><span style="color:#06989A"><span style="opacit [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    cmake -B_builddir -H"/buildstream/cmake-out-of-source-build/hello_main.bst/Source/src/main" -G"Unix Makefiles" -DCMAKE_INSTALL_PREFIX:PATH="/usr" \
+    -DCMAKE_INSTALL_LIBDIR=lib</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    cmake --build _builddir -- ${JOBS}</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    env DESTDIR="/buildstream-install" cmake --build _builddir --target install</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    cd "/buildstream-install" && find -type f \
+      '(' -perm -111 -o -name '*.so*' \
+          -o -name '*.cmxs' -o -name '*.node' ')' \
+      -exec sh -ec \
+      'read -n4 hdr <"$1" # check for elf header
+       case "$1" in
+         /buildstream-install/usr/lib/debug/*)
+           exit 0
+           ;;
+       esac
+       if [ "$hdr" != "$(printf \\x7fELF)" ]; then
+           exit 0
+       fi
+       debugfile="/buildstream-install/usr/lib/debug/$1"
+       mkdir -p "$(dirname "$debugfile")"
+       objcopy --only-keep-debug --compress-debug-sections "$1" "$debugfile"
+       chmod 644 "$debugfile"
+       strip --remove-section=.comment --remove-section=.note --strip-unneeded "$1"
+       objcopy --add-gnu-debuglink "$debugfile" "$1"' - {} ';'</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">01</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">01</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  [...]
+
+<span style="color:#C4A000"><span style="">Pipeline Summary
+</span></span><span style="color:#06989A"><span style="opacity:0.5">  Total:       </span></span><span style="color:#C4A000">3</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Session:     </span></span><span style="color:#C4A000">1</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Fetch Queue: </span></span><span style="color:#C4A000">processed </span><span style="color:#4E9A06">0</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">skipped </span><span style="color:#C4A000">1</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">failed </span><span style="color:#CC0000"><span style="opacity:0.5">0</span></span> 
+<span style="color:#06989A"><span style="opacity:0.5">  Build Queue: </span></span><span style="color:#C4A000">processed </span><span style="color:#4E9A06">1</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">skipped </span><span style="color:#C4A000">0</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">failed </span><span style="color:#CC0000"><span style="opacity:0.5">0</span></span>
+</pre></div>
diff --git a/doc/source/sessions-stored/out-of-source-build-build-subfolder.html b/doc/source/sessions-stored/out-of-source-build-build-subfolder.html
new file mode 100644
index 0000000..0f5a61d
--- /dev/null
+++ b/doc/source/sessions-stored/out-of-source-build-build-subfolder.html
@@ -0,0 +1,99 @@
+<!--
+    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">~/out-of-source-build</span>$ bst build subfolder.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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+
+<span style="color:#C4A000"><span style="">BuildStream Version 1.3.0+890.g20bbe4b5
+</span></span><span style="color:#06989A"><span style="opacity:0.5">  Session Start: </span></span><span style="color:#C4A000">Monday, 19-11-2018 at 15:38:33</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Project:       </span></span><span style="color:#C4A000">cmake-out-of-source-build (/home/user/projects/buildstream/buildstream/doc/examples/out-of-source-build)</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Targets:       </span></span><span style="color:#C4A000">subfolder.bst</span>
+
+<span style="color:#C4A000"><span style="">User Configuration
+</span></span><span style="color:#06989A"><span style="opacity:0.5">  Configuration File:      </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/buildstream.conf</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Log Files:               </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/logs</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Source Mirrors:          </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/sources</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Build Area:              </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/build</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Artifact Cache:          </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/artifacts</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Strict Build Plan:       </span></span><span style="color:#C4A000">Yes</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Fetch Tasks:     </span></span><span style="color:#C4A000">10</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Build Tasks:     </span></span><span style="color:#C4A000">4</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Push Tasks:      </span></span><span style="color:#C4A000">4</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Network Retries: </span></span><span style="color:#C4A000">2</span>
+
+<span style="color:#C4A000"><span style="">Pipeline
+</span></span><span style="color:#75507B">      cached</span> <span style="color:#C4A000">9afe69d645f0bee106749bc2101aae16ef437bb51e1b343ef1f16f04f0572efb</span> <span style="color:#3465A4"><span style="">base/alpine.bst</span></span> 
+<span style="color:#75507B">      cached</span> <span style="color:#C4A000">19f7c50c7a1db9ae4babe9d1f34f4cdbbf2428827d48673861fd1452d6c7e16b</span> <span style="color:#3465A4"><span style="">base.bst</span></span> 
+<span style="color:#4E9A06">   buildable</span> <span style="color:#C4A000">150c4a9e5b1a329684dafeecd20cec5e792459f252dda600cd11d01120047e34</span> <span style="color:#3465A4"><span style="">subfolder.bst</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:#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">150c4a9e</span><span style="color:#06989A"><span style="opacit [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    cmake -B_builddir -H"/buildstream/cmake-out-of-source-build/subfolder.bst/Source/src/main" -G"Unix Makefiles" -DCMAKE_INSTALL_PREFIX:PATH="/usr" \
+    -DCMAKE_INSTALL_LIBDIR=lib</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    cmake --build _builddir -- ${JOBS}</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    env DESTDIR="/buildstream-install" cmake --build _builddir --target install</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    cd "/buildstream-install" && find -type f \
+      '(' -perm -111 -o -name '*.so*' \
+          -o -name '*.cmxs' -o -name '*.node' ')' \
+      -exec sh -ec \
+      'read -n4 hdr <"$1" # check for elf header
+       case "$1" in
+         /buildstream-install/usr/lib/debug/*)
+           exit 0
+           ;;
+       esac
+       if [ "$hdr" != "$(printf \\x7fELF)" ]; then
+           exit 0
+       fi
+       debugfile="/buildstream-install/usr/lib/debug/$1"
+       mkdir -p "$(dirname "$debugfile")"
+       objcopy --only-keep-debug --compress-debug-sections "$1" "$debugfile"
+       chmod 644 "$debugfile"
+       strip --remove-section=.comment --remove-section=.note --strip-unneeded "$1"
+       objcopy --add-gnu-debuglink "$debugfile" "$1"' - {} ';'</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">01</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">01</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  [...]
+
+<span style="color:#C4A000"><span style="">Pipeline Summary
+</span></span><span style="color:#06989A"><span style="opacity:0.5">  Total:       </span></span><span style="color:#C4A000">3</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Session:     </span></span><span style="color:#C4A000">1</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Fetch Queue: </span></span><span style="color:#C4A000">processed </span><span style="color:#4E9A06">0</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">skipped </span><span style="color:#C4A000">1</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">failed </span><span style="color:#CC0000"><span style="opacity:0.5">0</span></span> 
+<span style="color:#06989A"><span style="opacity:0.5">  Build Queue: </span></span><span style="color:#C4A000">processed </span><span style="color:#4E9A06">1</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">skipped </span><span style="color:#C4A000">0</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">failed </span><span style="color:#CC0000"><span style="opacity:0.5">0</span></span>
+</pre></div>
diff --git a/doc/source/sessions-stored/out-of-source-build-build.html b/doc/source/sessions-stored/out-of-source-build-build.html
new file mode 100644
index 0000000..680acaf
--- /dev/null
+++ b/doc/source/sessions-stored/out-of-source-build-build.html
@@ -0,0 +1,109 @@
+<!--
+    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">~/out-of-source-build</span>$ bst build sourceroot.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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+
+<span style="color:#C4A000"><span style="">BuildStream Version 1.3.0+890.g20bbe4b5
+</span></span><span style="color:#06989A"><span style="opacity:0.5">  Session Start: </span></span><span style="color:#C4A000">Monday, 19-11-2018 at 15:38:12</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Project:       </span></span><span style="color:#C4A000">cmake-out-of-source-build (/home/user/projects/buildstream/buildstream/doc/examples/out-of-source-build)</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Targets:       </span></span><span style="color:#C4A000">sourceroot.bst</span>
+
+<span style="color:#C4A000"><span style="">User Configuration
+</span></span><span style="color:#06989A"><span style="opacity:0.5">  Configuration File:      </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/buildstream.conf</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Log Files:               </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/logs</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Source Mirrors:          </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/sources</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Build Area:              </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/build</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Artifact Cache:          </span></span><span style="color:#C4A000">/home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/artifacts</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Strict Build Plan:       </span></span><span style="color:#C4A000">Yes</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Fetch Tasks:     </span></span><span style="color:#C4A000">10</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Build Tasks:     </span></span><span style="color:#C4A000">4</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Push Tasks:      </span></span><span style="color:#C4A000">4</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Maximum Network Retries: </span></span><span style="color:#C4A000">2</span>
+
+<span style="color:#C4A000"><span style="">Pipeline
+</span></span><span style="color:#4E9A06">   buildable</span> <span style="color:#C4A000">9afe69d645f0bee106749bc2101aae16ef437bb51e1b343ef1f16f04f0572efb</span> <span style="color:#3465A4"><span style="">base/alpine.bst</span></span> 
+<span style="color:#3465A4">     waiting</span> <span style="color:#C4A000">19f7c50c7a1db9ae4babe9d1f34f4cdbbf2428827d48673861fd1452d6c7e16b</span> <span style="color:#3465A4"><span style="">base.bst</span></span> 
+<span style="color:#3465A4">     waiting</span> <span style="color:#C4A000">f7b50d8b77c24a53e09abb6fb6ab2b6be6328cf5c08e33dcd26f2ffdab3eef89</span> <span style="color:#3465A4"><span style="">sourceroot.bst</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:#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">9afe69d6</span><span style="color:#06989A"><span style="opacit [...]
+<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">9afe69d6</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">09</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">9afe69d6</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">9afe69d6</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">03</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">9afe69d6</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">16</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">9afe69d6</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">19f7c50c</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">19f7c50c</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">19f7c50c</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">19f7c50c</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    cmake -B_builddir -H"/buildstream/cmake-out-of-source-build/sourceroot.bst/Source/src" -G"Unix Makefiles" -DCMAKE_INSTALL_PREFIX:PATH="/usr" \
+    -DCMAKE_INSTALL_LIBDIR=lib</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    cmake --build _builddir -- ${JOBS}</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    env DESTDIR="/buildstream-install" cmake --build _builddir --target install</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    cd "/buildstream-install" && find -type f \
+      '(' -perm -111 -o -name '*.so*' \
+          -o -name '*.cmxs' -o -name '*.node' ')' \
+      -exec sh -ec \
+      'read -n4 hdr <"$1" # check for elf header
+       case "$1" in
+         /buildstream-install/usr/lib/debug/*)
+           exit 0
+           ;;
+       esac
+       if [ "$hdr" != "$(printf \\x7fELF)" ]; then
+           exit 0
+       fi
+       debugfile="/buildstream-install/usr/lib/debug/$1"
+       mkdir -p "$(dirname "$debugfile")"
+       objcopy --only-keep-debug --compress-debug-sections "$1" "$debugfile"
+       chmod 644 "$debugfile"
+       strip --remove-section=.comment --remove-section=.note --strip-unneeded "$1"
+       objcopy --add-gnu-debuglink "$debugfile" "$1"' - {} ';'</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:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">01</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">19</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  [...]
+
+<span style="color:#C4A000"><span style="">Pipeline Summary
+</span></span><span style="color:#06989A"><span style="opacity:0.5">  Total:       </span></span><span style="color:#C4A000">3</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Session:     </span></span><span style="color:#C4A000">3</span>
+<span style="color:#06989A"><span style="opacity:0.5">  Fetch Queue: </span></span><span style="color:#C4A000">processed </span><span style="color:#4E9A06">0</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">skipped </span><span style="color:#C4A000">3</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">failed </span><span style="color:#CC0000"><span style="opacity:0.5">0</span></span> 
+<span style="color:#06989A"><span style="opacity:0.5">  Build Queue: </span></span><span style="color:#C4A000">processed </span><span style="color:#4E9A06">3</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">skipped </span><span style="color:#C4A000">0</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">failed </span><span style="color:#CC0000"><span style="opacity:0.5">0</span></span>
+</pre></div>
diff --git a/doc/source/sessions-stored/out-of-source-build-shell-main.html b/doc/source/sessions-stored/out-of-source-build-shell-main.html
new file mode 100644
index 0000000..cbd3862
--- /dev/null
+++ b/doc/source/sessions-stored/out-of-source-build-shell-main.html
@@ -0,0 +1,22 @@
+<!--
+    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">~/out-of-source-build</span>$ bst shell hello_main.bst --  hello_buildstream
+
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">4ab8120b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    hello_buildstream</span>
+
+Hello, World!
+</pre></div>
diff --git a/doc/source/sessions-stored/out-of-source-build-shell-subfolder.html b/doc/source/sessions-stored/out-of-source-build-shell-subfolder.html
new file mode 100644
index 0000000..6cf0592
--- /dev/null
+++ b/doc/source/sessions-stored/out-of-source-build-shell-subfolder.html
@@ -0,0 +1,22 @@
+<!--
+    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">~/out-of-source-build</span>$ bst shell subfolder.bst --  hello_buildstream
+
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">150c4a9e</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    hello_buildstream</span>
+
+Hello, World! Built from a subdirectory of the source.
+</pre></div>
diff --git a/doc/source/sessions-stored/out-of-source-build-shell.html b/doc/source/sessions-stored/out-of-source-build-shell.html
new file mode 100644
index 0000000..9798a49
--- /dev/null
+++ b/doc/source/sessions-stored/out-of-source-build-shell.html
@@ -0,0 +1,22 @@
+<!--
+    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">~/out-of-source-build</span>$ bst shell sourceroot.bst --  hello_buildstream
+
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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:#C4A000">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+<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">f7b50d8b</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5">    hello_buildstream</span>
+
+Hello, World! Built from the source root.
+</pre></div>
diff --git a/doc/source/sessions-stored/out-of-source-build-show-variables.html b/doc/source/sessions-stored/out-of-source-build-show-variables.html
new file mode 100644
index 0000000..a487924
--- /dev/null
+++ b/doc/source/sessions-stored/out-of-source-build-show-variables.html
@@ -0,0 +1,64 @@
+<!--
+    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">~/out-of-source-build</span>$ bst show --deps none --format "%{vars}" sourceroot.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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+<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  [...]
+bindir: /usr/bin
+build-dir: _builddir
+build-root: /buildstream/cmake-out-of-source-build/sourceroot.bst
+cmake: "cmake -B_builddir -H\"/buildstream/cmake-out-of-source-build/sourceroot.bst/Source/src\"\
+  \ -G\"Unix Makefiles\" -DCMAKE_INSTALL_PREFIX:PATH=\"/usr\" \\\n-DCMAKE_INSTALL_LIBDIR=lib\
+  \   "
+cmake-args: "-DCMAKE_INSTALL_PREFIX:PATH=\"/usr\" \\\n-DCMAKE_INSTALL_LIBDIR=lib"
+cmake-extra: ''
+cmake-global: ''
+cmake-local: ''
+command-subdir: build
+conf-root: /buildstream/cmake-out-of-source-build/sourceroot.bst/Source/src
+datadir: /usr/share
+debugdir: /usr/lib/debug
+docdir: /usr/share/doc
+element-name: sourceroot.bst
+exec_prefix: /usr
+fix-pyc-timestamps: "find \"/buildstream-install\" -name '*.pyc' -exec \\\n  dd if=/dev/zero\
+  \ of={} bs=1 count=4 seek=4 conv=notrunc ';'"
+generator: Unix Makefiles
+includedir: /usr/include
+infodir: /usr/share/info
+install-root: /buildstream-install
+lib: lib
+libdir: /usr/lib
+libexecdir: /usr/libexec
+localstatedir: /var
+make: cmake --build _builddir -- ${JOBS}
+make-install: env DESTDIR="/buildstream-install" cmake --build _builddir --target
+  install
+mandir: /usr/share/man
+max-jobs: '4'
+objcopy-extract-args: --only-keep-debug --compress-debug-sections
+objcopy-link-args: --add-gnu-debuglink
+prefix: /usr
+project-name: cmake-out-of-source-build
+sbindir: /usr/sbin
+sharedstatedir: /usr/com
+strip-args: --remove-section=.comment --remove-section=.note --strip-unneeded
+strip-binaries: "cd \"/buildstream-install\" && find -type f \\\n  '(' -perm -111\
+  \ -o -name '*.so*' \\\n      -o -name '*.cmxs' -o -name '*.node' ')' \\\n  -exec\
+  \ sh -ec \\\n  'read -n4 hdr <\"$1\" # check for elf header\n   case \"$1\" in\n\
+  \     /buildstream-install/usr/lib/debug/*)\n       exit 0\n       ;;\n   esac\n\
+  \   if [ \"$hdr\" != \"$(printf \\\\x7fELF)\" ]; then\n       exit 0\n   fi\n  \
+  \ debugfile=\"/buildstream-install/usr/lib/debug/$1\"\n   mkdir -p \"$(dirname \"\
+  $debugfile\")\"\n   objcopy --only-keep-debug --compress-debug-sections \"$1\" \"\
+  $debugfile\"\n   chmod 644 \"$debugfile\"\n   strip --remove-section=.comment --remove-section=.note\
+  \ --strip-unneeded \"$1\"\n   objcopy --add-gnu-debuglink \"$debugfile\" \"$1\"\
+  ' - {} ';'"
+sysconfdir: /etc
+
+</pre></div>
diff --git a/doc/source/using_examples.rst b/doc/source/using_examples.rst
index 18b15c7..6cbca2f 100644
--- a/doc/source/using_examples.rst
+++ b/doc/source/using_examples.rst
@@ -15,3 +15,4 @@ maintained and work as expected.
    examples/flatpak-autotools
    examples/tar-mirror
    examples/git-mirror
+   examples/out-of-source-build
diff --git a/tests/examples/out-of-source.py b/tests/examples/out-of-source.py
new file mode 100644
index 0000000..6f68421
--- /dev/null
+++ b/tests/examples/out-of-source.py
@@ -0,0 +1,78 @@
+import os
+import pytest
+
+from tests.testutils import cli_integration as cli
+from tests.testutils.integration import assert_contains
+from tests.testutils.site import HAVE_BWRAP, IS_LINUX
+
+pytestmark = pytest.mark.integration
+
+DATA_DIR = os.path.join(
+    os.path.dirname(os.path.realpath(__file__)), '..', '..', 'doc', 'examples', 'out-of-source-build'
+)
+
+
+# Tests a build of the autotools amhello project on a alpine-linux base runtime
+@pytest.mark.skipif(not IS_LINUX or not HAVE_BWRAP, reason='Only available on linux with bubblewrap')
+@pytest.mark.datafiles(DATA_DIR)
+def test_project_build_projcet(cli, tmpdir, datafiles):
+    project = os.path.join(datafiles.dirname, datafiles.basename)
+    checkout = os.path.join(cli.directory, 'checkout')
+
+    # Check that the project can be built correctly.
+    result = cli.run(project=project, args=['build', 'sourceroot.bst'])
+    result.assert_success()
+
+    result = cli.run(project=project, args=['checkout', 'sourceroot.bst', checkout])
+    result.assert_success()
+
+    assert_contains(checkout, ['/usr', '/usr/lib', '/usr/bin',
+                               '/usr/share',
+                               '/bin/hello_buildstream'])
+
+
+# Tests a build of the autotools amhello project on a alpine-linux base runtime
+@pytest.mark.skipif(not IS_LINUX or not HAVE_BWRAP, reason='Only available on linux with bubblewrap')
+@pytest.mark.datafiles(DATA_DIR)
+def test_project_build_main(cli, tmpdir, datafiles):
+    project = os.path.join(datafiles.dirname, datafiles.basename)
+    checkout = os.path.join(cli.directory, 'checkout')
+
+    # Check that the project can be built correctly.
+    result = cli.run(project=project, args=['build', 'subfolder.bst'])
+    result.assert_success()
+
+    result = cli.run(project=project, args=['checkout', 'subfolder.bst', checkout])
+    result.assert_success()
+
+    assert_contains(checkout, ['/usr', '/usr/lib', '/usr/bin',
+                               '/usr/share',
+                               '/bin/hello_buildstream'])
+
+
+# Test running an executable built with autotools.
+@pytest.mark.skipif(not IS_LINUX or not HAVE_BWRAP, reason='Only available on linux with bubblewrap')
+@pytest.mark.datafiles(DATA_DIR)
+def test_run_project(cli, tmpdir, datafiles):
+    project = os.path.join(datafiles.dirname, datafiles.basename)
+
+    result = cli.run(project=project, args=['build', 'sourceroot.bst'])
+    result.assert_success()
+
+    result = cli.run(project=project, args=['shell', 'sourceroot.bst', 'hello_buildstream'])
+    result.assert_success()
+    assert result.output == 'Hello, World! Built from the source root.\n'
+
+
+# Test running an executable built with autotools.
+@pytest.mark.skipif(not IS_LINUX or not HAVE_BWRAP, reason='Only available on linux with bubblewrap')
+@pytest.mark.datafiles(DATA_DIR)
+def test_run_main(cli, tmpdir, datafiles):
+    project = os.path.join(datafiles.dirname, datafiles.basename)
+
+    result = cli.run(project=project, args=['build', 'subfolder.bst'])
+    result.assert_success()
+
+    result = cli.run(project=project, args=['shell', 'subfolder.bst', 'hello_buildstream'])
+    result.assert_success()
+    assert result.output == 'Hello, World! Built from a subdirectory of the source.\n'