From 8932103c83971651a41526fc2235895ef1ac399d Mon Sep 17 00:00:00 2001 From: William Salmon Date: Mon, 10 Sep 2018 15:46:46 +0100 Subject: Adding Out of Source Build Example For issue #695 in Gitlab. --- doc/examples/out-of-source-build/elements/base.bst | 5 + .../out-of-source-build/elements/base/alpine.bst | 13 ++ .../out-of-source-build/elements/sourceroot.bst | 14 ++ .../out-of-source-build/elements/subfolder.bst | 14 ++ .../files/OutOfSourceProject/CMakeLists.txt | 14 ++ .../files/OutOfSourceProject/README | 5 + .../files/OutOfSourceProject/main/CMakeLists.txt | 14 ++ .../files/OutOfSourceProject/main/main.c | 11 ++ doc/examples/out-of-source-build/project.conf | 13 ++ doc/sessions/out-of-source-build.run | 41 +++++ doc/source/examples/out-of-source-build.rst | 173 +++++++++++++++++++++ .../out-of-source-build-build-main.html | 99 ++++++++++++ .../out-of-source-build-build-subfolder.html | 99 ++++++++++++ .../sessions-stored/out-of-source-build-build.html | 109 +++++++++++++ .../out-of-source-build-shell-main.html | 22 +++ .../out-of-source-build-shell-subfolder.html | 22 +++ .../sessions-stored/out-of-source-build-shell.html | 22 +++ .../out-of-source-build-show-variables.html | 64 ++++++++ doc/source/using_examples.rst | 1 + tests/examples/out-of-source.py | 78 ++++++++++ 20 files changed, 833 insertions(+) create mode 100644 doc/examples/out-of-source-build/elements/base.bst create mode 100644 doc/examples/out-of-source-build/elements/base/alpine.bst create mode 100644 doc/examples/out-of-source-build/elements/sourceroot.bst create mode 100644 doc/examples/out-of-source-build/elements/subfolder.bst create mode 100644 doc/examples/out-of-source-build/files/OutOfSourceProject/CMakeLists.txt create mode 100644 doc/examples/out-of-source-build/files/OutOfSourceProject/README create mode 100644 doc/examples/out-of-source-build/files/OutOfSourceProject/main/CMakeLists.txt create mode 100644 doc/examples/out-of-source-build/files/OutOfSourceProject/main/main.c create mode 100644 doc/examples/out-of-source-build/project.conf create mode 100644 doc/sessions/out-of-source-build.run create mode 100644 doc/source/examples/out-of-source-build.rst create mode 100644 doc/source/sessions-stored/out-of-source-build-build-main.html create mode 100644 doc/source/sessions-stored/out-of-source-build-build-subfolder.html create mode 100644 doc/source/sessions-stored/out-of-source-build-build.html create mode 100644 doc/source/sessions-stored/out-of-source-build-shell-main.html create mode 100644 doc/source/sessions-stored/out-of-source-build-shell-subfolder.html create mode 100644 doc/source/sessions-stored/out-of-source-build-shell.html create mode 100644 doc/source/sessions-stored/out-of-source-build-show-variables.html create mode 100644 tests/examples/out-of-source.py 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 000000000..1b85a9e8c --- /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 000000000..cf85df5bf --- /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 000000000..aadcf09e3 --- /dev/null +++ b/doc/examples/out-of-source-build/elements/sourceroot.bst @@ -0,0 +1,14 @@ +depends: +- base.bst +description: |2 + + Hello world example from cmake +kind: cmake +sources: +- kind: local + path: files/OutOfSourceProject + directory: Source +variables: + command-subdir: build + conf-root: "%{build-root}/Source/" + diff --git a/doc/examples/out-of-source-build/elements/subfolder.bst b/doc/examples/out-of-source-build/elements/subfolder.bst new file mode 100644 index 000000000..d2e241f6d --- /dev/null +++ b/doc/examples/out-of-source-build/elements/subfolder.bst @@ -0,0 +1,14 @@ +depends: +- base.bst +description: |2 + + Hello world example from cmake +kind: cmake +sources: +- kind: local + path: files/OutOfSourceProject + directory: Source +variables: + command-subdir: build + conf-root: "%{build-root}/Source/main" + diff --git a/doc/examples/out-of-source-build/files/OutOfSourceProject/CMakeLists.txt b/doc/examples/out-of-source-build/files/OutOfSourceProject/CMakeLists.txt new file mode 100644 index 000000000..287c78371 --- /dev/null +++ b/doc/examples/out-of-source-build/files/OutOfSourceProject/CMakeLists.txt @@ -0,0 +1,14 @@ + +# Set the minimum version of CMake that can be used +# To find the cmake version run +# $ cmake --version +cmake_minimum_required(VERSION 2.8) + +# Set the project name +project (hello_main C) + +# Set something so that we can see if main.c was compiled from this cmake +# projcet +set(CMAKE_C_FLAGS "-DFULL_PROJECT") + +add_subdirectory(main) diff --git a/doc/examples/out-of-source-build/files/OutOfSourceProject/README b/doc/examples/out-of-source-build/files/OutOfSourceProject/README new file mode 100644 index 000000000..49489374a --- /dev/null +++ b/doc/examples/out-of-source-build/files/OutOfSourceProject/README @@ -0,0 +1,5 @@ +This is a simple example project for using buildstream to build software that is +located in different parts of it sources + +The source code will produce different code depending on which directory you +specify to cmake diff --git a/doc/examples/out-of-source-build/files/OutOfSourceProject/main/CMakeLists.txt b/doc/examples/out-of-source-build/files/OutOfSourceProject/main/CMakeLists.txt new file mode 100644 index 000000000..417693296 --- /dev/null +++ b/doc/examples/out-of-source-build/files/OutOfSourceProject/main/CMakeLists.txt @@ -0,0 +1,14 @@ + +# Set the minimum version of CMake that can be used +# To find the cmake version run +# $ cmake --version +cmake_minimum_required(VERSION 2.8) + +# Set the project name +project (hello_buildstreams C) + +# Add an executable +add_executable(hello_buildstream main.c) + + +install(TARGETS hello_buildstream DESTINATION /bin) diff --git a/doc/examples/out-of-source-build/files/OutOfSourceProject/main/main.c b/doc/examples/out-of-source-build/files/OutOfSourceProject/main/main.c new file mode 100644 index 000000000..a114945e2 --- /dev/null +++ b/doc/examples/out-of-source-build/files/OutOfSourceProject/main/main.c @@ -0,0 +1,11 @@ +#include +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 000000000..047ab7ff1 --- /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 000000000..31b7b174b --- /dev/null +++ b/doc/sessions/out-of-source-build.run @@ -0,0 +1,41 @@ + +commands: +# This section is for the hello.bst element +# Make it fetch first +- directory: ../examples/out-of-source-build + command: fetch sourceroot.bst + +# Capture a `bst show` of the variables +- directory: ../examples/out-of-source-build + output: ../source/sessions/out-of-source-build-show-variables.html + command: show --deps none --format "%{vars}" sourceroot.bst + +# Capture a `bst build` +- directory: ../examples/out-of-source-build + output: ../source/sessions/out-of-source-build-build.html + command: build sourceroot.bst + +# Capture a shell output +- directory: ../examples/out-of-source-build + output: ../source/sessions/out-of-source-build-shell-ls.html + command: shell sourceroot.bst --build -- ls .. + +# Capture a shell output +- directory: ../examples/out-of-source-build + output: ../source/sessions/out-of-source-build-shell.html + command: shell sourceroot.bst -- hello_buildstream + +# This section if for the hello_main.bst element +# Make it fetch first +- directory: ../examples/out-of-source-build + command: fetch subfolder.bst + +# Capture a `bst build` +- directory: ../examples/out-of-source-build + output: ../source/sessions/out-of-source-build-build-subfolder.html + command: build subfolder.bst + +# Capture a shell output +- directory: ../examples/out-of-source-build + output: ../source/sessions/out-of-source-build-shell-subfolder.html + command: shell subfolder.bst -- hello_buildstream diff --git a/doc/source/examples/out-of-source-build.rst b/doc/source/examples/out-of-source-build.rst new file mode 100644 index 000000000..b8573398a --- /dev/null +++ b/doc/source/examples/out-of-source-build.rst @@ -0,0 +1,173 @@ + +.. _examples_out-of-source-build.rst: + +Building out of source +====================== + +Intro +----- + +This example aims to: + + * Give a basic overview of how out of source builds work. This is done by + collecting the relevant bits of information spread across different sections + of the documentation that tend to group information by element rather than + task. + * Give Examples of how to use out of source builds. + +Buildstream aims to make out of source builds easy and consistent across as +many build systems as possible. However it should be noted that not all build +systems support `out of source builds`. + +Key Variables +------------- + +Out of source builds are configured by setting: + + * ``directory`` of the source, this sets the source to extract to a folder in + the build root. + * ``command-subdir`` variable, sets the directory were the build commands + will be run. + * ``conf-root`` variable, tells the configuration tool were to find the root of + the source code. + +``conf-root`` is given to the configuration tool which is run in +``command-subdir``. It can either be given as a relative path from +``command-subdir`` to the location of the source code. Or as an absolute +location. + +By setting ``conf-root`` as a absolute path we can change ``command-subdir`` +with out having to change ``conf-root``. + +If a absolute path is given it must be from the root of the sandbox. +To specify a absolute path from the root of the build-root the build-root +variable can be used eg. ``conf-root`` can be set to ``"%{build-root}/Source"`` +to specify the ``Source`` folder in the root of the build-root. + +These variables can be use for many of the buildstream build element kinds. +Indeed converting to out of source builds should be as simple as adding these +variables to the individual bst files and in some circumstance most of the +variables could be set at a project level. + + +Examples +-------- + +The out of source examples can be found in the buildstream source code in +``doc/examples/out-of-source`` folder in the buildstream source. The two cmake +elements we will use as examples are `sourceroot.bst` and `subfolder.bst`. + +It is very simple to create a build element that loads a source in to the +`build-root` and then uses the standard build tools to build the project in the +same folder. Buildstream has lots of build element plugs so that a new element +may only need to set its `kind` to the relevant build system and then define a +source, the `sourceroot.bst` example element takes a cmake exmaple and expands +it to a out of source build. + +An alternative build elements might build in a sub folder of the source. The +`hello.bst` element in the `autotools` example dose this. And a out of source +version is given in the `subfolder.bst` element of the out of source example +project. + + +Build project defined in source root +------------------------------------ + +This example points cmake at the root of the source. + +In this example, the CMakeLis.txt in the root folder of the source +causes the helloworld program to state that it was build from the root of the +source project when called. + +To make the software build in a folder outside of the source code we set the +source to be in a sub folder of the build-root folder rather than in its root, +in our case this folder will be called ``source``. + +The build tools are then set to run a separate folder in the build-root folder, +this will be called ``build``. We must then tell the build tools were to +find the source code, this is done with the ``conf-root`` variable. + +This is done by: + + * Setting the sources ``directory`` property to ``Source`` + * Setting the element variable ``command-subdir`` to ``build`` + * Setting the element variable ``conf-root`` to ``"%{build-root}/Source"`` + + +``sourceroot.bst`` +~~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../../examples/out-of-source-build/elements/sourceroot.bst + :language: yaml + +We can then use the ``bst show`` command to see how variable like ``conf-root`` +are expanded. + +.. raw:: html + :file: ../sessions/out-of-source-build-show-variables.html + + +Using a workspace or a shell with `--build` can be used to see the folder +structure that gets created. When bst shell is launched it runs in the +``command-subdir`` directory. If ``ls ..`` is run we can see that the build-root +now contains the ``build`` folder and the ``Source`` folder. + +.. raw:: html + :file: ../sessions//out-of-source-build-shell-ls.html + + + +Build project defined in source subdirectory +-------------------------------------------- + +This example points cmake at he `main` directory inside the source. + +In this example, the CMakeLis.txt in the folder main in the root of the +source causes the helloworld program to state that it was build from a subfolder +of the source project when called. + +To make the software build in a folder outside of the source code we set the +source to be in a sub folder of the build-root folder rather than in its root, +in our case this folder will be called ``source``. + +The build tools are then set to run a separate folder in the build-root folder, +this will be called ``build``. We must then tell the build tools were to +find the source code, this is done with the ``conf-root`` variable. +Unlike the previous example we need ``conf-root`` to point the sub directory of +the source project rather than the root. + + + +This is done by: + + * Setting the sources ``directory`` property to ``Source`` + * Setting the element variable ``command-subdir`` to ``build`` + * Setting the element variable ``conf-root`` to + ``"%{build-root}/Source/main"`` + +``subfolder.bst`` +~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../../examples/out-of-source-build/elements/subfolder.bst + :language: yaml + + +Run the hello world program +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We can see the output of the two different binaries created from the same +source by invoking the shell of the respective elements with the new programs +name. + +When the binary from the build that included the file that defined the extra build +flag ``FULL_PROJECT`` is run, we get the following output: + +.. raw:: html + :file: ../sessions/out-of-source-build-shell.html + +When the binary from the build that pointed to the CMakeList.txt that +just adds the source without defining any extra build flags is run, we get the +following output: + +.. raw:: html + :file: ../sessions/out-of-source-build-shell-subfolder.html diff --git a/doc/source/sessions-stored/out-of-source-build-build-main.html b/doc/source/sessions-stored/out-of-source-build-build-main.html new file mode 100644 index 000000000..2ac37632b --- /dev/null +++ b/doc/source/sessions-stored/out-of-source-build-build-main.html @@ -0,0 +1,99 @@ + +
+user@host:~/out-of-source-build$ bst build hello_main.bst
+
+[--:--:--][][] START   Build
+[--:--:--][][] START   Loading elements
+[00:00:00][][] SUCCESS Loading elements
+[--:--:--][][] START   Resolving elements
+[00:00:00][][] SUCCESS Resolving elements
+[--:--:--][][] START   Resolving cached state
+[00:00:00][][] SUCCESS Resolving cached state
+[--:--:--][][] START   Checking sources
+[00:00:00][][] SUCCESS Checking sources
+
+BuildStream Version 1.3.0+867.gb1ab7d77.dirty
+  Session Start: Friday, 09-11-2018 at 16:03:46
+  Project:       cmake-out-of-source-build (/home/user/projects/buildstream/buildstream/doc/examples/out-of-source-build)
+  Targets:       hello_main.bst
+
+User Configuration
+  Configuration File:      /home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/buildstream.conf
+  Log Files:               /home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/logs
+  Source Mirrors:          /home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/sources
+  Build Area:              /home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/build
+  Artifact Cache:          /home/user/projects/buildstream/buildstream/doc/run-bst-pb6r66bq/artifacts
+  Strict Build Plan:       Yes
+  Maximum Fetch Tasks:     10
+  Maximum Build Tasks:     4
+  Maximum Push Tasks:      4
+  Maximum Network Retries: 2
+
+Pipeline
+      cached 9afe69d645f0bee106749bc2101aae16ef437bb51e1b343ef1f16f04f0572efb base/alpine.bst 
+      cached 19f7c50c7a1db9ae4babe9d1f34f4cdbbf2428827d48673861fd1452d6c7e16b base.bst 
+   buildable 4ab8120b3cfb80e993b1efe8af5fa5d49bcba5aaf67e1ee4f5ede735a6cfcf4e hello_main.bst 
+===============================================================================
+[--:--:--][4ab8120b][build:hello_main.bst                ] START   cmake-out-of-source-build/hello_main/4ab8120b-build.26805.log
+[--:--:--][4ab8120b][build:hello_main.bst                ] START   Staging dependencies
+[00:00:00][4ab8120b][build:hello_main.bst                ] SUCCESS Staging dependencies
+[--:--:--][4ab8120b][build:hello_main.bst                ] START   Integrating sandbox
+[00:00:00][4ab8120b][build:hello_main.bst                ] SUCCESS Integrating sandbox
+[--:--:--][4ab8120b][build:hello_main.bst                ] START   Staging sources
+[00:00:00][4ab8120b][build:hello_main.bst                ] SUCCESS Staging sources
+[--:--:--][4ab8120b][build:hello_main.bst                ] START   Running configure-commands
+[--:--:--][4ab8120b][build:hello_main.bst                ] STATUS  Running configure-commands
+
+    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
+
+[00:00:00][4ab8120b][build:hello_main.bst                ] SUCCESS Running configure-commands
+[--:--:--][4ab8120b][build:hello_main.bst                ] START   Running build-commands
+[--:--:--][4ab8120b][build:hello_main.bst                ] STATUS  Running build-commands
+
+    cmake --build _builddir -- ${JOBS}
+
+[00:00:00][4ab8120b][build:hello_main.bst                ] SUCCESS Running build-commands
+[--:--:--][4ab8120b][build:hello_main.bst                ] START   Running install-commands
+[--:--:--][4ab8120b][build:hello_main.bst                ] STATUS  Running install-commands
+
+    env DESTDIR="/buildstream-install" cmake --build _builddir --target install
+
+[00:00:00][4ab8120b][build:hello_main.bst                ] SUCCESS Running install-commands
+[--:--:--][4ab8120b][build:hello_main.bst                ] START   Running strip-commands
+[--:--:--][4ab8120b][build:hello_main.bst                ] STATUS  Running strip-commands
+
+    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"' - {} ';'
+
+[00:00:00][4ab8120b][build:hello_main.bst                ] SUCCESS Running strip-commands
+[--:--:--][4ab8120b][build:hello_main.bst                ] START   Caching artifact
+[00:00:00][4ab8120b][build:hello_main.bst                ] SUCCESS Caching artifact
+[00:00:01][4ab8120b][build:hello_main.bst                ] SUCCESS cmake-out-of-source-build/hello_main/4ab8120b-build.26805.log
+[00:00:01][][] SUCCESS Build
+
+Pipeline Summary
+  Total:       3
+  Session:     1
+  Fetch Queue: processed 0, skipped 1, failed 0 
+  Build Queue: processed 1, skipped 0, failed 0
+
diff --git a/doc/source/sessions-stored/out-of-source-build-build-subfolder.html b/doc/source/sessions-stored/out-of-source-build-build-subfolder.html new file mode 100644 index 000000000..0f5a61d78 --- /dev/null +++ b/doc/source/sessions-stored/out-of-source-build-build-subfolder.html @@ -0,0 +1,99 @@ + +
+user@host:~/out-of-source-build$ bst build subfolder.bst
+
+[--:--:--][][] START   Build
+[--:--:--][][] START   Loading elements
+[00:00:00][][] SUCCESS Loading elements
+[--:--:--][][] START   Resolving elements
+[00:00:00][][] SUCCESS Resolving elements
+[--:--:--][][] START   Resolving cached state
+[00:00:00][][] SUCCESS Resolving cached state
+[--:--:--][][] START   Checking sources
+[00:00:00][][] SUCCESS Checking sources
+
+BuildStream Version 1.3.0+890.g20bbe4b5
+  Session Start: Monday, 19-11-2018 at 15:38:33
+  Project:       cmake-out-of-source-build (/home/user/projects/buildstream/buildstream/doc/examples/out-of-source-build)
+  Targets:       subfolder.bst
+
+User Configuration
+  Configuration File:      /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/buildstream.conf
+  Log Files:               /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/logs
+  Source Mirrors:          /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/sources
+  Build Area:              /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/build
+  Artifact Cache:          /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/artifacts
+  Strict Build Plan:       Yes
+  Maximum Fetch Tasks:     10
+  Maximum Build Tasks:     4
+  Maximum Push Tasks:      4
+  Maximum Network Retries: 2
+
+Pipeline
+      cached 9afe69d645f0bee106749bc2101aae16ef437bb51e1b343ef1f16f04f0572efb base/alpine.bst 
+      cached 19f7c50c7a1db9ae4babe9d1f34f4cdbbf2428827d48673861fd1452d6c7e16b base.bst 
+   buildable 150c4a9e5b1a329684dafeecd20cec5e792459f252dda600cd11d01120047e34 subfolder.bst 
+===============================================================================
+[--:--:--][150c4a9e][build:subfolder.bst                 ] START   cmake-out-of-source-build/subfolder/150c4a9e-build.18278.log
+[--:--:--][150c4a9e][build:subfolder.bst                 ] START   Staging dependencies
+[00:00:00][150c4a9e][build:subfolder.bst                 ] SUCCESS Staging dependencies
+[--:--:--][150c4a9e][build:subfolder.bst                 ] START   Integrating sandbox
+[00:00:00][150c4a9e][build:subfolder.bst                 ] SUCCESS Integrating sandbox
+[--:--:--][150c4a9e][build:subfolder.bst                 ] START   Staging sources
+[00:00:00][150c4a9e][build:subfolder.bst                 ] SUCCESS Staging sources
+[--:--:--][150c4a9e][build:subfolder.bst                 ] START   Running configure-commands
+[--:--:--][150c4a9e][build:subfolder.bst                 ] STATUS  Running configure-commands
+
+    cmake -B_builddir -H"/buildstream/cmake-out-of-source-build/subfolder.bst/Source/src/main" -G"Unix Makefiles" -DCMAKE_INSTALL_PREFIX:PATH="/usr" \
+    -DCMAKE_INSTALL_LIBDIR=lib
+
+[00:00:00][150c4a9e][build:subfolder.bst                 ] SUCCESS Running configure-commands
+[--:--:--][150c4a9e][build:subfolder.bst                 ] START   Running build-commands
+[--:--:--][150c4a9e][build:subfolder.bst                 ] STATUS  Running build-commands
+
+    cmake --build _builddir -- ${JOBS}
+
+[00:00:00][150c4a9e][build:subfolder.bst                 ] SUCCESS Running build-commands
+[--:--:--][150c4a9e][build:subfolder.bst                 ] START   Running install-commands
+[--:--:--][150c4a9e][build:subfolder.bst                 ] STATUS  Running install-commands
+
+    env DESTDIR="/buildstream-install" cmake --build _builddir --target install
+
+[00:00:00][150c4a9e][build:subfolder.bst                 ] SUCCESS Running install-commands
+[--:--:--][150c4a9e][build:subfolder.bst                 ] START   Running strip-commands
+[--:--:--][150c4a9e][build:subfolder.bst                 ] STATUS  Running strip-commands
+
+    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"' - {} ';'
+
+[00:00:00][150c4a9e][build:subfolder.bst                 ] SUCCESS Running strip-commands
+[--:--:--][150c4a9e][build:subfolder.bst                 ] START   Caching artifact
+[00:00:00][150c4a9e][build:subfolder.bst                 ] SUCCESS Caching artifact
+[00:00:01][150c4a9e][build:subfolder.bst                 ] SUCCESS cmake-out-of-source-build/subfolder/150c4a9e-build.18278.log
+[00:00:01][][] SUCCESS Build
+
+Pipeline Summary
+  Total:       3
+  Session:     1
+  Fetch Queue: processed 0, skipped 1, failed 0 
+  Build Queue: processed 1, skipped 0, failed 0
+
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 000000000..680acaff7 --- /dev/null +++ b/doc/source/sessions-stored/out-of-source-build-build.html @@ -0,0 +1,109 @@ + +
+user@host:~/out-of-source-build$ bst build sourceroot.bst
+
+[--:--:--][][] START   Build
+[--:--:--][][] START   Loading elements
+[00:00:00][][] SUCCESS Loading elements
+[--:--:--][][] START   Resolving elements
+[00:00:00][][] SUCCESS Resolving elements
+[--:--:--][][] START   Resolving cached state
+[00:00:00][][] SUCCESS Resolving cached state
+[--:--:--][][] START   Checking sources
+[00:00:00][][] SUCCESS Checking sources
+
+BuildStream Version 1.3.0+890.g20bbe4b5
+  Session Start: Monday, 19-11-2018 at 15:38:12
+  Project:       cmake-out-of-source-build (/home/user/projects/buildstream/buildstream/doc/examples/out-of-source-build)
+  Targets:       sourceroot.bst
+
+User Configuration
+  Configuration File:      /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/buildstream.conf
+  Log Files:               /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/logs
+  Source Mirrors:          /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/sources
+  Build Area:              /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/build
+  Artifact Cache:          /home/user/projects/buildstream/buildstream/doc/run-bst-jjblcjj9/artifacts
+  Strict Build Plan:       Yes
+  Maximum Fetch Tasks:     10
+  Maximum Build Tasks:     4
+  Maximum Push Tasks:      4
+  Maximum Network Retries: 2
+
+Pipeline
+   buildable 9afe69d645f0bee106749bc2101aae16ef437bb51e1b343ef1f16f04f0572efb base/alpine.bst 
+     waiting 19f7c50c7a1db9ae4babe9d1f34f4cdbbf2428827d48673861fd1452d6c7e16b base.bst 
+     waiting f7b50d8b77c24a53e09abb6fb6ab2b6be6328cf5c08e33dcd26f2ffdab3eef89 sourceroot.bst 
+===============================================================================
+[--:--:--][9afe69d6][build:base/alpine.bst               ] START   cmake-out-of-source-build/base-alpine/9afe69d6-build.18125.log
+[--:--:--][9afe69d6][build:base/alpine.bst               ] START   Staging sources
+[00:00:09][9afe69d6][build:base/alpine.bst               ] SUCCESS Staging sources
+[--:--:--][9afe69d6][build:base/alpine.bst               ] START   Caching artifact
+[00:00:03][9afe69d6][build:base/alpine.bst               ] SUCCESS Caching artifact
+[00:00:16][9afe69d6][build:base/alpine.bst               ] SUCCESS cmake-out-of-source-build/base-alpine/9afe69d6-build.18125.log
+[--:--:--][19f7c50c][build:base.bst                      ] START   cmake-out-of-source-build/base/19f7c50c-build.18133.log
+[--:--:--][19f7c50c][build:base.bst                      ] START   Caching artifact
+[00:00:00][19f7c50c][build:base.bst                      ] SUCCESS Caching artifact
+[00:00:00][19f7c50c][build:base.bst                      ] SUCCESS cmake-out-of-source-build/base/19f7c50c-build.18133.log
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] START   cmake-out-of-source-build/sourceroot/f7b50d8b-build.18138.log
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] START   Staging dependencies
+[00:00:00][f7b50d8b][build:sourceroot.bst                ] SUCCESS Staging dependencies
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] START   Integrating sandbox
+[00:00:00][f7b50d8b][build:sourceroot.bst                ] SUCCESS Integrating sandbox
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] START   Staging sources
+[00:00:00][f7b50d8b][build:sourceroot.bst                ] SUCCESS Staging sources
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] START   Running configure-commands
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] STATUS  Running configure-commands
+
+    cmake -B_builddir -H"/buildstream/cmake-out-of-source-build/sourceroot.bst/Source/src" -G"Unix Makefiles" -DCMAKE_INSTALL_PREFIX:PATH="/usr" \
+    -DCMAKE_INSTALL_LIBDIR=lib
+
+[00:00:00][f7b50d8b][build:sourceroot.bst                ] SUCCESS Running configure-commands
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] START   Running build-commands
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] STATUS  Running build-commands
+
+    cmake --build _builddir -- ${JOBS}
+
+[00:00:00][f7b50d8b][build:sourceroot.bst                ] SUCCESS Running build-commands
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] START   Running install-commands
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] STATUS  Running install-commands
+
+    env DESTDIR="/buildstream-install" cmake --build _builddir --target install
+
+[00:00:00][f7b50d8b][build:sourceroot.bst                ] SUCCESS Running install-commands
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] START   Running strip-commands
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] STATUS  Running strip-commands
+
+    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"' - {} ';'
+
+[00:00:00][f7b50d8b][build:sourceroot.bst                ] SUCCESS Running strip-commands
+[--:--:--][f7b50d8b][build:sourceroot.bst                ] START   Caching artifact
+[00:00:00][f7b50d8b][build:sourceroot.bst                ] SUCCESS Caching artifact
+[00:00:01][f7b50d8b][build:sourceroot.bst                ] SUCCESS cmake-out-of-source-build/sourceroot/f7b50d8b-build.18138.log
+[00:00:19][][] SUCCESS Build
+
+Pipeline Summary
+  Total:       3
+  Session:     3
+  Fetch Queue: processed 0, skipped 3, failed 0 
+  Build Queue: processed 3, skipped 0, failed 0
+
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 000000000..cbd386255 --- /dev/null +++ b/doc/source/sessions-stored/out-of-source-build-shell-main.html @@ -0,0 +1,22 @@ + +
+user@host:~/out-of-source-build$ bst shell hello_main.bst --  hello_buildstream
+
+[--:--:--][][] START   Loading elements
+[00:00:00][][] SUCCESS Loading elements
+[--:--:--][][] START   Resolving elements
+[00:00:00][][] SUCCESS Resolving elements
+[--:--:--][][] START   Resolving cached state
+[00:00:00][][] SUCCESS Resolving cached state
+[--:--:--][4ab8120b][ main:hello_main.bst                ] START   Staging dependencies
+[00:00:00][4ab8120b][ main:hello_main.bst                ] SUCCESS Staging dependencies
+[--:--:--][4ab8120b][ main:hello_main.bst                ] START   Integrating sandbox
+[00:00:00][4ab8120b][ main:hello_main.bst                ] SUCCESS Integrating sandbox
+[--:--:--][4ab8120b][ main:hello_main.bst                ] STATUS  Running command
+
+    hello_buildstream
+
+Hello, World!
+
diff --git a/doc/source/sessions-stored/out-of-source-build-shell-subfolder.html b/doc/source/sessions-stored/out-of-source-build-shell-subfolder.html new file mode 100644 index 000000000..6cf0592db --- /dev/null +++ b/doc/source/sessions-stored/out-of-source-build-shell-subfolder.html @@ -0,0 +1,22 @@ + +
+user@host:~/out-of-source-build$ bst shell subfolder.bst --  hello_buildstream
+
+[--:--:--][][] START   Loading elements
+[00:00:00][][] SUCCESS Loading elements
+[--:--:--][][] START   Resolving elements
+[00:00:00][][] SUCCESS Resolving elements
+[--:--:--][][] START   Resolving cached state
+[00:00:00][][] SUCCESS Resolving cached state
+[--:--:--][150c4a9e][ main:subfolder.bst                 ] START   Staging dependencies
+[00:00:00][150c4a9e][ main:subfolder.bst                 ] SUCCESS Staging dependencies
+[--:--:--][150c4a9e][ main:subfolder.bst                 ] START   Integrating sandbox
+[00:00:00][150c4a9e][ main:subfolder.bst                 ] SUCCESS Integrating sandbox
+[--:--:--][150c4a9e][ main:subfolder.bst                 ] STATUS  Running command
+
+    hello_buildstream
+
+Hello, World! Built from a subdirectory of the source.
+
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 000000000..9798a492c --- /dev/null +++ b/doc/source/sessions-stored/out-of-source-build-shell.html @@ -0,0 +1,22 @@ + +
+user@host:~/out-of-source-build$ bst shell sourceroot.bst --  hello_buildstream
+
+[--:--:--][][] START   Loading elements
+[00:00:00][][] SUCCESS Loading elements
+[--:--:--][][] START   Resolving elements
+[00:00:00][][] SUCCESS Resolving elements
+[--:--:--][][] START   Resolving cached state
+[00:00:00][][] SUCCESS Resolving cached state
+[--:--:--][f7b50d8b][ main:sourceroot.bst                ] START   Staging dependencies
+[00:00:00][f7b50d8b][ main:sourceroot.bst                ] SUCCESS Staging dependencies
+[--:--:--][f7b50d8b][ main:sourceroot.bst                ] START   Integrating sandbox
+[00:00:00][f7b50d8b][ main:sourceroot.bst                ] SUCCESS Integrating sandbox
+[--:--:--][f7b50d8b][ main:sourceroot.bst                ] STATUS  Running command
+
+    hello_buildstream
+
+Hello, World! Built from the source root.
+
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 000000000..a4879248a --- /dev/null +++ b/doc/source/sessions-stored/out-of-source-build-show-variables.html @@ -0,0 +1,64 @@ + +
+user@host:~/out-of-source-build$ bst show --deps none --format "%{vars}" sourceroot.bst
+
+[--:--:--][][] START   Loading elements
+[00:00:00][][] SUCCESS Loading elements
+[--:--:--][][] START   Resolving elements
+[00:00:00][][] SUCCESS Resolving elements
+[--:--:--][][] START   Resolving cached state
+[00:00:00][][] SUCCESS Resolving cached state
+bindir: /usr/bin
+build-dir: _builddir
+build-root: /buildstream/cmake-out-of-source-build/sourceroot.bst
+cmake: "cmake -B_builddir -H\"/buildstream/cmake-out-of-source-build/sourceroot.bst/Source/src\"\
+  \ -G\"Unix Makefiles\" -DCMAKE_INSTALL_PREFIX:PATH=\"/usr\" \\\n-DCMAKE_INSTALL_LIBDIR=lib\
+  \   "
+cmake-args: "-DCMAKE_INSTALL_PREFIX:PATH=\"/usr\" \\\n-DCMAKE_INSTALL_LIBDIR=lib"
+cmake-extra: ''
+cmake-global: ''
+cmake-local: ''
+command-subdir: build
+conf-root: /buildstream/cmake-out-of-source-build/sourceroot.bst/Source/src
+datadir: /usr/share
+debugdir: /usr/lib/debug
+docdir: /usr/share/doc
+element-name: sourceroot.bst
+exec_prefix: /usr
+fix-pyc-timestamps: "find \"/buildstream-install\" -name '*.pyc' -exec \\\n  dd if=/dev/zero\
+  \ of={} bs=1 count=4 seek=4 conv=notrunc ';'"
+generator: Unix Makefiles
+includedir: /usr/include
+infodir: /usr/share/info
+install-root: /buildstream-install
+lib: lib
+libdir: /usr/lib
+libexecdir: /usr/libexec
+localstatedir: /var
+make: cmake --build _builddir -- ${JOBS}
+make-install: env DESTDIR="/buildstream-install" cmake --build _builddir --target
+  install
+mandir: /usr/share/man
+max-jobs: '4'
+objcopy-extract-args: --only-keep-debug --compress-debug-sections
+objcopy-link-args: --add-gnu-debuglink
+prefix: /usr
+project-name: cmake-out-of-source-build
+sbindir: /usr/sbin
+sharedstatedir: /usr/com
+strip-args: --remove-section=.comment --remove-section=.note --strip-unneeded
+strip-binaries: "cd \"/buildstream-install\" && find -type f \\\n  '(' -perm -111\
+  \ -o -name '*.so*' \\\n      -o -name '*.cmxs' -o -name '*.node' ')' \\\n  -exec\
+  \ sh -ec \\\n  'read -n4 hdr <\"$1\" # check for elf header\n   case \"$1\" in\n\
+  \     /buildstream-install/usr/lib/debug/*)\n       exit 0\n       ;;\n   esac\n\
+  \   if [ \"$hdr\" != \"$(printf \\\\x7fELF)\" ]; then\n       exit 0\n   fi\n  \
+  \ debugfile=\"/buildstream-install/usr/lib/debug/$1\"\n   mkdir -p \"$(dirname \"\
+  $debugfile\")\"\n   objcopy --only-keep-debug --compress-debug-sections \"$1\" \"\
+  $debugfile\"\n   chmod 644 \"$debugfile\"\n   strip --remove-section=.comment --remove-section=.note\
+  \ --strip-unneeded \"$1\"\n   objcopy --add-gnu-debuglink \"$debugfile\" \"$1\"\
+  ' - {} ';'"
+sysconfdir: /etc
+
+
diff --git a/doc/source/using_examples.rst b/doc/source/using_examples.rst index 18b15c711..6cbca2f6a 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 000000000..7f5c266b9 --- /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! Built from the source root.\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! Built from a subdirectory of the source.\n' -- cgit v1.2.1