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.

doc/examples/cmake/elements/base.bst

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

doc/examples/cmake/elements/base/alpine.bst

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

doc/examples/cmake/elements/hello.bst

+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"
+

doc/examples/cmake/files/hello/CMakeLists.txt

+
+# 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) 

doc/examples/cmake/files/hello/main.c

+#include <stdio.h>
+int main()
+{
+   // printf() displays the string inside quotation
+   printf("Hello, World!\n");
+   return 0;
+}

doc/examples/cmake/project.conf

+# 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/

doc/examples/out-of-source-autotool-in-source-tree/elements/base.bst

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

doc/examples/out-of-source-autotool-in-source-tree/elements/base/alpine.bst

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

doc/examples/out-of-source-autotool-in-source-tree/elements/hello.bst

+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
+

doc/examples/out-of-source-autotool-in-source-tree/project.conf

+# 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/

doc/examples/out-of-source-build-helloworld/elements/base.bst

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

doc/examples/out-of-source-build-helloworld/elements/base/alpine.bst

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

doc/examples/out-of-source-build-helloworld/elements/hello.bst

+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
+

doc/examples/out-of-source-build-helloworld/files/hello/Makefile.am

+SUBDIRS = src

doc/examples/out-of-source-build-helloworld/files/hello/configure.ac

+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

doc/examples/out-of-source-build-helloworld/files/hello/src/Makefile.am

+bin_PROGRAMS = hello
+hello_SOURCES = hello.c libhello.c

doc/examples/out-of-source-build-helloworld/files/hello/src/hello.c

+/*
+ * 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;
+}

doc/examples/out-of-source-build-helloworld/files/hello/src/libhello.c

+/*
+ * libhello.c - The hello library
+ */
+#include <stdio.h>
+
+void hello(const char *person)
+{
+  printf("Hello %s\n", person);
+}

doc/examples/out-of-source-build-helloworld/files/hello/src/libhello.h

+/*
+ * libhello.h - The hello library
+ */
+
+/*
+ * A function to say hello to @person
+ */
+void hello(const char *person);