

.. _junction_elements:

Junction elements
=================
BuildStream's :mod:`junction <elements.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 :ref:`fetched <invoking_source_fetch>`
and :ref:`tracked <invoking_source_track>` like other elements, except that regular
elements cannot *depend* on junctions directly, nor can junctions be :ref:`built <invoking_build>`.
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*.


A simple example
----------------

.. note::

    This example is distributed with BuildStream in the
    `doc/examples/junctions <https://github.com/apache/buildstream/tree/master/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:

.. literalinclude:: ../../examples/junctions/elements/hello-junction.bst
    :language: yaml

This element imports the autotools example subproject distributed with BuildStream
in the `doc/examples/junctions/autotools <https://github.com/apache/buildstream/tree/master/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:

.. literalinclude:: ../../examples/junctions/elements/callHello.bst
    :language: yaml

Note how this element refers to the previously declared ``hello-junction.bst``
junction in its :ref:`dependency dictionary <format_dependencies>`. 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``:

.. literalinclude:: ../../examples/junctions/files/callHello.sh
    :language: shell


Building and running
--------------------
Building the ``callHello.bst`` element which requires an external project
is just a matter of invoking :ref:`bst build <invoking_build>` in the
regular way:

.. raw:: html
   :file: ../sessions/junctions-build.html

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 :ref:`bst shell <invoking_shell>` and run our ``callHello.sh``
script, which in turn also calls the ``hello`` program installed by the
subproject's ``hello.bst`` element.

.. raw:: html
   :file: ../sessions/junctions-shell.html


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.