diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2020-04-11 16:16:33 +0900 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2020-04-17 20:58:24 +0900 |
commit | 48f8fdff9aec57f1620bc0ec3e21f201475b8f8c (patch) | |
tree | 2a5cf0a277f76999baa8e59aa15c5f2178cf80fb | |
parent | 061ca4c475568ec6ddaeb6c7498f48ad001015c7 (diff) | |
download | buildstream-48f8fdff9aec57f1620bc0ec3e21f201475b8f8c.tar.gz |
doc/source/format_intro.rst: Clarifications around directives
Clarification of (@) include documentation
The "important" annotation here was very confusing to read, rewrote
this section to clarify that files included across a junction cannot
be used to inform the declaration of a junction, as this can present
a circular dependency.
Clarification around conditionals and includes
Clarify that conditional statements are always resolved in the context
of the project where the conditional statement was declared.
-rw-r--r-- | doc/source/format_intro.rst | 41 |
1 files changed, 26 insertions, 15 deletions
diff --git a/doc/source/format_intro.rst b/doc/source/format_intro.rst index 86a3d336a..e8fe6007b 100644 --- a/doc/source/format_intro.rst +++ b/doc/source/format_intro.rst @@ -194,6 +194,16 @@ Compound conditionals are also allowed. - (logging == True and debugging == True): enable-debug: True +.. important:: + + Conditional statements are guaranteed to always be resolved in the + context of the project where the conditional statement is *declared*. + + When :ref:`including a file <format_directives_include>` from a + subproject, any conditionals expressed in that file will already be + resolved in the context of the subproject which the file was included + from. + .. _format_directives_assertion: @@ -297,7 +307,7 @@ free form and not validated. ~~~~~~~~~~~ Indicates that content should be loaded from files. -This include directive expects a string, or a list of strings when +The include directive expects a string, or a list of strings when including multiple files. Each of these strings represent a project relative filename to include. Files can be included from subprojects by prefixing the string with the locally defined :mod:`junction @@ -305,7 +315,7 @@ element <elements.junction>` and colon (':'). The include directive can be used in any dictionary declared in the :ref:`project.conf <projectconf>`, in any :ref:`.bst file -<format_basics>`, or recursively included in a another include file. +<format_basics>`, or recursively included in another include file. The including YAML fragment has priority over the files it includes, and overrides any values introduced by the includes. When including @@ -313,26 +323,27 @@ multiple files, files are included in the order they are declared in the include list, and each subsequent include file takes priority over the previous one. +**Example:** + +.. code:: yaml + + environment: + (@): junction.bst:includes/environment.bst + .. important:: - Cross junction include files are not processed when loading - :mod:`junction elements <elements.junction>`. Variables, - :ref:`element overrides <project_element_overrides>`, :ref:`source - overrides <project_source_overrides>` and :ref:`mirrors + Files included across a junction cannot be used to inform the + declaration of a :mod:`junction element <elements.junction>`, as + this can present a circular dependency. + + Any :ref:`variables <format_variables>`, :ref:`element + overrides <project_element_overrides>`, :ref:`source + overrides <project_source_overrides>` or :ref:`mirrors <project_essentials_mirrors>` used in the declaration of a junction must be declared in the :ref:`project.conf <projectconf>` or in included files which are local to the project declaring the junction itself. -:mod:`Junction elements <elements.junction>` cannot use include directives. - -**Example:** - -.. code:: yaml - - elements: - (@): junction.bst:includes/element-overrides.bst - .. note:: The include directive is available since :ref:`format version 12 <project_format_version>` |