diff options
| -rw-r--r-- | doc/source/format_declaring.rst | 124 | ||||
| -rw-r--r-- | src/buildstream/plugins/elements/junction.py | 12 | ||||
| -rw-r--r-- | src/buildstream/plugins/elements/link.py | 5 |
3 files changed, 80 insertions, 61 deletions
diff --git a/doc/source/format_declaring.rst b/doc/source/format_declaring.rst index 7514d43e1..41224e039 100644 --- a/doc/source/format_declaring.rst +++ b/doc/source/format_declaring.rst @@ -60,6 +60,57 @@ details here in order to have a more complete initial example. Let's break down the above and give a brief explanation of what these attributes mean. +.. _format_element_names: + +Element names and paths +~~~~~~~~~~~~~~~~~~~~~~~ +An *element name* is the filename of an element relative to the project's +:ref:`element path <project_element_path>`. + +Element names are the identifiers used to refer to elements, they are used +to specify an element's :ref:`dependencies <format_dependencies>`, to select +elements to build on the :ref:`command line <commands>`, and they are arbitrarily +used in various element specific configuration surfaces, for example the +*target* configuration of the :mod:`link <elements.link>` element is also +an *element name*. + + +Addressing elements +''''''''''''''''''' +When addressing elements in a single project, it is sufficient to use +the *element name* as a dependency or configuration parameter. + +When muliple projects are connected through :mod:`junction <elements.junction>` +elements, there is a need to address elements which are not in the same +project but in a junctioned *subproject*. In the case that you need to +address elements across junction boundaries, one must use *element paths*. + +An *element path* is a path to the element indicating the junction +elements leading up to the project, separated by ``:`` symbols, e.g.: +``junction.bst:junction.bst:element.bst``. + + +Element naming rules +'''''''''''''''''''' +When naming the elements, use the following rules: + +* The name of the file must have ``.bst`` extension. + +* All characters in the name must be printable 7-bit ASCII characters. + +* Following characters are reserved and must not be part of the name: + + - ``<`` (less than) + - ``>`` (greater than) + - ``:`` (colon) + - ``"`` (double quote) + - ``/`` (forward slash) + - ``\`` (backslash) + - ``|`` (vertical bar) + - ``?`` (question mark) + - ``*`` (asterisk) + + Kind ~~~~ @@ -92,8 +143,8 @@ Depends - element2.bst Relationships between elements are specified with the ``depends`` attribute. Elements -may depend on other elements by specifying the :ref:`element path <project_element_path>` -relative filename to the elements they depend on here. +may depend on other elements by specifying the :ref:`element names <format_element_names>` +they depend on here. See :ref:`format_dependencies` for more information on the dependency model. @@ -228,7 +279,6 @@ Environment variables can be set to literal values here, these environment variables will be effective in the :mod:`Sandbox <buildstream.sandbox>` where build instructions are run for this element. - Environment variables can also be declared and overridden in the :ref:`projectconf` @@ -364,8 +414,7 @@ Attributes: * ``filename`` - The :ref:`element path <project_element_path>` relative filename of the element to - depend on in the project. + The :ref:`element name <format_element_names>` to depend on. * ``type`` @@ -375,15 +424,15 @@ Attributes: * ``junction`` - This attribute can be used to depend on elements in other projects. - - If a junction is specified, then it must be an :ref:`element path <project_element_path>` - relative filename of the junction element in the project. + This attribute can be used to specify the junction portion of the :ref:`element name <format_element_names>` + separately from the project local element name. - In the case that a *junction* is specified, the ``filename`` attribute indicates an element - in the *junctioned project*. + This should be the *element name* of the :mod:`junction <elements.junction>` element + in the local project, possibly followed by other junctions in subprojects leading + to the project in which the element you want to depend on resides. - See :mod:`junction <elements.junction>`. + In the case that a *junction* is specified, the ``filename`` attribute indicates an + element in the *junctioned project*. * ``strict`` @@ -398,33 +447,26 @@ Attributes: Cross-junction dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As mentioned above, cross-junction dependencies can be specified using the -``junction`` attribute. They can also be expressed as simple strings as a -convenience shorthand. You can refer to cross-junction elements using the -syntax ``{junction-name}:{element-name}``. +As explained in the :ref:`element name <format_element_names>` section +on element addressing, elements can be addressed across junction boundaries +using *element paths* such as ``junction.bst:element.bst``. An element +at any depth can be specified by specifying multiple junction elements. -For example, the following is logically same as the example above: +For example, one can specify a subproject element dependency with +the following syntax: .. code:: yaml build-depends: - - baseproject.bst:foo.bst + - baseproject.bst:element.bst -Similarly, you can also refer to cross-junction elements via the ``filename`` -attribute, like so: +And one can specify an element residing in a sub-subproject as a +dependency like so: .. code:: yaml depends: - - filename: baseproject.bst:foo.bst - type: build - -.. note:: - - BuildStream does not allow recursive lookups for junction elements. If a - filename contains more than one ``:`` (colon) character, an error will be - raised. See :ref:`nested junctions <core_junction_nested>` for more details - on nested junctions. + - baseproject.bst:middleproject.bst:element.bst .. _format_dependencies_types: @@ -552,27 +594,3 @@ read-only variables are also dynamically declared by BuildStream: build, support for this is conditional on the element type and the build system used (any element using 'make' can implement this). - - -Naming elements ---------------- -When naming the element files, use the following rules: - -* The name of the file must have ``.bst`` extension. - -* All characters in the name must be printable 7-bit ASCII characters. - -* Following characters are reserved and must not be part of the name: - - - ``<`` (less than) - - ``>`` (greater than) - - ``:`` (colon) - - ``"`` (double quote) - - ``/`` (forward slash) - - ``\`` (backslash) - - ``|`` (vertical bar) - - ``?`` (question mark) - - ``*`` (asterisk) - -BuildStream will attempt to raise warnings when any of these rules are violated -but that may not always be possible. diff --git a/src/buildstream/plugins/elements/junction.py b/src/buildstream/plugins/elements/junction.py index c9e78632f..3e221cce7 100644 --- a/src/buildstream/plugins/elements/junction.py +++ b/src/buildstream/plugins/elements/junction.py @@ -63,15 +63,15 @@ Overview 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: +the other BuildStream project using :ref:`element paths <format_element_names>`. +For example, if you have a ``toolchain.bst`` junction element referring to +a project which contains a ``gcc.bst`` element, you can express a build +dependency to the compiler like this: .. code:: yaml - depends: - - junction: toolchain.bst - filename: gcc.bst - type: build + build-depends: + - junction: toolchain.bst:gcc.bst While junctions are elements, only a limited set of element operations is supported. They can be tracked and fetched like other elements. diff --git a/src/buildstream/plugins/elements/link.py b/src/buildstream/plugins/elements/link.py index 611108241..e6d7f056e 100644 --- a/src/buildstream/plugins/elements/link.py +++ b/src/buildstream/plugins/elements/link.py @@ -27,7 +27,7 @@ a symbolic element which will be resolved to another element. Overview -------- The only configuration allowed in a ``link`` element is the specified -target of the link. +target :ref:`element name <format_element_names>` of the link. .. code:: yaml @@ -37,7 +37,8 @@ target of the link. target: element.bst The ``link`` element can be used to refer to elements in subprojects, and -can be used to symbolically link junctions as well as other elements. +can be used to symbolically link :mod:`junction <elements.junction>` elements +as well as other elements. """ from buildstream import Element |