diff options
-rw-r--r-- | buildstream/plugin.py | 48 | ||||
-rw-r--r-- | doc/source/format.rst | 6 | ||||
-rw-r--r-- | doc/source/index.rst | 1 | ||||
-rw-r--r-- | doc/source/sample_plugin/MANIFEST.in | 1 | ||||
-rw-r--r-- | doc/source/sample_plugin/setup.py | 15 |
5 files changed, 70 insertions, 1 deletions
diff --git a/buildstream/plugin.py b/buildstream/plugin.py index 110d865f5..5be2255e5 100644 --- a/buildstream/plugin.py +++ b/buildstream/plugin.py @@ -19,7 +19,52 @@ # Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> """ Plugin -====== +======= +BuildStream supports third party plugins to define additional kinds of +elements and sources. + +Plugin Structure +---------------- +A plugin should consist of a `setuptools package +<http://setuptools.readthedocs.io/en/latest/setuptools.html>`_ that +advertises contained plugins using `entry points +<http://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins>`_. + +A plugin entry point must be a module that extends a class in the +:ref:`core_framework` to be discovered by BuildStream. A YAML file +defining plugin default settings with the same name as the module can +also be defined in the same directory as the plugin module. + +.. note:: + + BuildStream does not support function/class entry points. + +A sample plugin could be structured as such: + +.. code-block:: text + + . + ├── elements + │ ├── autotools.py + │ ├── autotools.yaml + │ └── __init__.py + ├── MANIFEST.in + └── setup.py + +The setuptools configuration should then contain at least: + +setup.py: + +.. literalinclude:: ../source/sample_plugin/setup.py + :language: python + +MANIFEST.in: + +.. literalinclude:: ../source/sample_plugin/setup.py + :language: text + +Class Reference +--------------- """ import os @@ -44,6 +89,7 @@ class Plugin(): Some common features to both Sources and Elements are found in this class. + """ BST_REQUIRED_VERSION_MAJOR = 0 diff --git a/doc/source/format.rst b/doc/source/format.rst index ebe8e2636..6be1893f9 100644 --- a/doc/source/format.rst +++ b/doc/source/format.rst @@ -152,6 +152,12 @@ The ``kind`` attribute specifies which plugin will be operating on the element's produce its output. Plugins define element types and each of them can be referred to by name with the ``kind`` attribute. +To refer to a third party plugin, prefix the plugin with its package, for example: + +.. code:: yaml + + kind: buildstream-plugins:dpkg_build + Depends ~~~~~~~ diff --git a/doc/source/index.rst b/doc/source/index.rst index 5a06b501d..1d9477740 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -79,6 +79,7 @@ The following source types are provided with BuildStream: * :mod:`ostree <sources.ostree>` - A Source implementation for ostree * :mod:`patch <sources.patch>` - A Source implementation for applying local patches +.. _core_framework: Core Framework -------------- diff --git a/doc/source/sample_plugin/MANIFEST.in b/doc/source/sample_plugin/MANIFEST.in new file mode 100644 index 000000000..2be67bf4e --- /dev/null +++ b/doc/source/sample_plugin/MANIFEST.in @@ -0,0 +1 @@ +global-include *.yaml diff --git a/doc/source/sample_plugin/setup.py b/doc/source/sample_plugin/setup.py new file mode 100644 index 000000000..7ea0e1ef3 --- /dev/null +++ b/doc/source/sample_plugin/setup.py @@ -0,0 +1,15 @@ +from setuptools import setup, find_packages + +setup(name='BuildStream Autotools', + version="0.1", + description="A better autotools element for BuildStream", + packages=find_packages(), + install_requires=[ + 'setuptools' + ], + include_package_data=True, + entry_points={ + 'buildstream.plugins': [ + 'autotools = elements.autotools' + ] + }) |