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:46:45 UTC
[buildstream] 01/04: WIP: Use freedesktop-sdk as a base for
tutorials as much as possible
This is an automated email from the ASF dual-hosted git repository.
root pushed a commit to branch tlater/freedocstop-sdk
in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit d608e92a48f21fd4ecacde416f0b8ea3fdd2f562
Author: Tristan Maat <tr...@codethink.co.uk>
AuthorDate: Fri Apr 5 18:05:06 2019 +0100
WIP: Use freedesktop-sdk as a base for tutorials as much as possible
WIP because:
[] - We need to introduce a buildstream docs cache since this takes
ages to compile.
[] - I'm not happy with the integration-commands doc - I *should* add
another nested dependency.
[] - Session output has not yet been updated - this will need to be
done post-cache implementation.
---
.../autotools/elements/freedesktop-sdk.bst | 9 ++
.../autotools/elements/hello.bst | 4 +-
.../autotools/project.conf | 14 +-
.../elements/callHello.bst | 0
.../elements/freedesktop-sdk.bst | 9 ++
.../elements/hello-junction.bst | 0
.../elements/hello.bst} | 8 +-
.../files/callHello.sh | 0
doc/examples/advanced-junctions/files/src/Makefile | 12 ++
doc/examples/advanced-junctions/files/src/hello.c | 10 ++
.../{junctions => advanced-junctions}/project.conf | 11 ++
doc/examples/autotools/elements/base.bst | 5 -
doc/examples/autotools/elements/base/alpine.bst | 13 --
.../autotools/elements/freedesktop-sdk.bst | 9 ++
doc/examples/autotools/elements/hello.bst | 4 +-
doc/examples/autotools/project.conf | 12 +-
.../integration-commands/elements/base.bst | 5 -
.../integration-commands/elements/base/alpine.bst | 17 ---
.../elements/freedesktop-sdk.bst | 9 ++
.../integration-commands/elements/libhello.bst | 7 +-
doc/examples/integration-commands/project.conf | 13 +-
doc/examples/junctions/autotools/elements/base.bst | 5 -
.../junctions/autotools/elements/base/alpine.bst | 13 --
.../junctions/elements/freedesktop-sdk.bst | 9 ++
.../libhello.bst => junctions/elements/hello.bst} | 8 +-
doc/examples/junctions/files/src/Makefile | 12 ++
doc/examples/junctions/files/src/hello.c | 10 ++
doc/examples/junctions/project.conf | 11 ++
doc/sessions/advanced-junctions.run | 20 +++
doc/sessions/junctions.run | 35 +++--
doc/source/advanced-features/junction-elements.rst | 17 +--
doc/source/tutorial/autotools.rst | 10 +-
doc/source/tutorial/integration-commands.rst | 38 +++--
doc/source/tutorial/junctions.rst | 158 +++++++++++++++++++++
doc/source/tutorial/running-commands.rst | 7 +
doc/source/using_tutorial.rst | 1 +
tests/examples/advanced-junctions.py | 54 +++++++
37 files changed, 455 insertions(+), 124 deletions(-)
diff --git a/doc/examples/advanced-junctions/autotools/elements/freedesktop-sdk.bst b/doc/examples/advanced-junctions/autotools/elements/freedesktop-sdk.bst
new file mode 100644
index 0000000..9fe54d4
--- /dev/null
+++ b/doc/examples/advanced-junctions/autotools/elements/freedesktop-sdk.bst
@@ -0,0 +1,9 @@
+kind: junction
+sources:
+- kind: git
+ url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/
+ track: '18.08'
+ ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82
+config:
+ options:
+ target_arch: '%{arch}'
diff --git a/doc/examples/junctions/autotools/elements/hello.bst b/doc/examples/advanced-junctions/autotools/elements/hello.bst
similarity index 88%
rename from doc/examples/junctions/autotools/elements/hello.bst
rename to doc/examples/advanced-junctions/autotools/elements/hello.bst
index ce3ea74..7950a3a 100644
--- a/doc/examples/junctions/autotools/elements/hello.bst
+++ b/doc/examples/advanced-junctions/autotools/elements/hello.bst
@@ -18,4 +18,6 @@ sources:
ref: 80da43bb5665596ee389e6d8b64b4f122ea4b92a685b1dbd813cd1f0e0c2d83f
depends:
-- base.bst
+- freedesktop-sdk.bst:public-stacks/buildsystems.bst
+
+
diff --git a/doc/examples/junctions/autotools/project.conf b/doc/examples/advanced-junctions/autotools/project.conf
similarity index 52%
rename from doc/examples/junctions/autotools/project.conf
rename to doc/examples/advanced-junctions/autotools/project.conf
index 2cf5824..964d974 100644
--- a/doc/examples/junctions/autotools/project.conf
+++ b/doc/examples/advanced-junctions/autotools/project.conf
@@ -9,5 +9,15 @@ element-path: elements
# Define some aliases for the tarballs we download
aliases:
- alpine: https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/
- gnu: https://ftpmirror.gnu.org/gnu/automake/
+ gnu: http://ftpmirror.gnu.org/gnu/automake/
+
+options:
+ arch:
+ type: arch
+ description: Machine architecture
+ variable: arch
+ values:
+ - arm
+ - aarch64
+ - i686
+ - x86_64
diff --git a/doc/examples/junctions/elements/callHello.bst b/doc/examples/advanced-junctions/elements/callHello.bst
similarity index 100%
rename from doc/examples/junctions/elements/callHello.bst
rename to doc/examples/advanced-junctions/elements/callHello.bst
diff --git a/doc/examples/advanced-junctions/elements/freedesktop-sdk.bst b/doc/examples/advanced-junctions/elements/freedesktop-sdk.bst
new file mode 100644
index 0000000..9fe54d4
--- /dev/null
+++ b/doc/examples/advanced-junctions/elements/freedesktop-sdk.bst
@@ -0,0 +1,9 @@
+kind: junction
+sources:
+- kind: git
+ url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/
+ track: '18.08'
+ ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82
+config:
+ options:
+ target_arch: '%{arch}'
diff --git a/doc/examples/junctions/elements/hello-junction.bst b/doc/examples/advanced-junctions/elements/hello-junction.bst
similarity index 100%
rename from doc/examples/junctions/elements/hello-junction.bst
rename to doc/examples/advanced-junctions/elements/hello-junction.bst
diff --git a/doc/examples/integration-commands/elements/libhello.bst b/doc/examples/advanced-junctions/elements/hello.bst
similarity index 62%
copy from doc/examples/integration-commands/elements/libhello.bst
copy to doc/examples/advanced-junctions/elements/hello.bst
index 53496c8..dc4db56 100644
--- a/doc/examples/integration-commands/elements/libhello.bst
+++ b/doc/examples/advanced-junctions/elements/hello.bst
@@ -1,16 +1,16 @@
kind: manual
description: |
- The libhello library
+ Building using freedesktop-sdk as a base
# Depend on the base system
depends:
-- base.bst
+ - freedesktop-sdk.bst:public-stacks/buildsystems.bst
-# Stage the files/libhello directory for building
+# Stage the files/src directory for building
sources:
- kind: local
- path: files/libhello
+ path: files/src
# Now configure the commands to run
config:
diff --git a/doc/examples/junctions/files/callHello.sh b/doc/examples/advanced-junctions/files/callHello.sh
similarity index 100%
rename from doc/examples/junctions/files/callHello.sh
rename to doc/examples/advanced-junctions/files/callHello.sh
diff --git a/doc/examples/advanced-junctions/files/src/Makefile b/doc/examples/advanced-junctions/files/src/Makefile
new file mode 100644
index 0000000..8c84251
--- /dev/null
+++ b/doc/examples/advanced-junctions/files/src/Makefile
@@ -0,0 +1,12 @@
+# Sample makefile for hello.c
+#
+.PHONY: all install
+
+all: hello
+
+install:
+ install -d ${DESTDIR}${PREFIX}/bin
+ install -m 755 hello ${DESTDIR}${PREFIX}/bin
+
+hello: hello.c
+ $(CC) -Wall -o $@ $<
diff --git a/doc/examples/advanced-junctions/files/src/hello.c b/doc/examples/advanced-junctions/files/src/hello.c
new file mode 100644
index 0000000..b534082
--- /dev/null
+++ b/doc/examples/advanced-junctions/files/src/hello.c
@@ -0,0 +1,10 @@
+/*
+ * hello.c - Simple hello world program
+ */
+#include <stdio.h>
+
+int main(int argc, char *argv[])
+{
+ printf("Hello World\n");
+ return 0;
+}
diff --git a/doc/examples/junctions/project.conf b/doc/examples/advanced-junctions/project.conf
similarity index 50%
copy from doc/examples/junctions/project.conf
copy to doc/examples/advanced-junctions/project.conf
index 7f8ca6a..d10c25c 100644
--- a/doc/examples/junctions/project.conf
+++ b/doc/examples/advanced-junctions/project.conf
@@ -6,3 +6,14 @@ format-version: 9
# Subdirectory where elements are stored
element-path: elements
+
+options:
+ arch:
+ type: arch
+ description: Machine architecture
+ variable: arch
+ values:
+ - arm
+ - aarch64
+ - i686
+ - x86_64
diff --git a/doc/examples/autotools/elements/base.bst b/doc/examples/autotools/elements/base.bst
deleted file mode 100644
index 1b85a9e..0000000
--- a/doc/examples/autotools/elements/base.bst
+++ /dev/null
@@ -1,5 +0,0 @@
-kind: stack
-description: Base stack
-
-depends:
-- base/alpine.bst
diff --git a/doc/examples/autotools/elements/base/alpine.bst b/doc/examples/autotools/elements/base/alpine.bst
deleted file mode 100644
index cf85df5..0000000
--- a/doc/examples/autotools/elements/base/alpine.bst
+++ /dev/null
@@ -1,13 +0,0 @@
-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/autotools/elements/freedesktop-sdk.bst b/doc/examples/autotools/elements/freedesktop-sdk.bst
new file mode 100644
index 0000000..9fe54d4
--- /dev/null
+++ b/doc/examples/autotools/elements/freedesktop-sdk.bst
@@ -0,0 +1,9 @@
+kind: junction
+sources:
+- kind: git
+ url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/
+ track: '18.08'
+ ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82
+config:
+ options:
+ target_arch: '%{arch}'
diff --git a/doc/examples/autotools/elements/hello.bst b/doc/examples/autotools/elements/hello.bst
index ce3ea74..7950a3a 100644
--- a/doc/examples/autotools/elements/hello.bst
+++ b/doc/examples/autotools/elements/hello.bst
@@ -18,4 +18,6 @@ sources:
ref: 80da43bb5665596ee389e6d8b64b4f122ea4b92a685b1dbd813cd1f0e0c2d83f
depends:
-- base.bst
+- freedesktop-sdk.bst:public-stacks/buildsystems.bst
+
+
diff --git a/doc/examples/autotools/project.conf b/doc/examples/autotools/project.conf
index 96e0284..964d974 100644
--- a/doc/examples/autotools/project.conf
+++ b/doc/examples/autotools/project.conf
@@ -9,5 +9,15 @@ element-path: elements
# Define some aliases for the tarballs we download
aliases:
- alpine: https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/
gnu: http://ftpmirror.gnu.org/gnu/automake/
+
+options:
+ arch:
+ type: arch
+ description: Machine architecture
+ variable: arch
+ values:
+ - arm
+ - aarch64
+ - i686
+ - x86_64
diff --git a/doc/examples/integration-commands/elements/base.bst b/doc/examples/integration-commands/elements/base.bst
deleted file mode 100644
index 1b85a9e..0000000
--- a/doc/examples/integration-commands/elements/base.bst
+++ /dev/null
@@ -1,5 +0,0 @@
-kind: stack
-description: Base stack
-
-depends:
-- base/alpine.bst
diff --git a/doc/examples/integration-commands/elements/base/alpine.bst b/doc/examples/integration-commands/elements/base/alpine.bst
deleted file mode 100644
index 433f477..0000000
--- a/doc/examples/integration-commands/elements/base/alpine.bst
+++ /dev/null
@@ -1,17 +0,0 @@
-kind: import
-description: |
-
- Alpine Linux base runtime
-
-sources:
-- kind: tar
- url: alpine:integration-tests-base.v1.x86_64.tar.xz
- ref: 3eb559250ba82b64a68d86d0636a6b127aa5f6d25d3601a79f79214dc9703639
-
-#
-# Run ldconfig in the libdir before running anything
-#
-public:
- bst:
- integration-commands:
- - ldconfig "%{libdir}"
diff --git a/doc/examples/integration-commands/elements/freedesktop-sdk.bst b/doc/examples/integration-commands/elements/freedesktop-sdk.bst
new file mode 100644
index 0000000..9fe54d4
--- /dev/null
+++ b/doc/examples/integration-commands/elements/freedesktop-sdk.bst
@@ -0,0 +1,9 @@
+kind: junction
+sources:
+- kind: git
+ url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/
+ track: '18.08'
+ ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82
+config:
+ options:
+ target_arch: '%{arch}'
diff --git a/doc/examples/integration-commands/elements/libhello.bst b/doc/examples/integration-commands/elements/libhello.bst
index 53496c8..a184b21 100644
--- a/doc/examples/integration-commands/elements/libhello.bst
+++ b/doc/examples/integration-commands/elements/libhello.bst
@@ -5,7 +5,7 @@ description: |
# Depend on the base system
depends:
-- base.bst
+- freedesktop-sdk.bst:public-stacks/buildsystems.bst
# Stage the files/libhello directory for building
sources:
@@ -20,3 +20,8 @@ config:
install-commands:
- make -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install
+
+public:
+ bst:
+ integration-commands:
+ - ldconfig "%{libdir}"
diff --git a/doc/examples/integration-commands/project.conf b/doc/examples/integration-commands/project.conf
index 9ae5b2a..0aaf5d5 100644
--- a/doc/examples/integration-commands/project.conf
+++ b/doc/examples/integration-commands/project.conf
@@ -7,6 +7,13 @@ format-version: 9
# Subdirectory where elements are stored
element-path: elements
-# Define an alias for our alpine tarball
-aliases:
- alpine: https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/
+options:
+ arch:
+ type: arch
+ description: Machine architecture
+ variable: arch
+ values:
+ - arm
+ - aarch64
+ - i686
+ - x86_64
diff --git a/doc/examples/junctions/autotools/elements/base.bst b/doc/examples/junctions/autotools/elements/base.bst
deleted file mode 100644
index 1b85a9e..0000000
--- a/doc/examples/junctions/autotools/elements/base.bst
+++ /dev/null
@@ -1,5 +0,0 @@
-kind: stack
-description: Base stack
-
-depends:
-- base/alpine.bst
diff --git a/doc/examples/junctions/autotools/elements/base/alpine.bst b/doc/examples/junctions/autotools/elements/base/alpine.bst
deleted file mode 100644
index cf85df5..0000000
--- a/doc/examples/junctions/autotools/elements/base/alpine.bst
+++ /dev/null
@@ -1,13 +0,0 @@
-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/junctions/elements/freedesktop-sdk.bst b/doc/examples/junctions/elements/freedesktop-sdk.bst
new file mode 100644
index 0000000..9fe54d4
--- /dev/null
+++ b/doc/examples/junctions/elements/freedesktop-sdk.bst
@@ -0,0 +1,9 @@
+kind: junction
+sources:
+- kind: git
+ url: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/
+ track: '18.08'
+ ref: ddde36212f574fbdb66b5cca3d4b411aec22ee82
+config:
+ options:
+ target_arch: '%{arch}'
diff --git a/doc/examples/integration-commands/elements/libhello.bst b/doc/examples/junctions/elements/hello.bst
similarity index 62%
copy from doc/examples/integration-commands/elements/libhello.bst
copy to doc/examples/junctions/elements/hello.bst
index 53496c8..dc4db56 100644
--- a/doc/examples/integration-commands/elements/libhello.bst
+++ b/doc/examples/junctions/elements/hello.bst
@@ -1,16 +1,16 @@
kind: manual
description: |
- The libhello library
+ Building using freedesktop-sdk as a base
# Depend on the base system
depends:
-- base.bst
+ - freedesktop-sdk.bst:public-stacks/buildsystems.bst
-# Stage the files/libhello directory for building
+# Stage the files/src directory for building
sources:
- kind: local
- path: files/libhello
+ path: files/src
# Now configure the commands to run
config:
diff --git a/doc/examples/junctions/files/src/Makefile b/doc/examples/junctions/files/src/Makefile
new file mode 100644
index 0000000..8c84251
--- /dev/null
+++ b/doc/examples/junctions/files/src/Makefile
@@ -0,0 +1,12 @@
+# Sample makefile for hello.c
+#
+.PHONY: all install
+
+all: hello
+
+install:
+ install -d ${DESTDIR}${PREFIX}/bin
+ install -m 755 hello ${DESTDIR}${PREFIX}/bin
+
+hello: hello.c
+ $(CC) -Wall -o $@ $<
diff --git a/doc/examples/junctions/files/src/hello.c b/doc/examples/junctions/files/src/hello.c
new file mode 100644
index 0000000..b534082
--- /dev/null
+++ b/doc/examples/junctions/files/src/hello.c
@@ -0,0 +1,10 @@
+/*
+ * hello.c - Simple hello world program
+ */
+#include <stdio.h>
+
+int main(int argc, char *argv[])
+{
+ printf("Hello World\n");
+ return 0;
+}
diff --git a/doc/examples/junctions/project.conf b/doc/examples/junctions/project.conf
index 7f8ca6a..d10c25c 100644
--- a/doc/examples/junctions/project.conf
+++ b/doc/examples/junctions/project.conf
@@ -6,3 +6,14 @@ format-version: 9
# Subdirectory where elements are stored
element-path: elements
+
+options:
+ arch:
+ type: arch
+ description: Machine architecture
+ variable: arch
+ values:
+ - arm
+ - aarch64
+ - i686
+ - x86_64
diff --git a/doc/sessions/advanced-junctions.run b/doc/sessions/advanced-junctions.run
new file mode 100644
index 0000000..28578a8
--- /dev/null
+++ b/doc/sessions/advanced-junctions.run
@@ -0,0 +1,20 @@
+
+ commands:
+# Build callHello.bst
+ - directory: ../examples/junctions
+ output: ../source/sessions/junctions-build.html
+ command: build callHello.bst
+
+# Run callHello.sh in a shell
+ - directory: ../examples/junctions
+ output: ../source/sessions/junctions-shell.html
+ command: shell callHello.bst -- /bin/sh callHello.sh
+
+# Open a crossJunction workspace:
+ - directory: ../examples/junctions
+ output: ../source/sessions/junctions-workspace-open.html
+ command: workspace open --directory workspace_hello hello-junction.bst:hello.bst
+
+# Remove the workspace
+ - directory: ../examples/junctions
+ command: workspace close --remove-dirs hello-junction.bst:hello.bst
diff --git a/doc/sessions/junctions.run b/doc/sessions/junctions.run
index 74c3a4f..4b03271 100644
--- a/doc/sessions/junctions.run
+++ b/doc/sessions/junctions.run
@@ -1,20 +1,25 @@
commands:
-# Build callHello.bst
-- directory: ../examples/junctions
- output: ../source/sessions/junctions-build.html
- command: build callHello.bst
+# We need to fetch the junction
+- directory: ../examples/advanced-junctions
+ command: source fetch freedesktop-sdk.bst
-# Run callHello.sh in a shell
-- directory: ../examples/junctions
- output: ../source/sessions/junctions-shell.html
- command: shell callHello.bst -- /bin/sh callHello.sh
+# We want to show the project contents
+- directory: ../examples/advanced-junctions
+ command: show hello.bst
+ output: ../source/sessions/advanced-junctions-show-before.html
-# Open a crossJunction workspace:
-- directory: ../examples/junctions
- output: ../source/sessions/junctions-workspace-open.html
- command: workspace open --directory workspace_hello hello-junction.bst:hello.bst
+# We want to build the project
+- directory: ../examples/advanced-junctions
+ command: build hello.bst
+ output: ../source/sessions/advanced-junctions-build.html
-# Remove the workspace
-- directory: ../examples/junctions
- command: workspace close --remove-dirs hello-junction.bst:hello.bst
+# We want to show post-build show output
+- directory: ../examples/advanced-junctions
+ command: show hello.bst
+ output: ../source/sessions/advanced-junctions-show-after.html
+
+# We want to show the application running
+- directory: ../examples/advanced-junctions
+ command: run hello.bst -- hello
+ output: ../source/sessions/advanced-junctions-shell.html
diff --git a/doc/source/advanced-features/junction-elements.rst b/doc/source/advanced-features/junction-elements.rst
index b6065d3..521c4c0 100644
--- a/doc/source/advanced-features/junction-elements.rst
+++ b/doc/source/advanced-features/junction-elements.rst
@@ -13,16 +13,16 @@ A simple example
.. note::
This example is distributed with BuildStream in the
- `doc/examples/junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions>`_
+ `doc/examples/advanced-junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/advanced-junctions>`_
subdirectory.
Below is a simple example of bst file for a junction element:
-.. literalinclude:: ../../examples/junctions/elements/hello-junction.bst
+.. literalinclude:: ../../examples/advanced-junctions/elements/hello-junction.bst
:language: yaml
This element imports the autotools example subproject found in the
-BuildStream doc/examples/junctions/autotools subdirectory.
+BuildStream doc/examples/advanced-junctions/autotools subdirectory.
.. note::
@@ -33,7 +33,7 @@ BuildStream doc/examples/junctions/autotools subdirectory.
The below bst file describes an element which depends on the hello.bst element
from the autotools example:
-.. literalinclude:: ../../examples/junctions/elements/callHello.bst
+.. literalinclude:: ../../examples/advanced-junctions/elements/callHello.bst
:language: yaml
This element consists of a script which calls hello.bst's hello command.
@@ -41,7 +41,7 @@ This element consists of a script which calls hello.bst's hello command.
Building callHello.bst,
.. raw:: html
- :file: ../sessions/junctions-build.html
+ :file: ../sessions/advanced-junctions-build.html
You can see that the hello.bst element and its dependencies from the autotools
project have been build as part of the pipeline for callHello.bst.
@@ -49,7 +49,7 @@ project have been build as part of the pipeline for callHello.bst.
We can now invoke `bst shell`
.. raw:: html
- :file: ../sessions/junctions-shell.html
+ :file: ../sessions/advanced-junctions-shell.html
This runs the script files/callHello.sh which will makes use of the hello command from the hello.bst element in the autotools project.
@@ -59,8 +59,9 @@ Cross-junction workspaces
You can open workspaces for elements in the project refered to by the junction
using the syntax `bst open ${junction-name}:{element-name}`. In this example,
-.. raw:: html
- :file: ../sessions/junctions-workspace-open.html
+..
+ .. raw:: html
+ :file: ../sessions/advanced-junctions-workspace-open.html
This has opened a workspace for the hello.bst element from the autotools project.
This workspace can now be used as normal.
diff --git a/doc/source/tutorial/autotools.rst b/doc/source/tutorial/autotools.rst
index ea28358..8a01e6e 100644
--- a/doc/source/tutorial/autotools.rst
+++ b/doc/source/tutorial/autotools.rst
@@ -2,7 +2,7 @@
Using the autotools element
===========================
-In :ref:`the last chapter <tutorial_running_commands>` we observed how the
+In :ref:`the previous chapters <tutorial_junctions>` we observed how the
:mod:`manual <elements.manual>` element works, allowing one to specify and
run commands manually in the process of constructing an *artifact*.
@@ -47,10 +47,10 @@ added another :ref:`source alias <project_source_aliases>` for ``gnu``, the loca
from which we're going to download the ``automake`` tarball.
-``elements/base/alpine.bst`` and ``elements/base.bst``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The alpine base and base stack element are defined in the
-same way as in the last chapter: :ref:`tutorial_running_commands`.
+``elements/freedesktop-sdk.bst``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The freedesktop-sdk junction is defined in the same way as in the last
+chapter: :ref:`tutorial_running_commands`.
``elements/hello.bst``
diff --git a/doc/source/tutorial/integration-commands.rst b/doc/source/tutorial/integration-commands.rst
index ead5be8..7f31407 100644
--- a/doc/source/tutorial/integration-commands.rst
+++ b/doc/source/tutorial/integration-commands.rst
@@ -31,20 +31,21 @@ Project structure
-----------------
-``project.conf`` and ``elements/base.bst``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The project.conf and base stack :mod:`stack <elements.stack>` element are configured in the
+``project.conf`` and ``elements/freedesktop-sdk.bst``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The project.conf and freedesktop-sdk element are configured in the
same way as in the previous chapter: :ref:`tutorial_running_commands`.
-``elements/base/alpine.bst``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``elements/libhello.bst``
+~~~~~~~~~~~~~~~~~~~~~~~~~
-.. literalinclude:: ../../examples/integration-commands/elements/base/alpine.bst
+.. literalinclude:: ../../examples/integration-commands/elements/libhello.bst
:language: yaml
-This is the same ``base/alpine.bst`` we've seen in previous chapters,
-except that we've added an :ref:`integration command <public_integration>`.
+This is a simple library to be used by ``elements/hello.bst`` - it is
+very similar to elements we have already seen, except that we have
+added an :ref:`integration command <public_integration>`.
This informs BuildStream that whenever the output of this element is
expected to *run*, this command should be run first. In this case we
@@ -67,16 +68,11 @@ the dependency chain about details of its artifact, or to suggest how
it should be processed.
-``elements/libhello.bst`` and ``elements/hello.bst``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These are basically manual elements very similar to the ones we've
-seen in the previous chapter: :ref:`tutorial_running_commands`.
+``elements/hello.bst``
+~~~~~~~~~~~~~~~~~~~~~~
-These produce a library and a hello program which uses the library,
-we will consider these irrelevant to the topic and leave examination
-of `their sources
-<https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/integration-commands/files>`_
-as an exercise for the reader.
+This is, in essence, the same element we have seen in the previous
+chapter: :ref:`tutorial_running_commands`.
Using the project
@@ -91,10 +87,10 @@ following way:
.. raw:: html
:file: ../sessions/integration-commands-build.html
-Observe in the build process above, the integration command declared on the
-``base/alpine.bst`` element is run after staging the dependency artifacts
-into the build sandbox and before running any of the build commands, for
-both of the ``libhello.bst`` and ``hello.bst`` elements.
+Observe in the build process above, the integration command declared
+on the ``libhello.bst`` element is run after staging the dependency
+artifacts into the build sandbox and before running any of the build
+commands.
BuildStream assumes that commands which are to be run in the build sandbox
need to be run in an *integrated* sandbox.
diff --git a/doc/source/tutorial/junctions.rst b/doc/source/tutorial/junctions.rst
new file mode 100644
index 0000000..dd4bb08
--- /dev/null
+++ b/doc/source/tutorial/junctions.rst
@@ -0,0 +1,158 @@
+.. _tutorial_junctions:
+
+Depending on other BuildStream projects
+=======================================
+In :ref:`the last chapter <tutorial_running_commands>` we saw how
+BuildStream can be used to compile a simple C project. We used a
+slightly modified Alpine tarball for this.
+
+While this works, and is not an uncommon practice, this way we lose
+out on some of BuildStream's features, and cannot necessarily
+reproduce the whole system from scratch. We would also need to supply
+different base images for different architectures if we wanted to
+support more than ``x86_64``. It would be better if we could use
+BuildStream elements to build everything from scratch, but this would
+take a lot of effort.
+
+Instead, in this chapter, we will introduce the concept of "junctions"
+that allow us to depend on other BuildStream projects, so that we can
+have a definition of the whole system without needing to specify every
+detail ourselves.
+
+.. note::
+
+ This example is distributed with BuildStream
+ in the `doc/examples/junctions
+ <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/autotools>`_
+ subdirectory.
+
+
+Overview
+--------
+In this example we will replace the ``elements/base.bst`` and
+``elements/base/alpine.bst`` elements with a junction to
+`freedesktop-sdk <https://freedesktop-sdk.io/>`_.
+
+
+Project structure
+-----------------
+
+For this project, we will only use two element declarations, and the
+usual ``project.conf``, with some slight modifications.
+
+If we look at what this project builds using :ref:`bst show
+<invoking_show>` we will see a pipeline with a lot more elements than
+we defined:
+
+..
+ .. raw:: html
+ :file: ../sessions/junctions-show-before.html
+
+.. note::
+
+ You will likely need to fetch the freedesktop-sdk project first. To
+ do so, simply run ``bst source fetch freedesktop-sdk.bst`` as
+ suggested.
+
+This is because we use a number of elements from the freedesktop-sdk
+junction. Those are clearly marked with a ``freedesktop-sdk:``
+prefix. In fact, the only element we seem to define is ``hello.bst``.
+
+Let's explain the files that we do define:
+
+.. _tutorial_junctions_project_conf:
+
+
+``project.conf``
+~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/junctions/project.conf
+ :language: yaml
+
+freedesktop-sdk provides bindings for multiple architectures, but to
+use these we need to add an :ref:`option <project_options>` to
+``project.conf``. We define options for ``arm``, ``aarch64``, ``i686``
+and ``x86_64``. BuildStream will automatically pick the correct
+architecture for our system.
+
+
+``elements/freedesktop-sdk.bst``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/junctions/elements/freedesktop-sdk.bst
+ :language: yaml
+
+This is the magic element that allows us to access elements from
+another project. We instruct BuildStream to clone the freedesktop-sdk
+project and use its ``18.08`` branch, which is the recommended version
+at the time of writing this guide.
+
+We also set the ``target_arch`` option to the option we defined in
+``project.conf`` - if we only wanted to target one architecture, we
+could specify a specific architecture here.
+
+
+``elements/hello.bst``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../examples/junctions/elements/hello.bst
+ :language: yaml
+
+Finally, we modify our build element. We replace our Alpine-based base
+system with an element from freedesktop sdk -
+`public-stacks/buildsystems.bst
+<https://gitlab.com/freedesktop-sdk/freedesktop-sdk/blob/master/elements/public-stacks/buildsystems.bst>`_. We
+do this using a normal dependency, but we specify the junction from
+which to take the element by prepending the element name with
+``freedesktop-sdk.bst``, which refers to our junction element.
+
+Since the ``freedesktop-sdk.bst:public-stacks/buildsystems.bst``
+element provides all runtime components we need for our build, just
+like alpine did, we need to make no other changes.
+
+Using the project
+-----------------
+
+This project can be used in exactly the same way the
+:ref:`running_commands <tutorial_running_commands>` project was used -
+we build and run ``hello.bst``. The difference is that ``bst show``
+will now list every individual component, as we saw earlier.
+
+Build the hello.bst element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To build the project, run :ref:`bst build <invoking_build>` in the
+following way:
+
+..
+ .. raw:: html
+ :file: ../sessions/junctions-build.html
+
+BuildStream will automatically build elements provided by the
+freedesktop-sdk project, and even download ready-made binaries
+wherever possible. It then uses ``make`` and the C compiler provided
+by freedesktop-sdk to build our hello world program.
+
+All the elements, including the freedesktop-sdk elements, will now
+show up as ``cached`` in the pipeline:
+
+..
+ .. raw:: html
+ :file: ../sessions/junctions-show-after.html
+
+Run the hello world program
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just like in the previous example, we can run our program using
+:ref:`bst shell <invoking_shell>`:
+
+..
+ .. raw:: html
+ :file: ../sessions/junctions-shell.html
+
+Summary
+-------
+
+In this chapter we introduced the concept of project junctions, and
+explained how they can be used to define a basic sysroot that is
+transparent to buildstream.
diff --git a/doc/source/tutorial/running-commands.rst b/doc/source/tutorial/running-commands.rst
index 1708145..7e164c6 100644
--- a/doc/source/tutorial/running-commands.rst
+++ b/doc/source/tutorial/running-commands.rst
@@ -92,6 +92,13 @@ This tarball is a sysroot which provides the C runtime libraries
and some programs - this is what will be providing the programs we're
going to run in this example.
+.. note::
+
+ This alpine sysroot will only work on ``x86_64`` systems, so don't
+ panic if you are using a different architecture! The `next chapter
+ <tutorial_junctions>` will go over an alternative that resolves
+ this problem.
+
``elements/base.bst``
~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/source/using_tutorial.rst b/doc/source/using_tutorial.rst
index 297f234..20a3e08 100644
--- a/doc/source/using_tutorial.rst
+++ b/doc/source/using_tutorial.rst
@@ -14,5 +14,6 @@ projects.
tutorial/first-project
tutorial/running-commands
+ tutorial/junctions
tutorial/autotools
tutorial/integration-commands
diff --git a/tests/examples/advanced-junctions.py b/tests/examples/advanced-junctions.py
new file mode 100644
index 0000000..536523c
--- /dev/null
+++ b/tests/examples/advanced-junctions.py
@@ -0,0 +1,54 @@
+# Pylint doesn't play well with fixtures and dependency injection from pytest
+# pylint: disable=redefined-outer-name
+
+import os
+import pytest
+
+from buildstream.testing import cli_integration as cli # pylint: disable=unused-import
+from buildstream.testing._utils.site import IS_LINUX, HAVE_BWRAP
+
+pytestmark = pytest.mark.integration
+
+DATA_DIR = os.path.join(
+ os.path.dirname(os.path.realpath(__file__)), '..', '..', 'doc', 'examples', 'advanced-junctions'
+)
+
+
+# Test that the project builds successfully
+# @pytest.mark.skipif(not IS_LINUX or not HAVE_BWRAP, reason='Only available on linux with bubblewrap')
+@pytest.mark.datafiles(DATA_DIR)
+def test_build(cli, datafiles):
+ project = str(datafiles)
+
+ result = cli.run(project=project, args=['build', 'callHello.bst'])
+ result.assert_success()
+
+
+# Test the callHello script works as expected.
+# @pytest.mark.skipif(not IS_LINUX or not HAVE_BWRAP, reason='Only available on linux with bubblewrap')
+@pytest.mark.datafiles(DATA_DIR)
+def test_shell_call_hello(cli, datafiles):
+ project = str(datafiles)
+
+ result = cli.run(project=project, args=['build', 'callHello.bst'])
+ result.assert_success()
+
+ result = cli.run(project=project, args=['shell', 'callHello.bst', '--', '/bin/sh', 'callHello.sh'])
+ result.assert_success()
+ assert result.output == 'Calling hello:\nHello World!\nThis is amhello 1.0.\n'
+
+
+# Test opening a cross-junction workspace
+# @pytest.mark.skipif(not IS_LINUX, reason='Only available on linux')
+@pytest.mark.datafiles(DATA_DIR)
+def test_open_cross_junction_workspace(cli, tmpdir, datafiles):
+ project = str(datafiles)
+ workspace_dir = os.path.join(str(tmpdir), "workspace_hello_junction")
+
+ result = cli.run(project=project,
+ args=['workspace', 'open', '--directory', workspace_dir, 'hello-junction.bst:hello.bst'])
+ result.assert_success()
+
+ result = cli.run(project=project,
+ args=['workspace', 'close', '--remove-dir', 'hello-junction.bst:hello.bst'])
+ result.assert_success()