1. Junction elements
BuildStream’s junction elements are the mechanism which
allow projects to interact and depend on eachother.
Junction elements represent the BuildStream project you are depending, and behave much like other elements in the sense that they can be fetched and tracked like other elements, except that regular elements cannot depend on junctions directly, nor can junctions be built. Instead, junctions act like a window into another project you depend on, and allow elements of your project to depend on elements exposed by the project referenced by the junction.
Projects which are junctioned by your project are referred to as subprojects.
1.1. A simple example
Note
This example is distributed with BuildStream in the doc/examples/junctions subdirectory.
Below is a simple example of bst file for the junction element, which
we have called hello-junction.bst in this project:
kind: junction
sources:
- kind: local
path: autotools
This element imports the autotools example subproject distributed with BuildStream in the doc/examples/junctions/autotools subdirectory.
Note
For the sake of this example we are using a local source in a subdirectory of the example project.
Since junctions allow interoperability of projects, it would be more common
to use a junction to a remote project under separate revision control, possibly
using a kind: git source.
The below bst file describes the element callHello.bst, which depends on the
hello.bst element from the autotools example:
kind: import
sources:
- kind: local
path: files/callHello.sh
depends:
- filename: hello.bst
junction: hello-junction.bst
Note how this element refers to the previously declared hello-junction.bst
junction in its dependency dictionary. This dependency
expresses that we are depending on the hello.bst element in the project
which hello-junction.bst refers to.
The callHello.bst element simply imports a callHello.sh shell script which
calls the hello command provided by hello.bst:
#!/bin/sh
echo "Calling hello:"
hello
1.2. Building and running
Building the callHello.bst element which requires an external project
is just a matter of invoking bst build in the
regular way:
user@host:~/junctions$ bst build callHello.bst
[--:--:--][ ][ main:core activity ] START Build
[--:--:--][ ][ main:core activity ] START Loading elements
WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1723732120.351805 5295 config.cc:230] gRPC experiments enabled: call_status_override_on_cancellation, event_engine_dns, event_engine_listener, http2_stats_fix, monitoring_experiment, pick_first_new, trace_record_callops, work_serializer_clears_time_cache
[--:--:--][6d2e5da0][ fetch:hello-junction.bst ] START junctions/hello-junction/6d2e5da0-fetch.20240815-142840.log
[00:00:00][6d2e5da0][ fetch:hello-junction.bst ] SUCCESS junctions/hello-junction/6d2e5da0-fetch.20240815-142840.log
[00:00:00][ ][ main:core activity ] SUCCESS Loading elements
[--:--:--][ ][ main:core activity ] START Resolving elements
[00:00:00][ ][ main:core activity ] SUCCESS Resolving elements
[--:--:--][ ][ main:core activity ] START Initializing remote caches
[00:00:00][ ][ main:core activity ] SUCCESS Initializing remote caches
[--:--:--][ ][ main:core activity ] START Query cache
[00:00:00][ ][ main:core activity ] SUCCESS Query cache
BuildStream Version 2.3.0
Session Start: Thursday, 15-08-2024 at 14:28:40
Project: junctions (/home/user/buildstream/doc/examples/junctions)
Targets: callHello.bst
User Configuration
Configuration File: /home/user/buildstream/doc/run-bst-xsm25yqy/buildstream.conf
Cache Directory: /home/user/buildstream/doc/run-bst-xsm25yqy
Log Files: /home/user/buildstream/doc/run-bst-xsm25yqy/logs
Source Mirrors: /home/user/buildstream/doc/run-bst-xsm25yqy/sources
Build Area: /home/user/buildstream/doc/run-bst-xsm25yqy/build
Strict Build Plan: Yes
Maximum Fetch Tasks: 10
Maximum Build Tasks: 4
Maximum Push Tasks: 4
Maximum Network Retries: 2
Project: junctions
Element Plugins
junction: core plugin
import: core plugin
Source Plugins
local: core plugin
Project: autotools
Junction path: hello-junction.bst
Loaded by: callHello.bst [line 8 column 4]
Element Plugins
autotools: python package 'buildstream-plugins 2.2.0' at: /home/user/buildstream/.tox/docs/lib/python3.12/site-packages
stack: core plugin
import: core plugin
Source Plugins
tar: core plugin
Pipeline
fetch needed 6a78c03097648e558c803c20d8d20f61d3e87e3e616f3a45923704cfe95019af hello-junction.bst:base/alpine.bst
waiting 644e964abe673c8a8723cf5a3fceeeda44a7bea364f55604fc8132af44a4fb59 hello-junction.bst:base.bst
fetch needed ffeab61203b5940714c33b1cc29822b9391b9fea5876faef23c024bf6acd99cf hello-junction.bst:hello.bst
waiting b6da6abe68420499ec616c50433619027a915e37217b85450a5590a28bd28820 callHello.bst
===============================================================================
[--:--:--][6a78c030][ fetch:hello-junction.bst:base/alpine.bst] START autotools/base-alpine/6a78c030-fetch.20240815-142840.log
[--:--:--][ffeab612][ fetch:hello-junction.bst:hello.bst ] START autotools/hello/ffeab612-fetch.20240815-142840.log
[--:--:--][b6da6abe][ fetch:callHello.bst ] START junctions/callHello/b6da6abe-fetch.20240815-142840.log
[--:--:--][644e964a][ fetch:hello-junction.bst:base.bst ] START autotools/base/644e964a-fetch.20240815-142840.log
[--:--:--][ffeab612][ fetch:hello-junction.bst:hello.bst ] START Fetching https://ftpmirror.gnu.org/gnu/automake/automake-1.16.tar.gz
[--:--:--][6a78c030][ fetch:hello-junction.bst:base/alpine.bst] START Fetching https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/integration-tests-base.v1.x86_64.tar.xz
[00:00:00][644e964a][ fetch:hello-junction.bst:base.bst ] SUCCESS autotools/base/644e964a-fetch.20240815-142840.log
[00:00:00][b6da6abe][ fetch:callHello.bst ] SUCCESS junctions/callHello/b6da6abe-fetch.20240815-142840.log
[00:00:00][6a78c030][ fetch:hello-junction.bst:base/alpine.bst] SUCCESS Fetching https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/integration-tests-base.v1.x86_64.tar.xz
[00:00:06][6a78c030][ fetch:hello-junction.bst:base/alpine.bst] SUCCESS autotools/base-alpine/6a78c030-fetch.20240815-142840.log
[--:--:--][6a78c030][ build:hello-junction.bst:base/alpine.bst] START autotools/base-alpine/6a78c030-build.20240815-142847.log
[--:--:--][6a78c030][ build:hello-junction.bst:base/alpine.bst] START Staging sources
[00:00:00][6a78c030][ build:hello-junction.bst:base/alpine.bst] SUCCESS Staging sources
[--:--:--][6a78c030][ build:hello-junction.bst:base/alpine.bst] START Caching artifact
[00:00:00][6a78c030][ build:hello-junction.bst:base/alpine.bst] SUCCESS Caching artifact
[00:00:00][6a78c030][ build:hello-junction.bst:base/alpine.bst] SUCCESS autotools/base-alpine/6a78c030-build.20240815-142847.log
[--:--:--][644e964a][ build:hello-junction.bst:base.bst ] START autotools/base/644e964a-build.20240815-142847.log
[--:--:--][644e964a][ build:hello-junction.bst:base.bst ] START Caching artifact
[00:00:00][644e964a][ build:hello-junction.bst:base.bst ] SUCCESS Caching artifact
[00:00:00][644e964a][ build:hello-junction.bst:base.bst ] SUCCESS autotools/base/644e964a-build.20240815-142847.log
[00:00:08][ffeab612][ fetch:hello-junction.bst:hello.bst ] SUCCESS Fetching https://ftpmirror.gnu.org/gnu/automake/automake-1.16.tar.gz
[00:00:08][ffeab612][ fetch:hello-junction.bst:hello.bst ] SUCCESS autotools/hello/ffeab612-fetch.20240815-142840.log
[--:--:--][ffeab612][ build:hello-junction.bst:hello.bst ] START autotools/hello/ffeab612-build.20240815-142849.log
[--:--:--][ffeab612][ build:hello-junction.bst:hello.bst ] START Staging dependencies at: /
[00:00:00][ffeab612][ build:hello-junction.bst:hello.bst ] SUCCESS Staging dependencies at: /
[--:--:--][ffeab612][ build:hello-junction.bst:hello.bst ] START Integrating sandbox
[00:00:00][ffeab612][ build:hello-junction.bst:hello.bst ] SUCCESS Integrating sandbox
[--:--:--][ffeab612][ build:hello-junction.bst:hello.bst ] START Staging sources
[00:00:00][ffeab612][ build:hello-junction.bst:hello.bst ] SUCCESS Staging sources
[--:--:--][ffeab612][ build:hello-junction.bst:hello.bst ] START Running commands
export NOCONFIGURE=1;
if [ -x ./configure ]; 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 .;
fi
./configure --prefix=/usr \
--exec-prefix=/usr \
--bindir=/usr/bin \
--sbindir=/usr/sbin \
--sysconfdir=/etc \
--datadir=/usr/share \
--includedir=/usr/include \
--libdir=/usr/lib \
--libexecdir=/usr/libexec \
--localstatedir=/var \
--sharedstatedir=/usr/com \
Message contains 23 additional lines
[00:00:03][ffeab612][ build:hello-junction.bst:hello.bst ] SUCCESS Running commands
[--:--:--][ffeab612][ build:hello-junction.bst:hello.bst ] START Caching artifact
[00:00:00][ffeab612][ build:hello-junction.bst:hello.bst ] SUCCESS Caching artifact
[00:00:03][ffeab612][ build:hello-junction.bst:hello.bst ] SUCCESS autotools/hello/ffeab612-build.20240815-142849.log
[--:--:--][b6da6abe][ build:callHello.bst ] START junctions/callHello/b6da6abe-build.20240815-142852.log
[--:--:--][b6da6abe][ build:callHello.bst ] START Staging sources
[00:00:00][b6da6abe][ build:callHello.bst ] SUCCESS Staging sources
[--:--:--][b6da6abe][ build:callHello.bst ] START Caching artifact
[00:00:00][b6da6abe][ build:callHello.bst ] SUCCESS Caching artifact
[00:00:00][b6da6abe][ build:callHello.bst ] SUCCESS junctions/callHello/b6da6abe-build.20240815-142852.log
[00:00:12][ ][ main:core activity ] SUCCESS Build
Pipeline Summary
Total: 4
Session: 4
Fetch Queue: processed 4, skipped 0, failed 0
Build Queue: processed 4, skipped 0, failed 0
You can see that the hello.bst element and its dependencies from the autotools project have been built as a part of the pipeline for callHello.bst.
We can now invoke bst shell and run our callHello.sh
script, which in turn also calls the hello program installed by the
subproject’s hello.bst element.
user@host:~/junctions$ bst shell callHello.bst -- /bin/sh callHello.sh
[--:--:--][ ][ main:core activity ] START Loading elements
WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1723732133.297193 6314 config.cc:230] gRPC experiments enabled: call_status_override_on_cancellation, event_engine_dns, event_engine_listener, http2_stats_fix, monitoring_experiment, pick_first_new, trace_record_callops, work_serializer_clears_time_cache
[00:00:00][ ][ main:core activity ] SUCCESS Loading elements
[--:--:--][ ][ main:core activity ] START Resolving elements
[00:00:00][ ][ main:core activity ] SUCCESS Resolving elements
[--:--:--][ ][ main:core activity ] START Initializing remote caches
[00:00:00][ ][ main:core activity ] SUCCESS Initializing remote caches
[--:--:--][ ][ main:core activity ] START Query cache
[00:00:00][ ][ main:core activity ] SUCCESS Query cache
[--:--:--][b6da6abe][ main:callHello.bst ] START Staging dependencies
[00:00:00][b6da6abe][ main:callHello.bst ] SUCCESS Staging dependencies
[--:--:--][b6da6abe][ main:callHello.bst ] START Integrating sandbox
[00:00:00][b6da6abe][ main:callHello.bst ] SUCCESS Integrating sandbox
[--:--:--][b6da6abe][ main:callHello.bst ] STATUS Running command
/bin/sh callHello.sh
Calling hello:
Hello World!
This is amhello 1.0.
1.3. Further reading
For an example of junction elements being used in a real project, take a look at the freedesktop-sdk junction in the gnome-build-meta project.