diff options
| author | Jonathan Maw <jonathan.maw@codethink.co.uk> | 2017-12-13 17:23:53 +0000 |
|---|---|---|
| committer | Jonathan Maw <jonathan.maw@codethink.co.uk> | 2018-01-25 13:27:42 +0000 |
| commit | b1bd7862eb021b66764c60937ec467c7947adf5f (patch) | |
| tree | 5abb86ff177e49644c266f326e9d7135d518ce2b | |
| parent | efbf144e3d5e433c20f2646040548008e82d9a60 (diff) | |
| download | buildstream-164-minimise-overlaps-by-having-overlaps-raise-exceptions-unless-configured-not-to.tar.gz | |
doc: Explain overlap-whitelist and fail-on-overlap164-minimise-overlaps-by-having-overlaps-raise-exceptions-unless-configured-not-to
| -rw-r--r-- | doc/source/projectconf.rst | 17 | ||||
| -rw-r--r-- | doc/source/public.rst | 23 |
2 files changed, 40 insertions, 0 deletions
diff --git a/doc/source/projectconf.rst b/doc/source/projectconf.rst index d7f609b39..9af52d65a 100644 --- a/doc/source/projectconf.rst +++ b/doc/source/projectconf.rst @@ -190,6 +190,23 @@ system. elements: potato: 0 +Fail on Overlaps +~~~~~~~~~~~~~~~~ +When multiple elements are staged, there's a possibility that different +elements will try and stage different versions of the same file. + +When ``fail-on-overlap`` is true, if an overlap is detected +that hasn't been allowed by the element's +:ref:`overlap whitelist<public_overlap_whitelist>`, +then an error will be raised and the build will fail. + +otherwise, a warning will be raised indicating which files had overlaps, +and the order that the elements were overlapped. + +.. code:: yaml + + fail-on-overlap: true + .. _project_options: diff --git a/doc/source/public.rst b/doc/source/public.rst index 7a0da8e63..b9468cb00 100644 --- a/doc/source/public.rst +++ b/doc/source/public.rst @@ -82,3 +82,26 @@ then applied as a glob style match, as understood by 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 |