summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorPhil Dawson <phil.dawson@codethink.co.uk>2018-07-17 13:23:06 +0100
committerPhil Dawson <phildawson.0807@gmail.com>2018-07-30 07:58:07 +0000
commitbf175bf78f5a1c3392d979182440858cd43054fc (patch)
tree279908b94a3020b0475ac8bd370ed436f3d31997 /doc
parentefa24e7e633d9ede4edaff80eef707f089950907 (diff)
downloadbuildstream-bf175bf78f5a1c3392d979182440858cd43054fc.tar.gz
junction-elements.rst: Add junctions walkthrough
This is part of the work towards #437.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile3
-rw-r--r--doc/source/advanced-features/junction-elements.rst72
2 files changed, 75 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile
index 3557ac505..381ab90ad 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -118,8 +118,11 @@ html devhelp: templates sessions
$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \
$(wildcard source/*.rst) \
$(wildcard source/tutorial/*.rst) \
+ $(wildcard source/advanced-features/*.rst) \
$(wildcard source/examples/*.rst) \
$(wildcard source/elements/*.rst) \
$(wildcard source/sources/*.rst)
@echo
@echo "Build of $@ finished, output: $(CURDIR)/$(BUILDDIR)/$@"
+# Makefile for Sphinx documentation
+#
diff --git a/doc/source/advanced-features/junction-elements.rst b/doc/source/advanced-features/junction-elements.rst
new file mode 100644
index 000000000..4457077aa
--- /dev/null
+++ b/doc/source/advanced-features/junction-elements.rst
@@ -0,0 +1,72 @@
+
+
+Junction elements
+=================
+BuildStream's junction elements are used to import other BuildStream
+projects. This allows you to depend on elements that are part of an
+upstream project.
+
+
+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>`_
+ subdirectory.
+
+Below is a simple example of bst file for a junction element:
+
+.. literalinclude:: ../../examples/junctions/elements/hello-junction.bst
+ :language: yaml
+
+This element imports the autotools example project found in the BuildStream
+doc/examples/autotools subdirectory.
+
+.. note::
+
+ While for this example we're using a local source, another common use-case,
+ for junction elements is including a remote, version contolled project,
+ having a source type such as `-kind: git`.
+
+The below bst file describes an element which depends on the hello.bst element
+from the autotools example:
+
+.. literalinclude:: ../../examples/junctions/elements/callHello.bst
+
+This element consists of a script which calls hello.bst's hello command.
+
+Building callHello.bst,
+
+.. raw:: html
+ :file: ../sessions-stored/junctions-build.html
+
+You can see that the hello.bst element and it's dependencies from the autotools
+project have been build as part of the pipeline for callHello.bst.
+
+We can now invoke `bst shell`
+
+.. raw:: html
+ :file: ../sessions-stored/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.
+
+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-stored/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.
+
+
+Further reading
+---------------
+For an example of junction elements being used in a real project, take a look
+at the `freedesktop-sdk junction
+<https://gitlab.gnome.org/GNOME/gnome-build-meta/blob/master/elements/freedesktop-sdk.bst>`_
+in the `gnome-build-meta <https://gitlab.gnome.org/GNOME/gnome-build-meta>`_ project.