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:58 UTC
[buildstream] branch willsalmon/outOfSourecBuilddocs created (now
61dc4f2)
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a change to branch willsalmon/outOfSourecBuilddocs
in repository https://gitbox.apache.org/repos/asf/buildstream.git.
at 61dc4f2 Adding Out of Source Build Example
This branch includes the following new commits:
new 61dc4f2 Adding Out of Source Build Example
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[buildstream] 01/01: Adding Out of Source Build Example
Posted by gi...@apache.org.
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'