buildstream/buildelement.py

@@ -23,6 +23,38 @@ BuildElement - Abstract class for build elements
 The BuildElement class is a convenience element one can derive from for
 implementing the most common case of element.
 
+Built-in functionality
+----------------------
+
+The BuildElement base class provides built in functionality that could be overridden by the
+individual plugins.
+
+This section will give a brief summary of how some of the common features work, some of them or the variables they
+use will be further detailed in the following sections.
+
+* Location for running commands
+
+ The ``command-subdir`` variable sets where the build commands will be executed, if the directory dose not exist it
+ will be created, it is defined relative to the buildroot.
+
+* Location for configuring the project
+
+ The ``conf-root`` is defined by default as ``.`` and is the location that specific build element can use to look
+ for build configuration files, currently autotools and cmake use this.
+
+ The configuration commands are run in ``command-subdir`` and by default ``conf-root`` is ``.`` so if
+ ``conf-root`` is not set the configuration files in ``command-subdir`` will be used.
+
+ By setting ``conf-root`` to ``"%{build-root}/Source/conf_location"`` and your source elements ``directory`` variable
+ to ``Source`` then the configuration files in the directory ``conf_location`` with in your Source will be used.
+ However the location where your configuration command will be run will still be wherever you set your
+ ``command-subdir`` to be.
+
+* Install Location
+
+  You should not change the ``install-root`` variable as it is a special writeable location in the sandbox but it is
+  useful when writing custom install instructions as it may need to be supplied as the ``DESTDIR``, please see the
+  cmake build element for example.
 
 Abstract method implementations
 -------------------------------

buildstream/data/projectconfig.yaml

@@ -38,6 +38,9 @@ variables:
   # normally staged
   build-root: /buildstream/%{project-name}/%{element-name}
 
+  # Indicates where the build system should look for configuration files  
+  conf-root: .
+  
   # Indicates the build installation directory in the sandbox
   install-root: /buildstream-install
 

buildstream/plugins/elements/autotools.yaml

@@ -6,11 +6,11 @@ variables:
     export NOCONFIGURE=1;
 
     if [ -x %{conf-cmd} ]; then true;
-    elif [ -x autogen ]; then ./autogen;
-    elif [ -x autogen.sh ]; then ./autogen.sh;
-    elif [ -x bootstrap ]; then ./bootstrap;
-    elif [ -x bootstrap.sh ]; then ./bootstrap.sh;
-    else autoreconf -ivf;
+    elif [ -x %{conf-root}/autogen ]; then %{conf-root}/./autogen;
+    elif [ -x %{conf-root}/autogen.sh ]; then %{conf-root}/./autogen.sh;
+    elif [ -x %{conf-root}/bootstrap ]; then %{conf-root}/./bootstrap;
+    elif [ -x %{conf-root}/bootstrap.sh ]; then %{conf-root}/./bootstrap.sh;
+    else autoreconf -ivf %{conf-root};
     fi
 
   # Project-wide extra arguments to be passed to `configure`
@@ -22,7 +22,8 @@ variables:
   # For backwards compatibility only, do not use.
   conf-extra: ''
 
-  conf-cmd: ./configure
+  conf-cmd: "%{conf-root}/./configure"
+  
   conf-args: |
 
     --prefix=%{prefix} \

buildstream/plugins/elements/cmake.yaml

@@ -23,7 +23,7 @@ variables:
 
   cmake: |
 
-    cmake -B%{build-dir} -H. -G"%{generator}" %{cmake-args}
+    cmake -B%{build-dir} -H"%{conf-root}" -G"%{generator}" %{cmake-args}
 
   make: cmake --build %{build-dir} -- ${JOBS}
   make-install: env DESTDIR="%{install-root}" cmake --build %{build-dir} --target install

buildstream/sandbox/_sandboxbwrap.py

@@ -108,9 +108,6 @@ class SandboxBwrap(Sandbox):
             bwrap_command += ['--unshare-uts', '--hostname', 'buildstream']
             bwrap_command += ['--unshare-ipc']
 
-        if cwd is not None:
-            bwrap_command += ['--chdir', cwd]
-
         # Give it a proc and tmpfs
         bwrap_command += [
             '--proc', '/proc',
@@ -151,6 +148,10 @@ class SandboxBwrap(Sandbox):
         if flags & SandboxFlags.ROOT_READ_ONLY:
             bwrap_command += ["--remount-ro", "/"]
 
+        if cwd is not None:
+            bwrap_command += ['--dir', cwd]
+            bwrap_command += ['--chdir', cwd]
+
         # Set UID and GUI
         if self.user_ns_available:
             bwrap_command += ['--unshare-user']
@@ -179,11 +180,6 @@ class SandboxBwrap(Sandbox):
         with ExitStack() as stack:
             stack.enter_context(mount_map.mounted(self))
 
-            # Ensure the cwd exists
-            if cwd is not None:
-                workdir = os.path.join(root_mount_source, cwd.lstrip(os.sep))
-                os.makedirs(workdir, exist_ok=True)
-
             # If we're interactive, we want to inherit our stdin,
             # otherwise redirect to /dev/null, ensuring process
             # disconnected from terminal.

buildstream/sandbox/_sandboxchroot.py

@@ -100,9 +100,8 @@ class SandboxChroot(Sandbox):
 
             # Ensure the cwd exists
             if cwd is not None:
-                workdir = os.path.join(root_mount_source, cwd.lstrip(os.sep))
+                workdir = os.path.join(rootfs, cwd.lstrip(os.sep))
                 os.makedirs(workdir, exist_ok=True)
-
             status = self.chroot(rootfs, command, stdin, stdout,
                                  stderr, cwd, env, flags)
 

buildstream/sandbox/sandbox.py

@@ -197,6 +197,11 @@ class Sandbox():
     def run(self, command, flags, *, cwd=None, env=None):
         """Run a command in the sandbox.
 
+        Note:
+            When reimplementing this function for sandbox specific implementations it is the sandbox's and probably
+            this functions responsibility to ensure that cwd is created correctly and that if a workspace is used
+            then the directory must be correctly created to take this in to account.
+
         Args:
             command (list): The command to run in the sandboxed environment, as a list
                             of strings starting with the binary to run.

buildstream/source.py

@@ -20,6 +20,19 @@
 Source - Base source class
 ==========================
 
+Built-in functionality
+----------------------
+
+The Source base class provides built in functionality that could be overridden by the
+individual plugins.
+
+* Directory
+
+  The ``directory`` variable can be set for all sources of a type in project.conf
+  or per source within a element.
+
+  This sets the location with in the build root that the content of the source will be
+  loaded in to. If the location dose not exist it will be created.
 
 .. _core_source_abstract_methods:
 

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