diff options
author | Josh Smith <joshsmith@codethink.co.uk> | 2018-08-08 14:02:45 +0100 |
---|---|---|
committer | Josh Smith <qinusty@gmail.com> | 2018-08-15 12:15:58 +0100 |
commit | c9dd51f2a69997a60387a2c468c9a013b73d7955 (patch) | |
tree | 291697da711bc44ed38dc3dea3883c1b3f6348fa | |
parent | 4669309e8417f15704d8132f1aa660a8d38887db (diff) | |
download | buildstream-c9dd51f2a69997a60387a2c468c9a013b73d7955.tar.gz |
docs: Add documentation for Configurable Warnings
This includes detailing the use of `fatal-warnings` within project.conf
-rw-r--r-- | buildstream/plugin.py | 19 | ||||
-rw-r--r-- | doc/source/format_project.rst | 29 |
2 files changed, 36 insertions, 12 deletions
diff --git a/buildstream/plugin.py b/buildstream/plugin.py index 64b38ff99..4514ee355 100644 --- a/buildstream/plugin.py +++ b/buildstream/plugin.py @@ -47,6 +47,23 @@ it is mandatory to implement the following abstract methods: Once all configuration has been loaded and preflight checks have passed, this method is used to inform the core of a plugin's unique configuration. +Configurable Warnings +--------------------- +Warnings raised through calling :func:`Plugin.warn() <buildstream.plugin.Plugin.warn>` can provide an optional +parameter ``warning_token``, this will raise a :class:`PluginError` if the warning is configured as fatal within +the project configuration. + +Configurable warnings will be prefixed with :func:`Plugin.get_kind() <buildstream.plugin.Plugin.get_kind>` +within buildstream and must be prefixed as such in project configurations. For more detail on project configuration +see :ref:`Configurable Warnings <configurable_warnings>`. + +It is important to document these warnings in your plugin documentation to allow users to make full use of them +while configuring their projects. + +Example +~~~~~~~ +If the :class:`git <buildstream.plugins.sources.git.GitSource>` plugin uses the warning ``"inconsistent-submodule"`` +then it could be referenced in project configuration as ``"git:inconsistent-submodule"``. Plugin Structure ---------------- @@ -731,7 +748,7 @@ class CoreWarnings(): OVERLAPS = "overlaps" """ This warning will be produced when buildstream detects an overlap on an element - which is not whitelisted. + which is not whitelisted. See :ref:`Overlap Whitelist <public_overlap_whitelist>` """ REF_NOT_IN_TRACK = "ref-not-in-track" diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst index cf0970f77..b43e67005 100644 --- a/doc/source/format_project.rst +++ b/doc/source/format_project.rst @@ -126,22 +126,29 @@ following to your ``project.conf``: The ``ref-storage`` configuration is available since :ref:`format version 8 <project_format_version>` -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. +.. _configurable_warnings: -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. +Configurable Warnings +~~~~~~~~~~~~~~~~~~~~~ +Warnings can be configured as fatal using the ``fatal-warnings`` configuration item. +When a warning is configured as fatal, where a warning would usually be thrown instead an error will be thrown +causing the build to fail. -otherwise, a warning will be raised indicating which files had overlaps, -and the order that the elements were overlapped. +Individual warnings can be configured as fatal by setting ``fatal-warnings`` to a list of warnings. .. code:: yaml - fail-on-overlap: true + fatal-warnings: + - overlaps + - ref-not-in-track + - <plugin>:<warning> + +BuildStream provides a collection of :class:`Core Warnings <buildstream.plugin.CoreWarnings>` which may be raised +by a variety of plugins. Other configurable warnings are plugin specific and should be noted within their individual documentation. + +.. note:: + + The ``fatal-warnings`` configuration is available since :ref:`format version 14 <project_format_version>` .. _project_source_aliases: |