1. 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.

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 a junction element:

kind: junction
sources:
- kind: local
  path: autotools

This element imports the autotools example subproject found in the BuildStream doc/examples/junctions/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:

kind: import

sources:
- kind: local
  path: files/callHello.sh

depends:
  - filename: hello.bst
    junction: hello-junction.bst

This element consists of a script which calls hello.bst’s hello command.

Building callHello.bst,

user@host:~/junctions$ bst build callHello.bst

[--:--:--][        ][ main:core activity                 ] STATUS  Cache usage recomputed: 12K / infinity (0%)
[--:--:--][        ][ main:core activity                 ] START   Build
[--:--:--][        ][ main:core activity                 ] START   Loading elements
[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   Resolving cached state
[00:00:00][        ][ main:core activity                 ] SUCCESS Resolving cached state
[--:--:--][        ][ main:core activity                 ] START   Checking sources
[00:00:00][        ][ main:core activity                 ] SUCCESS Checking sources

BuildStream Version 1.3.0+1567.g067a0c6b.dirty
  Session Start: Monday, 18-02-2019 at 20:38:12
  Project:       junctions (/home/user/junctions)
  Targets:       callHello.bst
  Cache Usage:   12K / infinity (0%)

User Configuration
  Configuration File:      /home/user/.config/buildstream.conf
  Log Files:               /home/user/.cache/buildstream/logs
  Source Mirrors:          /home/user/.cache/buildstream/sources
  Build Area:              /home/user/.cache/buildstream/build
  Artifact Cache:          /home/user/.cache/buildstream/artifacts
  Strict Build Plan:       Yes
  Maximum Fetch Tasks:     10
  Maximum Build Tasks:     4
  Maximum Push Tasks:      4
  Maximum Network Retries: 2

Pipeline
   buildable 4a31d9cf5fcd8bed64c35acd0451ad5c3c06813ee2febab29149d1b849e32f16 hello-junction.bst:base/alpine.bst 
     waiting 20182cc27932cf6633aa2cbaee86fe04f56ac112feef21d9a3759f0991d48f35 hello-junction.bst:base.bst 
     waiting a64362db63ac42a860f6846b9ebde6e835a0b99419cfbc60409706eb5e222007 hello-junction.bst:hello.bst 
     waiting 5abad316fbff2960ab8f9458aecdd2e5a0a1e4dd4855a0b12cd895bd958e12cd callHello.bst 
===============================================================================
[--:--:--][4a31d9cf][build:hello-junction.bst:base/alpine.bst] START   autotools/base-alpine/4a31d9cf-build.1968.log
[--:--:--][4a31d9cf][build:hello-junction.bst:base/alpine.bst] START   Staging sources
[00:00:15][4a31d9cf][build:hello-junction.bst:base/alpine.bst] SUCCESS Staging sources
[--:--:--][4a31d9cf][build:hello-junction.bst:base/alpine.bst] START   Caching artifact
[00:00:08][4a31d9cf][build:hello-junction.bst:base/alpine.bst] SUCCESS Caching artifact
[00:00:28][4a31d9cf][build:hello-junction.bst:base/alpine.bst] SUCCESS autotools/base-alpine/4a31d9cf-build.1968.log
[--:--:--][20182cc2][build:hello-junction.bst:base.bst   ] START   autotools/base/20182cc2-build.1973.log
[--:--:--][20182cc2][build:hello-junction.bst:base.bst   ] START   Caching artifact
[00:00:00][20182cc2][build:hello-junction.bst:base.bst   ] SUCCESS Caching artifact
[00:00:00][20182cc2][build:hello-junction.bst:base.bst   ] SUCCESS autotools/base/20182cc2-build.1973.log
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] START   autotools/hello/a64362db-build.1978.log
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] START   Staging dependencies
[00:00:01][a64362db][build:hello-junction.bst:hello.bst  ] SUCCESS Staging dependencies
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] START   Integrating sandbox
[00:00:00][a64362db][build:hello-junction.bst:hello.bst  ] SUCCESS Integrating sandbox
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] START   Staging sources
[00:00:01][a64362db][build:hello-junction.bst:hello.bst  ] SUCCESS Staging sources
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] START   Running configure-commands
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] STATUS  Running command

    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

[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] STATUS  Running command

    ./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 \
    --mandir=/usr/share/man \
    --infodir=/usr/share/info   

[00:00:05][a64362db][build:hello-junction.bst:hello.bst  ] SUCCESS Running configure-commands
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] START   Running build-commands
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] STATUS  Running command

    make

[00:00:00][a64362db][build:hello-junction.bst:hello.bst  ] SUCCESS Running build-commands
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] START   Running install-commands
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] STATUS  Running command

    make -j1 DESTDIR="/buildstream-install" install

[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] STATUS  Running command

    if false || false; then
      find "/buildstream-install" -name "*.la" -print0 | while read -d '' -r file; do
        if grep '^shouldnotlink=yes$' "${file}" &>/dev/null; then
          if false; then
            echo "Removing ${file}."
            rm "${file}"
          else
            echo "Not removing ${file}."
          fi
        else
          if false; then
            echo "Removing ${file}."
            rm "${file}"
          else
            echo "Not removing ${file}."
          fi
        fi
      done
    fi

[00:00:00][a64362db][build:hello-junction.bst:hello.bst  ] SUCCESS Running install-commands
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] START   Running strip-commands
[00:00:00][a64362db][build:hello-junction.bst:hello.bst  ] SUCCESS Running strip-commands
[--:--:--][a64362db][build:hello-junction.bst:hello.bst  ] START   Caching artifact
[00:00:01][a64362db][build:hello-junction.bst:hello.bst  ] SUCCESS Caching artifact
[00:00:10][a64362db][build:hello-junction.bst:hello.bst  ] SUCCESS autotools/hello/a64362db-build.1978.log
[--:--:--][5abad316][build:callHello.bst                 ] START   junctions/callHello/5abad316-build.2956.log
[--:--:--][5abad316][build:callHello.bst                 ] START   Staging sources
[00:00:00][5abad316][build:callHello.bst                 ] SUCCESS Staging sources
[--:--:--][5abad316][build:callHello.bst                 ] START   Caching artifact
[00:00:00][5abad316][build:callHello.bst                 ] SUCCESS Caching artifact
[00:00:00][5abad316][build:callHello.bst                 ] SUCCESS junctions/callHello/5abad316-build.2956.log
[00:00:39][        ][ main:core activity                 ] SUCCESS Build

Pipeline Summary
  Total:       4
  Session:     4
  Fetch Queue: processed 0, skipped 4, 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 build as part of the pipeline for callHello.bst.

We can now invoke bst shell

user@host:~/junctions$ bst shell callHello.bst -- /bin/sh callHello.sh

[--:--:--][        ][ main:core activity                 ] START   Loading elements
[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   Resolving cached state
[00:00:00][        ][ main:core activity                 ] SUCCESS Resolving cached state
[--:--:--][5abad316][ main:callHello.bst                 ] START   Staging dependencies
[00:00:01][5abad316][ main:callHello.bst                 ] SUCCESS Staging dependencies
[--:--:--][5abad316][ main:callHello.bst                 ] START   Integrating sandbox
[00:00:00][5abad316][ main:callHello.bst                 ] SUCCESS Integrating sandbox
[--:--:--][5abad316][ main:callHello.bst                 ] STATUS  Running command

    /bin/sh callHello.sh

Calling hello:
Hello World!
This is amhello 1.0.

This runs the script files/callHello.sh which will makes use of the hello command from the hello.bst element in the autotools project.

1.2. 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,

user@host:~/junctions$ bst workspace open --directory workspace_hello hello-junction.bst:hello.bst

[--:--:--][        ][ main:core activity                 ] START   Loading elements
[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   Resolving cached state
[00:00:00][        ][ main:core activity                 ] SUCCESS Resolving cached state
[--:--:--][        ][ main:core activity                 ] START   Checking sources
[00:00:00][        ][ main:core activity                 ] SUCCESS Checking sources
[--:--:--][        ][ main:core activity                 ] INFO    Creating workspace for element hello.bst
[--:--:--][a64362db][ main:hello-junction.bst:hello.bst  ] START   Staging sources to /home/user/junctions/workspace_hello
[00:00:00][a64362db][ main:hello-junction.bst:hello.bst  ] SUCCESS Staging sources to /home/user/junctions/workspace_hello
[--:--:--][        ][ main:core activity                 ] INFO    Created a workspace for element: hello-junction.bst:hello.bst

This has opened a workspace for the hello.bst element from the autotools project. This workspace can now be used as normal.

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.