diff options
author | Valentin David <valentin.david@codethink.co.uk> | 2018-07-18 12:29:40 +0200 |
---|---|---|
committer | Valentin David <valentin.david@codethink.co.uk> | 2018-08-02 16:18:10 +0200 |
commit | 171e803f5dab2644c7bcd2e22acecef64880e1ce (patch) | |
tree | a8e2ca4f2a7e2bebde42cb6ec2ba5f6ce32e26a6 /doc/source/format_intro.rst | |
parent | 19cd954bf9e22cbd6b7adacc9d87a693811830dc (diff) | |
download | buildstream-171e803f5dab2644c7bcd2e22acecef64880e1ce.tar.gz |
Add support for include '(@)' in project.conf and .bst files
Fixes #331.
Diffstat (limited to 'doc/source/format_intro.rst')
-rw-r--r-- | doc/source/format_intro.rst | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/doc/source/format_intro.rst b/doc/source/format_intro.rst index b1780f9dc..23c37aeae 100644 --- a/doc/source/format_intro.rst +++ b/doc/source/format_intro.rst @@ -289,3 +289,47 @@ free form and not validated. # This element's `make install` is broken, replace it. (=): - cp src/program %{bindir} + +(@) Include +~~~~~~~~~~~ +Indicates that content should be loaded from files. + +This 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 +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. + +The including YAML fragment has priority over the files it includes, +and overrides any values introduced by the includes. When including +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. + +.. 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 + <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>` |