doc: Documenting dependency configurations

2 files changed, 51 insertions, 6 deletions

diff --git a/doc/source/format_declaring.rst b/doc/source/format_declaring.rst
index 391591530..98b5f926e 100644
--- a/doc/source/format_declaring.rst
+++ b/doc/source/format_declaring.rst
@@ -419,12 +419,6 @@ Attributes:
 
   The :ref:`element name <format_element_names>` to depend on.
 
-* ``type``
-
-  This attribute is used to express the :ref:`dependency type <format_dependencies_types>`.
-  This field is not permitted in :ref:`Build-Depends <format_build_depends>` or
-  :ref:`Runtime-Depends <format_runtime_depends>`.
-
 * ``junction``
 
   This attribute can be used to specify the junction portion of the :ref:`element name <format_element_names>`
@@ -437,6 +431,12 @@ Attributes:
   In the case that a *junction* is specified, the ``filename`` attribute indicates an
   element in the *junctioned project*.
 
+* ``type``
+
+  This attribute is used to express the :ref:`dependency type <format_dependencies_types>`.
+  This field is not permitted in :ref:`Build-Depends <format_build_depends>` or
+  :ref:`Runtime-Depends <format_runtime_depends>`.
+
 * ``strict``
 
   This attribute can be used to specify that this element should
@@ -447,6 +447,42 @@ Attributes:
   verbatim in the output of the depending element, for instance
   when static linking is in use.
 
+* ``config``
+
+  This attribute defines the custom :term:`dependency configuration <Dependency configuration>`,
+  which is supported by select :mod:`Element <buildstream.element>` implementations.
+
+  Elements which support :term:`dependency configuration <Dependency configuration>` do so
+  by implementing the
+  :func:`Element.configure_dependencies() <buildstream.element.Element.configure_dependencies>`
+  abstract method. It is up to each element or abstract element class to
+  document what is supported in their :term:`dependency configuration <Dependency configuration>`.
+
+  .. attention::
+
+     It is illegal to declare :term:`dependency configuration <Dependency configuration>`
+     on runtime dependencies, since runtime dependencies are not visible to the depending
+     element.
+
+
+Redundant dependency declarations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is permitted to declare dependencies multiple times on the same element in the same
+element declaration, the result will be an inclusive OR of all configurations you have
+expressed in the redundant dependencies on the same element.
+
+* If a dependency is defined once as a ``build`` dependency and once as a ``runtime``
+  :ref:`dependency type <format_dependencies_types>`, then the resulting dependency
+  type will be ``all``
+
+* If any of the redundantly declared dependencies are specified as ``strict``, then
+  the resulting dependency will be ``strict``.
+
+Declaring redundant dependencies on the same element can be interesting when you
+need to specify multiple :term:`dependency configurations <Dependency configuration>`
+for the same element. For example, one might want to stage the same dependency
+in multiple locations in the build sandbox.
+
 
 Cross-junction dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/source/main_glossary.rst b/doc/source/main_glossary.rst
index c97277532..aa0c6da1f 100644
--- a/doc/source/main_glossary.rst
+++ b/doc/source/main_glossary.rst
@@ -44,6 +44,15 @@ Glossary
        See :ref:`Dependencies document <format_dependencies>` for more
        details.
 
+   Dependency configuration
+       Additional custom YAML configuration which is used to define
+       an :term:`Element's <Element>` relationship with it's :term:`Dependency <Dependency>`.
+
+       This is supported on limited :term:`Element <Element>` implementations, and
+       each :term:`Element <Element>` defines what configuration it supports.
+
+       See the :ref:`dependency documentation <format_dependencies>` for details
+       on dependency configuration.
 
    Element
        An atom of a :term:`BuildStream project <Project>`. Projects consist of