diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-06-12 23:20:14 -0400 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-06-13 00:24:27 -0400 |
commit | 9d7296eb84d604a02e5e9f989a09cb30994503c1 (patch) | |
tree | 2d70e86dd7eedb8eba066d063df61d6b9871473c /doc/source/format_public.rst | |
parent | 53bc7272edb232b22c290017ecff0ce6972b3771 (diff) | |
download | buildstream-9d7296eb84d604a02e5e9f989a09cb30994503c1.tar.gz |
doc: Overhaul of page names and titles
o Giving main pages simple word titles
This makes the main page:
* About
* Installing
* Using
* Reference
* Contributing
o Now named all rst files with their parent page name as a prefix.
o Also changed some titles to make overall consistent titles.
Diffstat (limited to 'doc/source/format_public.rst')
-rw-r--r-- | doc/source/format_public.rst | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/doc/source/format_public.rst b/doc/source/format_public.rst new file mode 100644 index 000000000..e640de7bb --- /dev/null +++ b/doc/source/format_public.rst @@ -0,0 +1,102 @@ + +Builtin public data +=================== +Elements can provide public data which can be read by other elements +later in the pipeline, the format for exposing public data on a given +element is :ref:`described here <format_public>`. + +Any element may use public data for whatever purpose it wants, but +BuildStream has some built-in expectations of public data, which resides +completely in the ``bst`` domain. + +In this section we will describe the public data in the ``bst`` domain. + + +.. _public_integration: + +Integration commands +-------------------- + +.. code:: yaml + + # Specify some integration commands + public: + bst: + integration-commands: + - /usr/bin/update-fancy-feature-cache + +The built-in ``integration-commands`` list indicates that depending elements +should run this set of commands before expecting the staged runtime environment +to be functional. + +Typical cases for this include running ``ldconfig`` at the base of a pipeline, +or running commands to update various system caches. + +Integration commands of a given element are automatically run by the +:func:`Element.integrate() <buildstream.element.Element.integrate>` method +and are used by various plugins. + +Notably the :mod:`BuildElement <buildstream.buildelement>` derived classes +will always integrate the build dependencies after staging and before running +any build commands. + + +.. _public_split_rules: + +Split rules +----------- + +.. code:: yaml + + # Specify some split rules + public: + bst: + split-rules: + runtime: + - | + %{bindir}/* + - | + %{sbindir}/* + - | + %{libexecdir}/* + - | + %{libdir}/lib*.so* + +Split rules indicate how the output of an element can be categorized +into *domains*. + +The ``split-rules`` domains are used by the +:func:`Element.stage_artifact() <buildstream.element.Element.stage_artifact>` +method when deciding what domains of an artifact should be staged. + +The strings listed in each domain are first substituted with the +:ref:`variables <format_variables>` in context of the given element, and +then applied as a glob style match, as understood by +:func:`utils.glob() <buildstream.utils.glob>` + +This is used for creating compositions with the :mod:`compose <elements.compose>` +element and can be used by other deployment related elements for the purpose of +splitting element artifacts into separate packages. + + +.. _public_overlap_whitelist: + +Overlap whitelist +----------------- + +The overlap whitelist indicates which files this element is allowed to overlap +over other elements when staged together with other elements. + +Each item in the overlap whitelist has substitutions applied from +:ref:`variables <format_variables>`, and is then applied as a glob-style match +(i.e. :func:`utils.glob() <buildstream.utils.glob>`). + +.. code:: yaml + + public: + bst: + overlap-whitelist: + - | + %{sysconfdir}/* + - | + /etc/fontcache |