doc/source/format_project.rst: Documenting the junction plugin origin.tristan/junction-plugin-origin

1 files changed, 63 insertions, 0 deletions

diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index 8cdced8f0..69c844692 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -380,6 +380,8 @@ of the plugins it means to make use of and the origin from which they can be loa
 Note that plugins with the same name from different origins are not permitted.
 
 
+.. _project_plugins_local:
+
 Local plugins
 ~~~~~~~~~~~~~
 Local plugins are expected to be found in a subdirectory of the actual
@@ -412,6 +414,8 @@ in the semantics of existing configurations or even removal of existing
 YAML configurations.
 
 
+.. _project_plugins_pip:
+
 Pip plugins
 ~~~~~~~~~~~
 Plugins loaded from the ``pip`` origin are expected to be installed
@@ -542,6 +546,65 @@ Here are a couple of examples:
    agree on which versions of API unstable plugin packages to use.
 
 
+.. _project_plugins_junction:
+
+Junction plugins
+~~~~~~~~~~~~~~~~
+Junction plugins are loaded from another project which your project has a
+:mod:`junction <elements.junction>` declaration for. Plugins are loaded directly
+from the referenced project, the source and element plugins listed will simply
+be loaded from the subproject regardless of how they were defined in that project.
+
+Plugins loaded from a junction might even come from another junction and
+be *deeply nested*.
+
+.. code:: yaml
+
+   plugins:
+
+   - origin: junction
+
+     # Specify the local junction name declared in your
+     # project as the origin from where to load plugins from.
+     #
+     junction: subproject-junction.bst
+
+     # Here we want to get the `frobnicate` element
+     # from the subproject and use it in our project.
+     #
+     elements:
+     - frobnicate
+
+Plugins loaded across junction boundaries will be loaded in the
+context of your project, and any default values set in the ``project.conf``
+of the junctioned project will be ignored when resolving the
+defaults provided with element plugins.
+
+It is recommended to use :ref:`include directives <format_directives_include>`
+in the case that the referenced plugins from junctioned projects depend
+on variables defined in the project they come from, in this way you can include
+variables needed by your plugins into your own ``project.conf``.
+
+.. tip::
+
+   **Distributing plugins as projects**
+
+   It is encouraged that people use BuildStream projects to distribute plugins
+   which are intended to be shared among projects, especially when these plugins
+   are not guaranteed to be completely API stable. This can still be done while
+   also distributing your plugins as :ref:`pip packages <project_plugins_pip>` at
+   the same time.
+
+   This can be achieved by simply creating a repository or tarball which
+   contains only the plugins you want to distribute, along with a ``project.conf``
+   file declaring these plugins as :ref:`local plugins <project_plugins_local>`.
+
+   Using plugins which are distributed as local plugins in a BuildStream project
+   ensures that you always have full control over which exact plugin your
+   project is using at all times, without needing to store the plugin as a
+   :ref:`local plugin <project_plugins_local>` in your own project.
+
+
 .. _project_plugins_deprecation:
 
 Suppressing deprecation warnings