Add junction support for subprojects

This introduces junctions as a new kind of elements to allow
dependencies to cross project boundaries.

1 files changed, 143 insertions, 0 deletions

diff --git a/buildstream/plugins/elements/junction.py b/buildstream/plugins/elements/junction.py
new file mode 100644
index 000000000..c0fd67d17
--- /dev/null
+++ b/buildstream/plugins/elements/junction.py
@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+#
+#  Copyright (C) 2017 Codethink Limited
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU Lesser General Public
+#  License as published by the Free Software Foundation; either
+#  version 2 of the License, or (at your option) any later version.
+#
+#  This library is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+#  Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public
+#  License along with this library. If not, see <http://www.gnu.org/licenses/>.
+#
+#  Authors:
+#        Jürg Billeter <juerg.billeter@codethink.co.uk>
+
+"""Junction element
+
+This element is a link to another BuildStream project. It allows integration
+of multiple projects into a single pipeline.
+
+Overview
+--------
+
+.. code:: yaml
+
+   kind: junction
+
+   # Specify the BuildStream project source
+   sources:
+   - kind: git
+     url: upstream:projectname.git
+     track: master
+     ref: d0b38561afb8122a3fc6bafc5a733ec502fcaed6
+
+   # Specify the junction configuration
+   config:
+
+     # Override project options
+     options:
+       machine_arch: "%{machine_arch}"
+       debug: True
+
+.. note::
+
+   Junction elements may not specify any dependencies as they are simply
+   links to other projects and are not in the dependency graph on their own.
+
+With a junction element in place, local elements can depend on elements in
+the other BuildStream project using the additional ``junction`` attribute in the
+dependency dictionary:
+
+.. code:: yaml
+
+   depends:
+   - junction: toolchain.bst
+     filename: gcc.bst
+     type: build
+
+While junctions are elements, only a limited set of element operations is
+supported. They can be tracked and fetched like other elements.
+However, junction elements do not produce any artifacts, which means that
+they cannot be built or staged. It also means that another element cannot
+depend on a junction element itself.
+
+Sources
+-------
+``bst show`` does not implicitly fetch junction sources if they haven't been
+cached yet. However, they can be fetched explicitly:
+
+.. code::
+
+   bst fetch junction.bst
+
+Other commands such as ``bst build`` implicitly fetch junction sources.
+
+Options
+-------
+.. code:: yaml
+
+   options:
+     machine_arch: "%{machine_arch}"
+     debug: True
+
+Junctions can configure options of the linked project. Options are never
+implicitly inherited across junctions, however, variables can be used to
+explicitly assign the same value to a subproject option.
+
+Nested Junctions
+----------------
+Junctions can be nested. That is, subprojects are allowed to have junctions on
+their own. Nested junctions in different subprojects may point to the same
+project, however, in most use cases the same project should be loaded only once.
+BuildStream uses the junction element name as key to determine which junctions
+to merge. It is recommended that the name of a junction is set to the same as
+the name of the linked project.
+
+As the junctions may differ in source version and options, BuildStream cannot
+simply use one junction and ignore the others. Due to this, BuildStream requires
+the user to resolve possibly conflicting nested junctions by creating a junction
+with the same name in the top-level project, which then takes precedence.
+"""
+
+import os
+from collections import Mapping
+from buildstream import Element
+from buildstream._pipeline import PipelineError
+
+
+# Element implementation for the 'junction' kind.
+class JunctionElement(Element):
+
+    def configure(self, node):
+        self.options = self.node_get_member(node, Mapping, 'options', default={})
+
+    def preflight(self):
+        pass
+
+    def get_unique_key(self):
+        # Junctions do not produce artifacts. get_unique_key() implementation
+        # is still required for `bst fetch`.
+        return 1
+
+    def configure_sandbox(self, sandbox):
+        raise PipelineError("Cannot build junction elements")
+
+    def stage(self, sandbox):
+        raise PipelineError("Cannot stage junction elements")
+
+    def generate_script(self):
+        raise PipelineError("Cannot build junction elements")
+
+    def assemble(self, sandbox):
+        raise PipelineError("Cannot build junction elements")
+
+
+# Plugin entry point
+def setup():
+    return JunctionElement