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:19:48 UTC
[buildstream] branch phil/out-of-source-build-docs created (now
59826dd)
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a change to branch phil/out-of-source-build-docs
in repository https://gitbox.apache.org/repos/asf/buildstream.git.
at 59826dd Various recomended changes to the out of source build docs
This branch includes the following new commits:
new 20bbe4b Adding Out of Source Build Example
new 59826dd Various recomended changes to the out of source build docs
The 2 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/02: 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 phil/out-of-source-build-docs
in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 20bbe4b5e712886a26e9b09b8ebc703e5e088f68
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 ++
.../out-of-source-build/files/hello/README | 5 +
.../files/hello/src/CMakeLists.txt | 14 ++
.../files/hello/src/main/CMakeLists.txt | 14 ++
.../files/hello/src/main/main.c | 11 ++
doc/examples/out-of-source-build/project.conf | 13 ++
doc/sessions/out-of-source-build.run | 36 +++++
doc/source/examples/out-of-source-build.rst | 160 +++++++++++++++++++++
.../out-of-source-build-build-main.html | 99 +++++++++++++
.../sessions-stored/out-of-source-build-build.html | 109 ++++++++++++++
.../out-of-source-build-shell-main.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 ++++++++++
18 files changed, 694 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..66ba1fc
--- /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/hello
+ directory: Source
+variables:
+ command-subdir: build
+ conf-root: "%{build-root}/Source/src"
+
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..3d2247a
--- /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/hello
+ directory: Source
+variables:
+ command-subdir: build
+ conf-root: "%{build-root}/Source/src/main"
+
diff --git a/doc/examples/out-of-source-build/files/hello/README b/doc/examples/out-of-source-build/files/hello/README
new file mode 100644
index 0000000..4948937
--- /dev/null
+++ b/doc/examples/out-of-source-build/files/hello/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/hello/src/CMakeLists.txt b/doc/examples/out-of-source-build/files/hello/src/CMakeLists.txt
new file mode 100644
index 0000000..287c783
--- /dev/null
+++ b/doc/examples/out-of-source-build/files/hello/src/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/hello/src/main/CMakeLists.txt b/doc/examples/out-of-source-build/files/hello/src/main/CMakeLists.txt
new file mode 100644
index 0000000..4176932
--- /dev/null
+++ b/doc/examples/out-of-source-build/files/hello/src/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/hello/src/main/main.c b/doc/examples/out-of-source-build/files/hello/src/main/main.c
new file mode 100644
index 0000000..a114945
--- /dev/null
+++ b/doc/examples/out-of-source-build/files/hello/src/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..255bf56
--- /dev/null
+++ b/doc/sessions/out-of-source-build.run
@@ -0,0 +1,36 @@
+
+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.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..6979f4c
--- /dev/null
+++ b/doc/source/examples/out-of-source-build.rst
@@ -0,0 +1,160 @@
+
+.. _examples_out-of-source-build.rst:
+
+Building out of source
+======================
+
+Intro
+-----
+
+This example aims to show:
+
+ * Give a basic overview of how out of source builds can work tying together
+ bits of information spread across different sections of the docs 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 open in to a folder in the
+ build root.
+ * ``command-subdir`` variable, sets were the build 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 ether 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 src directory in the root of the source.
+
+In this example, the CMakeLis.txt in the src folder in the root 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/src"``
+
+
+File: 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
+
+Build project defined in source subdirectory
+--------------------------------------------
+
+This example points cmake at he src/main directory inside the source.
+
+In this example, the CMakeLis.txt in the folder src/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/src/main"``
+
+File: 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.html b/doc/source/sessions-stored/out-of-source-build-build.html
new file mode 100644
index 0000000..cbe56d2
--- /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 hello.bst
+
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span [...]
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="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:24</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.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:#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">a2f30de9ab527ec782552c9dc290aa48f6a753391df5c670b9d6c633007ab9f1</span> <span style="color:#3465A4"><span style="">hello.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">17</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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.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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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.html b/doc/source/sessions-stored/out-of-source-build-shell.html
new file mode 100644
index 0000000..db61dce
--- /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 hello.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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</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">a2f30de9</span><span style="color:#06989A"><span style="opacity:0.5">][</spa [...]
+
+<span style="opacity:0.5"> hello_buildstream</span>
+
+Hello, World! From the hole project..
+</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..7636937
--- /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}" hello.bst
+
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span [...]
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity: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/hello.bst
+cmake: "cmake -B_builddir -H\"/buildstream/cmake-out-of-source-build/hello.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/hello.bst/Source/src
+datadir: /usr/share
+debugdir: /usr/lib/debug
+docdir: /usr/share/doc
+element-name: hello.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..d89f8a0
--- /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 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, reason='Only available on linux')
+@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', '/usr/lib/debug',
+ '/bin/hello_buildstream'])
+
+
+# Tests a build of the autotools amhello project on a alpine-linux base runtime
+@pytest.mark.skipif(not IS_LINUX, reason='Only available on linux')
+@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', '/usr/lib/debug',
+ '/bin/hello_buildstream'])
+
+
+# Test running an executable built with autotools.
+@pytest.mark.skipif(not IS_LINUX, reason='Only available on linux')
+@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! From the whole project.\n'
+
+
+# Test running an executable built with autotools.
+@pytest.mark.skipif(not IS_LINUX, reason='Only available on linux')
+@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! From the `main` section of the project.\n'
[buildstream] 02/02: Various recomended changes to the out of
source build docs
Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch phil/out-of-source-build-docs
in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 59826ddc7ede815e091e179818bdcc1c2e95020f
Author: Phil Dawson <ph...@codethink.co.uk>
AuthorDate: Mon Nov 19 15:54:30 2018 +0000
Various recomended changes to the out of source build docs
I've also left some comments on the branch
---
doc/source/examples/out-of-source-build.rst | 61 ++++++++++++-----------------
1 file changed, 26 insertions(+), 35 deletions(-)
diff --git a/doc/source/examples/out-of-source-build.rst b/doc/source/examples/out-of-source-build.rst
index 6979f4c..5ce8680 100644
--- a/doc/source/examples/out-of-source-build.rst
+++ b/doc/source/examples/out-of-source-build.rst
@@ -7,60 +7,51 @@ Building out of source
Intro
-----
-This example aims to show:
+This example aims to:
- * Give a basic overview of how out of source builds can work tying together
- bits of information spread across different sections of the docs that tend to
+ * Give a basic overview of how out of source builds can perfomed, tying together
+ information spread across different sections of the documentaion that tends 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
+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 open in to a folder in the
+To understand how to perform out od source builds, you must be familier with the
+following element properties.
+
+ * ``directory``: Defines the path in the build sandbox at which the element's sources will be staged. This is set for each of the element's sources.
build root.
- * ``command-subdir`` variable, sets were the build 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 ether be given as a relative path from
-``command-subdir`` to the location of the source code. Or as an absolute
-location.
+ * ``command-subdir`` The working directory used for the element's configure, build and integration commands.
+ * ``conf-root`` The path to your build system's configurations file, e.g top level CMakeLists.txt for an element of cmake kind. This path is relative to the elements command-subdir unless is specified as an absolute path.
-By setting ``conf-root`` as a absolute path we can change ``command-subdir``
-with out having to change ``conf-root``.
+.. note:
-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.
+ It is recomended to specify conf-root as an absolute path to make
+ life easier if you decide to change command-subdir. Commonly one
+ would use a path such as "%{build-root}/Some/Path"
-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.
+For element kinds which support the above properties, configuring out of source
+builds should be as simple as setting them.
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
+The examples shown here 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.
+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
+pluggins so that a new build element may only need to set its `kind`
+and then define a source, the `sourceroot.bst` example element takes the
+cmake exmaple from the 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
@@ -73,7 +64,7 @@ Build project defined in source root
This example points cmake at the src directory in the root of the source.
-In this example, the CMakeLis.txt in the src folder in the root of the source
+In this example, the CMakeLists.txt in the src folder in the root of the source
causes the helloworld program to state that it was build from the root of the
source project when called.
@@ -109,7 +100,7 @@ Build project defined in source subdirectory
This example points cmake at he src/main directory inside the source.
-In this example, the CMakeLis.txt in the folder src/main in the root of the
+In this example, the CMakeLists.txt in the folder src/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.