You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildstream.apache.org by ro...@apache.org on 2020/12/29 13:29:09 UTC
[buildstream] 04/09: Adding Out of Source Build Examples
This is an automated email from the ASF dual-hosted git repository.
root pushed a commit to branch willsalmon/simpleOutSource
in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 35c038704fe125b02686cc8f2a930723cf9b3df1
Author: William Salmon <wi...@codethink.co.uk>
AuthorDate: Mon Sep 10 15:46:46 2018 +0100
Adding Out of Source Build Examples
Three examples covering out of source builds for:
* basic autotools
* basic cmake
* autotools from a folder inside the source folder
This is also the first cmake example.
For issue #512 in Gitlab.
---
doc/examples/cmake/elements/base.bst | 5 +
doc/examples/cmake/elements/base/alpine.bst | 13 ++
doc/examples/cmake/elements/hello.bst | 14 ++
doc/examples/cmake/files/hello/CMakeLists.txt | 14 ++
doc/examples/cmake/files/hello/main.c | 7 +
doc/examples/cmake/project.conf | 13 ++
.../elements/base.bst | 5 +
.../elements/base/alpine.bst | 13 ++
.../elements/hello.bst | 15 +++
.../project.conf | 13 ++
.../elements/base.bst | 5 +
.../elements/base/alpine.bst | 13 ++
.../elements/hello.bst | 14 ++
.../files/hello/Makefile.am | 1 +
.../files/hello/README | 0
.../files/hello/configure.ac | 6 +
.../files/hello/src/Makefile.am | 2 +
.../files/hello/src/hello.c | 20 +++
.../files/hello/src/libhello.c | 9 ++
.../files/hello/src/libhello.h | 8 ++
.../out-of-source-build-helloworld/project.conf | 13 ++
doc/sessions/cmake.run | 20 +++
doc/sessions/outofsource-autotools-shell.run | 20 +++
doc/sessions/outofsource-helloworld-shell.run | 20 +++
doc/source/examples/cmake.rst | 145 +++++++++++++++++++++
.../out-of-source-autotool-in-source-tree.rst | 141 ++++++++++++++++++++
.../examples/out-of-source-build-helloworld.rst | 140 ++++++++++++++++++++
doc/source/using_examples.rst | 3 +
28 files changed, 692 insertions(+)
diff --git a/doc/examples/cmake/elements/base.bst b/doc/examples/cmake/elements/base.bst
new file mode 100644
index 0000000..1b85a9e
--- /dev/null
+++ b/doc/examples/cmake/elements/base.bst
@@ -0,0 +1,5 @@
+kind: stack
+description: Base stack
+
+depends:
+- base/alpine.bst
diff --git a/doc/examples/cmake/elements/base/alpine.bst b/doc/examples/cmake/elements/base/alpine.bst
new file mode 100644
index 0000000..cf85df5
--- /dev/null
+++ b/doc/examples/cmake/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/cmake/elements/hello.bst b/doc/examples/cmake/elements/hello.bst
new file mode 100644
index 0000000..654dad2
--- /dev/null
+++ b/doc/examples/cmake/elements/hello.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"
+
diff --git a/doc/examples/cmake/files/hello/CMakeLists.txt b/doc/examples/cmake/files/hello/CMakeLists.txt
new file mode 100644
index 0000000..4176932
--- /dev/null
+++ b/doc/examples/cmake/files/hello/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/cmake/files/hello/main.c b/doc/examples/cmake/files/hello/main.c
new file mode 100644
index 0000000..3c7b38d
--- /dev/null
+++ b/doc/examples/cmake/files/hello/main.c
@@ -0,0 +1,7 @@
+#include <stdio.h>
+int main()
+{
+ // printf() displays the string inside quotation
+ printf("Hello, World!\n");
+ return 0;
+}
diff --git a/doc/examples/cmake/project.conf b/doc/examples/cmake/project.conf
new file mode 100644
index 0000000..047ab7f
--- /dev/null
+++ b/doc/examples/cmake/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/examples/out-of-source-autotool-in-source-tree/elements/base.bst b/doc/examples/out-of-source-autotool-in-source-tree/elements/base.bst
new file mode 100644
index 0000000..1b85a9e
--- /dev/null
+++ b/doc/examples/out-of-source-autotool-in-source-tree/elements/base.bst
@@ -0,0 +1,5 @@
+kind: stack
+description: Base stack
+
+depends:
+- base/alpine.bst
diff --git a/doc/examples/out-of-source-autotool-in-source-tree/elements/base/alpine.bst b/doc/examples/out-of-source-autotool-in-source-tree/elements/base/alpine.bst
new file mode 100644
index 0000000..cf85df5
--- /dev/null
+++ b/doc/examples/out-of-source-autotool-in-source-tree/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-autotool-in-source-tree/elements/hello.bst b/doc/examples/out-of-source-autotool-in-source-tree/elements/hello.bst
new file mode 100644
index 0000000..9b82fe6
--- /dev/null
+++ b/doc/examples/out-of-source-autotool-in-source-tree/elements/hello.bst
@@ -0,0 +1,15 @@
+depends:
+- base.bst
+description: |2
+
+ Hello world example from automake
+kind: autotools
+sources:
+- directory: SourB
+ kind: tar
+ ref: 80da43bb5665596ee389e6d8b64b4f122ea4b92a685b1dbd813cd1f0e0c2d83f
+ url: gnu:automake-1.16.tar.gz
+variables:
+ conf-root: "%{build-root}/SourB/doc/amhello"
+ command-subdir: build
+
diff --git a/doc/examples/out-of-source-autotool-in-source-tree/project.conf b/doc/examples/out-of-source-autotool-in-source-tree/project.conf
new file mode 100644
index 0000000..b6f21d4
--- /dev/null
+++ b/doc/examples/out-of-source-autotool-in-source-tree/project.conf
@@ -0,0 +1,13 @@
+# Unique project name
+name: Out-of-Source-builds-in-autotool-in-Source-tree
+
+# 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/examples/out-of-source-build-helloworld/elements/base.bst b/doc/examples/out-of-source-build-helloworld/elements/base.bst
new file mode 100644
index 0000000..1b85a9e
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/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-helloworld/elements/base/alpine.bst b/doc/examples/out-of-source-build-helloworld/elements/base/alpine.bst
new file mode 100644
index 0000000..cf85df5
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/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-helloworld/elements/hello.bst b/doc/examples/out-of-source-build-helloworld/elements/hello.bst
new file mode 100644
index 0000000..49e81ae
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/elements/hello.bst
@@ -0,0 +1,14 @@
+depends:
+- base.bst
+description: |2
+
+ Hello world example from automake
+kind: autotools
+sources:
+- directory: Source
+ kind: local
+ path: files/hello
+variables:
+ conf-root: "%{build-root}/Source"
+ command-subdir: build
+
diff --git a/doc/examples/out-of-source-build-helloworld/files/hello/Makefile.am b/doc/examples/out-of-source-build-helloworld/files/hello/Makefile.am
new file mode 100644
index 0000000..af437a6
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/files/hello/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = src
diff --git a/doc/examples/out-of-source-build-helloworld/files/hello/README b/doc/examples/out-of-source-build-helloworld/files/hello/README
new file mode 100644
index 0000000..e69de29
diff --git a/doc/examples/out-of-source-build-helloworld/files/hello/configure.ac b/doc/examples/out-of-source-build-helloworld/files/hello/configure.ac
new file mode 100644
index 0000000..8cee3f7
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/files/hello/configure.ac
@@ -0,0 +1,6 @@
+AC_INIT([helloworld], [0.1], [will.salmon@codethink.co.uk])
+AM_INIT_AUTOMAKE([-Wall -Werror foreign])
+AC_PROG_CC
+AC_CONFIG_FILES([Makefile
+ src/Makefile])
+AC_OUTPUT
diff --git a/doc/examples/out-of-source-build-helloworld/files/hello/src/Makefile.am b/doc/examples/out-of-source-build-helloworld/files/hello/src/Makefile.am
new file mode 100644
index 0000000..2a4d8a8
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/files/hello/src/Makefile.am
@@ -0,0 +1,2 @@
+bin_PROGRAMS = hello
+hello_SOURCES = hello.c libhello.c
diff --git a/doc/examples/out-of-source-build-helloworld/files/hello/src/hello.c b/doc/examples/out-of-source-build-helloworld/files/hello/src/hello.c
new file mode 100644
index 0000000..83e762c
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/files/hello/src/hello.c
@@ -0,0 +1,20 @@
+/*
+ * hello.c - Simple hello program
+ */
+#include <stdio.h>
+#include <libhello.h>
+
+int main(int argc, char *argv[])
+{
+ const char *person = NULL;
+
+ if (argc > 1)
+ person = argv[1];
+
+ if (person)
+ hello(person);
+ else
+ hello("stranger");
+
+ return 0;
+}
diff --git a/doc/examples/out-of-source-build-helloworld/files/hello/src/libhello.c b/doc/examples/out-of-source-build-helloworld/files/hello/src/libhello.c
new file mode 100644
index 0000000..759b339
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/files/hello/src/libhello.c
@@ -0,0 +1,9 @@
+/*
+ * libhello.c - The hello library
+ */
+#include <stdio.h>
+
+void hello(const char *person)
+{
+ printf("Hello %s\n", person);
+}
diff --git a/doc/examples/out-of-source-build-helloworld/files/hello/src/libhello.h b/doc/examples/out-of-source-build-helloworld/files/hello/src/libhello.h
new file mode 100644
index 0000000..f714f36
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/files/hello/src/libhello.h
@@ -0,0 +1,8 @@
+/*
+ * libhello.h - The hello library
+ */
+
+/*
+ * A function to say hello to @person
+ */
+void hello(const char *person);
diff --git a/doc/examples/out-of-source-build-helloworld/project.conf b/doc/examples/out-of-source-build-helloworld/project.conf
new file mode 100644
index 0000000..9b33a6e
--- /dev/null
+++ b/doc/examples/out-of-source-build-helloworld/project.conf
@@ -0,0 +1,13 @@
+# Unique project name
+name: our-of-source-build-helloworld
+
+# 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/cmake.run b/doc/sessions/cmake.run
new file mode 100644
index 0000000..3241166
--- /dev/null
+++ b/doc/sessions/cmake.run
@@ -0,0 +1,20 @@
+
+commands:
+# Make it fetch first
+- directory: ../examples/cmake
+ command: fetch hello.bst
+
+# Capture a `bst show` of the variables
+- directory: ../examples/cmake
+ output: ../source/sessions/cmake-show-variables.html
+ command: show --deps none --format "%{vars}" hello.bst
+
+# Capture a `bst build`
+- directory: ../examples/cmake
+ output: ../source/sessions/cmake-build.html
+ command: build hello.bst
+
+# Capture a shell output
+- directory: ../examples/cmake
+ output: ../source/sessions/cmake-shell.html
+ command: shell hello.bst -- hello_buildstream
diff --git a/doc/sessions/outofsource-autotools-shell.run b/doc/sessions/outofsource-autotools-shell.run
new file mode 100644
index 0000000..facab5b
--- /dev/null
+++ b/doc/sessions/outofsource-autotools-shell.run
@@ -0,0 +1,20 @@
+
+commands:
+# Make it fetch first
+- directory: ../examples/out-of-source-autotool-in-source-tree
+ command: fetch hello.bst
+
+# Capture a `bst show` of the variables
+- directory: ../examples/out-of-source-autotool-in-source-tree
+ output: ../source/sessions/outofsource-autotool-show-variables.html
+ command: show --deps none --format "%{vars}" hello.bst
+
+# Capture a `bst build`
+- directory: ../examples/out-of-source-autotool-in-source-tree
+ output: ../source/sessions/outofsource-autotools-build.html
+ command: build hello.bst
+
+# Capture a shell output
+- directory: ../examples/out-of-source-autotool-in-source-tree
+ output: ../source/sessions/outofsource-autotools-shell.html
+ command: shell hello.bst -- hello
diff --git a/doc/sessions/outofsource-helloworld-shell.run b/doc/sessions/outofsource-helloworld-shell.run
new file mode 100644
index 0000000..df15bff
--- /dev/null
+++ b/doc/sessions/outofsource-helloworld-shell.run
@@ -0,0 +1,20 @@
+
+commands:
+# Make it fetch first
+- directory: ../examples/out-of-source-build-helloworld
+ command: fetch hello.bst
+
+# Capture a `bst show` of the variables
+- directory: ../examples/out-of-source-build-helloworld
+ output: ../source/sessions/outofsource-helloworld-show-variables.html
+ command: show --deps none --format "%{vars}" hello.bst
+
+# Capture a `bst build`
+- directory: ../examples/out-of-source-build-helloworld
+ output: ../source/sessions/outofsource-helloworld-build.html
+ command: build hello.bst
+
+# Capture a shell output
+- directory: ../examples/out-of-source-build-helloworld
+ output: ../source/sessions/outofsource-helloworld-shell.html
+ command: shell hello.bst -- hello
diff --git a/doc/source/examples/cmake.rst b/doc/source/examples/cmake.rst
new file mode 100644
index 0000000..e124257
--- /dev/null
+++ b/doc/source/examples/cmake.rst
@@ -0,0 +1,145 @@
+
+.. _examples_cmake:
+
+Using Cmake
+===========
+
+Intro
+-----
+
+This example aims to show:
+
+ * How to use cmake elements
+ * How to use Out of source element with cmake
+
+The out of source hello world example show the basics of out of source builds but
+this example shows how to apply that to cmake, a more complex build system.
+
+Build stream aims to make out of source builds as easy as posible and so long as
+the build element supports out of source element it should be the same.
+
+The 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 confirmation tool how to get from
+ `command-subdir` to `directory`.
+
+This example:
+
+ * Sets `directory` to `Source` in `elements/hello.bst`
+ * Sets `command-subdir` to `build` in `elements/hello.bst`
+ * Sets `conf-root` to `"%{build-root}/Source"` in `elements/hello.bst`
+
+This way we can change `command-subdir` with out having to change `conf-root`
+but we could have set `conf-root` to `../Source` but then we would have to
+change it if `command-subdir` changed to `.` or `sub/folder`
+
+
+Prerequisites
+-------------
+All the necessary elements are in the example folder
+
+Project structure
+-----------------
+
+The following is a simple :ref:`project <projectconf>` definition:
+
+``project.conf``
+~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/cmake/project.conf
+ :language: yaml
+
+Note that we’ve added a :ref:`source alias <project_source_aliases>` for
+the ``https://gnome7.codethink.co.uk/tarballs/`` repository to download the
+build tools from, please note that this bootstrap only contains the compiler
+if you wish to use c++ you will need a different bootstrap.
+
+``elements/base/alpine.bst``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/cmake/elements/base/alpine.bst
+ :language: yaml
+
+This is the :mod:`import <elements.import>` element used to import the
+actual Flatpak SDK, it uses an :mod:`tar <sources.tar>` source to
+download and unpack the archive in to the sandbox.
+
+``elements/base.bst``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/cmake/elements/base.bst
+ :language: yaml
+
+This is just a :mod:`stack <elements.stack>` element for convenience sake.
+
+Often times you will have a more complex base to build things on, and it
+is convenient to just use a :mod:`stack <elements.stack>` element for
+your elements to depend on without needing to know about the inner workings
+of the base system build.
+
+``elements/hello.bst``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/cmake/elements/hello.bst
+ :language: yaml
+
+Finally, we show an example of an :mod:`cmake <elements.cmake>` element
+to build our sample "Hello World" program.
+
+We use a :mod:`local <sources.local>` source to obtain the sample
+cmake project, but normally you would probably use a :mod:`git <sources.git>`
+or other source to obtain source code from another repository.
+
+Setting `kind` to `cmake` is enough to trigger the use of cmake and bst will
+formate your build options like ``command-subdir`` and ``conf-root`` for cmake
+but bst dose not provide the cmake program its self, you must specify that you
+want cmake to be a dependency this is done by depending on the`base.bst` element
+that provides cmake.
+
+
+Using the project
+-----------------
+Now that we've explained the basic layout of the project, here are
+just a few things you can try to do with the project.
+
+.. note::
+
+ The following examples assume that you have first changed your working
+ directory to the
+ `project root <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/cmake>`_.
+
+
+Build the hello.bst element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To build the project, run :ref:`bst build <invoking_build>` in the
+following way:
+
+.. raw:: html
+ :file: ../sessions/cmake-build.html
+
+
+Run the hello world program
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The hello world program has been built into the standard ``/usr`` prefix,
+and will automatically be in the default ``PATH`` for running things
+in a :ref:`bst shell <invoking_shell>`.
+
+To just run the program, run :ref:`bst shell <invoking_shell>` in the
+following way:
+
+.. raw:: html
+ :file: ../sessions/cmake-shell.html
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/source/examples/out-of-source-autotool-in-source-tree.rst b/doc/source/examples/out-of-source-autotool-in-source-tree.rst
new file mode 100644
index 0000000..3565caa
--- /dev/null
+++ b/doc/source/examples/out-of-source-autotool-in-source-tree.rst
@@ -0,0 +1,141 @@
+
+.. _examples_out_of_source_autotool_in_source_tree:
+
+
+Building a autotools project Out of source
+==========================================
+
+Intro
+-----
+
+This example aims to show:
+
+ * How to use Out of source element with autotools were the project to be build
+ is not in the sources root directory.
+
+The out of source hello world example show the basics of out of source builds but
+this example shows how to apply that to in source tree projects.
+
+Build stream aims to make out of source builds as easy as possible and so long as
+the build element supports out of source element it should be the same, so while
+this is a auto tools project the principles of in source tree projects should
+transfer to any buildsystem with support for out of source builds.
+
+
+The 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 confirmation tool how to get from
+ `command-subdir` to `directory`.
+
+This example:
+
+ * Sets `directory` to `SourB` in `elements/hello.bst`
+ * Sets `command-subdir` to `build` in `elements/hello.bst`
+ * Sets `conf-root` to `"%{build-root}/SourB/doc/amhello"` in `elements/hello.bst`
+
+Commenly we have `conf-root` be the location of the source. Ether in absolute
+terms, eg `%{build-root}/SourB` or in relative terms `../SourB`. But in our case
+the projcet is not in the root of the source, it is in `doc/amhello` within the
+source so we have to set `conf-root` to equal the location of the source plus
+the location of the project within the source. eg. `"%{build-root}/SourB/doc/amhello"`
+
+Prerequisites
+-------------
+All the necessary elements are in the example folder
+
+Project structure
+-----------------
+
+The following is a simple :ref:`project <projectconf>` definition:
+
+``project.conf``
+~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-autotool-in-source-tree/project.conf
+ :language: yaml
+
+Note that we’ve added a :ref:`source alias <project_source_aliases>` for
+the ``https://gnome7.codethink.co.uk/tarballs/`` repository to download the
+build tools from.
+
+``elements/base/alpine.bst``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-autotool-in-source-tree/elements/base/alpine.bst
+ :language: yaml
+
+This is the :mod:`import <elements.import>` element used to import the
+actual Flatpak SDK, it uses an :mod:`tar <sources.tar>` source to
+download and unpack the archive in to the sandbox.
+
+``elements/base.bst``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-autotool-in-source-tree/elements/base.bst
+ :language: yaml
+
+This is just a :mod:`stack <elements.stack>` element for convenience sake.
+
+Often times you will have a more complex base to build things on, and it
+is convenient to just use a :mod:`stack <elements.stack>` element for
+your elements to depend on without needing to know about the inner workings
+of the base system build.
+
+``elements/hello.bst``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-autotool-in-source-tree/elements/hello.bst
+ :language: yaml
+
+Finally, we show an example of an :mod:`automake <elements.autotools>` element
+to build our sample "Hello World" program.
+
+We use a :mod:`local <sources.local>` source to obtain the sample
+autotools project, but normally you would probably use a :mod:`git <sources.git>`
+or other source to obtain source code from another repository.
+
+
+Using the project
+-----------------
+Now that we've explained the basic layout of the project, here are
+just a few things you can try to do with the project.
+
+.. note::
+
+ The following examples assume that you have first changed your working
+ directory to the
+ `project root <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/out-of-source-autotool-in-source-tree>`_.
+
+Build the hello.bst element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To build the project, run :ref:`bst build <invoking_build>` in the
+following way:
+
+.. raw:: html
+ :file: ../sessions/outofsource-autotools-build.html
+
+
+Run the hello world program
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The hello world program has been built into the standard ``/usr`` prefix,
+and will automatically be in the default ``PATH`` for running things
+in a :ref:`bst shell <invoking_shell>`.
+
+To just run the program, run :ref:`bst shell <invoking_shell>` in the
+following way:
+
+.. raw:: html
+ :file: ../sessions/outofsource-autotools-shell.html
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/source/examples/out-of-source-build-helloworld.rst b/doc/source/examples/out-of-source-build-helloworld.rst
new file mode 100644
index 0000000..58cde5b
--- /dev/null
+++ b/doc/source/examples/out-of-source-build-helloworld.rst
@@ -0,0 +1,140 @@
+
+.. _examples_out_of_source_build_helloworld:
+
+
+Out of source hello world
+=========================
+
+Intro
+-----
+
+This example aims to show:
+
+ * How to use Out of source element with cmake
+
+This example aims to show the basics of out of source builds
+
+Build stream aims to make out of source builds as easy as posible and so long as
+the build element supports out of source element it should be the same.
+
+The 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 confirmation tool how to get from
+ `command-subdir` to `directory`.
+
+This example:
+
+ * Sets `directory` to `Source` in `elements/hello.bst`
+ * Sets `command-subdir` to `build` in `elements/hello.bst`
+ * Sets `conf-root` to `"%{build-root}/Source"` in `elements/hello.bst`
+
+This way we can change `command-subdir` with out having to change `conf-root`
+but we could have set `conf-root` to `../Source` but then we would have to
+change it if `command-subdir` changed to `.` or `sub/folder`
+
+
+
+Prerequisites
+-------------
+All the necessary elements are in the example folder
+
+Project structure
+-----------------
+
+The following is a simple :ref:`project <projectconf>` definition:
+
+``project.conf``
+~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-build-helloworld/project.conf
+ :language: yaml
+
+Note that we’ve added a :ref:`source alias <project_source_aliases>` for
+the ``https://gnome7.codethink.co.uk/tarballs/`` repository to download the
+build tools from.
+
+``elements/base/alpine.bst``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-build-helloworld/elements/base/alpine.bst
+ :language: yaml
+
+This is the :mod:`import <elements.import>` element used to import the
+actual Flatpak SDK, it uses an :mod:`tar <sources.tar>` source to
+download and unpack the archive in to the sandbox.
+
+``elements/base.bst``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-build-helloworld/elements/base.bst
+ :language: yaml
+
+This is just a :mod:`stack <elements.stack>` element for convenience sake.
+
+Often times you will have a more complex base to build things on, and it
+is convenient to just use a :mod:`stack <elements.stack>` element for
+your elements to depend on without needing to know about the inner workings
+of the base system build.
+
+``elements/hello.bst``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/out-of-source-build-helloworld/elements/hello.bst
+ :language: yaml
+
+Finally, we show an example of an :mod:`automake <elements.autotools>` element
+to build our sample "Hello World" program.
+
+We use a :mod:`local <sources.local>` source to obtain the sample
+autotools project, but normally you would probably use a :mod:`git <sources.git>`
+or other source to obtain source code from another repository.
+
+
+Using the project
+-----------------
+Now that we've explained the basic layout of the project, here are
+just a few things you can try to do with the project.
+
+.. note::
+
+ The following examples assume that you have first changed your working
+ directory to the
+ `project root <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/out-of-source-build-helloworld>`_.
+
+Build the hello.bst element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To build the project, run :ref:`bst build <invoking_build>` in the
+following way:
+
+.. raw:: html
+ :file: ../sessions/outofsource-helloworld-build.html
+
+Please see the source option `directory` and variables, `command-subdir` and
+`conf-root` set as described in the introduction.
+
+Run the hello world program
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The hello world program has been built into the standard ``/usr`` prefix,
+and will automatically be in the default ``PATH`` for running things
+in a :ref:`bst shell <invoking_shell>`.
+
+To just run the program, run :ref:`bst shell <invoking_shell>` in the
+following way:
+
+.. raw:: html
+ :file: ../sessions/outofsource-helloworld-shell.html
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/source/using_examples.rst b/doc/source/using_examples.rst
index 622b09e..b194804 100644
--- a/doc/source/using_examples.rst
+++ b/doc/source/using_examples.rst
@@ -12,3 +12,6 @@ maintained and work as expected.
examples/flatpak-autotools
examples/tar-mirror
examples/git-mirror
+ examples/out-of-source-build-helloworld
+ examples/out-of-source-autotool-in-source-tree
+ examples/cmake