diff options
author | Chandan Singh <chandan.devel@gmail.com> | 2018-10-25 16:59:13 +0000 |
---|---|---|
committer | Chandan Singh <chandan.devel@gmail.com> | 2018-10-25 16:59:13 +0000 |
commit | 356d84cdce6c44516d09ab561e10545434e4a609 (patch) | |
tree | 9aadc2949fec507a19f586e082583a1301de7d54 | |
parent | 1c1d14e7111edf244f1c93b2f0a2ba5088b6bffd (diff) | |
parent | db2a676e292f2970c4d03661c5ed7db63717f744 (diff) | |
download | buildstream-356d84cdce6c44516d09ab561e10545434e4a609.tar.gz |
Merge branch 'chandan/source-doc-directory' into 'master'
plugins: Don't redundantly document common configurations
Closes #713
See merge request BuildStream/buildstream!896
23 files changed, 63 insertions, 34 deletions
diff --git a/buildstream/buildelement.py b/buildstream/buildelement.py index e57ca1c79..48b7f2423 100644 --- a/buildstream/buildelement.py +++ b/buildstream/buildelement.py @@ -23,6 +23,8 @@ BuildElement - Abstract class for build elements The BuildElement class is a convenience element one can derive from for implementing the most common case of element. +.. _core_buildelement_builtins: + Built-in functionality ---------------------- diff --git a/buildstream/plugins/elements/autotools.py b/buildstream/plugins/elements/autotools.py index cf5e85661..43fe7add4 100644 --- a/buildstream/plugins/elements/autotools.py +++ b/buildstream/plugins/elements/autotools.py @@ -50,6 +50,9 @@ Here is the default configuration for the ``autotools`` element in full: .. literalinclude:: ../../../buildstream/plugins/elements/autotools.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/elements/cmake.py b/buildstream/plugins/elements/cmake.py index 2cb2601ae..de9aa9616 100644 --- a/buildstream/plugins/elements/cmake.py +++ b/buildstream/plugins/elements/cmake.py @@ -49,6 +49,9 @@ Here is the default configuration for the ``cmake`` element in full: .. literalinclude:: ../../../buildstream/plugins/elements/cmake.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/elements/distutils.py b/buildstream/plugins/elements/distutils.py index 5201013c1..20a2d67ef 100644 --- a/buildstream/plugins/elements/distutils.py +++ b/buildstream/plugins/elements/distutils.py @@ -26,6 +26,9 @@ python distutils The distutils default configuration: .. literalinclude:: ../../../buildstream/plugins/elements/distutils.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/elements/import.py b/buildstream/plugins/elements/import.py index 0eca2a902..ec491a0a5 100644 --- a/buildstream/plugins/elements/import.py +++ b/buildstream/plugins/elements/import.py @@ -28,6 +28,9 @@ some configuration data. The empty configuration is as such: .. literalinclude:: ../../../buildstream/plugins/elements/import.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ import os diff --git a/buildstream/plugins/elements/make.py b/buildstream/plugins/elements/make.py index 6c500f3f9..a22de168a 100644 --- a/buildstream/plugins/elements/make.py +++ b/buildstream/plugins/elements/make.py @@ -31,6 +31,9 @@ Here is the default configuration for the ``make`` element in full: .. literalinclude:: ../../../buildstream/plugins/elements/make.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/elements/makemaker.py b/buildstream/plugins/elements/makemaker.py index fccfaadab..8ad979984 100644 --- a/buildstream/plugins/elements/makemaker.py +++ b/buildstream/plugins/elements/makemaker.py @@ -26,6 +26,9 @@ the Perl ExtUtil::MakeMaker build system The MakeMaker default configuration: .. literalinclude:: ../../../buildstream/plugins/elements/makemaker.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/elements/manual.py b/buildstream/plugins/elements/manual.py index c7bdba95f..3300d017a 100644 --- a/buildstream/plugins/elements/manual.py +++ b/buildstream/plugins/elements/manual.py @@ -26,6 +26,9 @@ add custom build commands to the array understood by the :mod:`BuildElement <bui The empty configuration is as such: .. literalinclude:: ../../../buildstream/plugins/elements/manual.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/elements/meson.py b/buildstream/plugins/elements/meson.py index 9e0edf19e..0d5ca0087 100644 --- a/buildstream/plugins/elements/meson.py +++ b/buildstream/plugins/elements/meson.py @@ -46,6 +46,9 @@ Here is the default configuration for the ``meson`` element in full: .. literalinclude:: ../../../buildstream/plugins/elements/meson.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/elements/modulebuild.py b/buildstream/plugins/elements/modulebuild.py index 5189af1a6..d619a1d01 100644 --- a/buildstream/plugins/elements/modulebuild.py +++ b/buildstream/plugins/elements/modulebuild.py @@ -26,6 +26,9 @@ the Perl Module::Build build system The modulebuild default configuration: .. literalinclude:: ../../../buildstream/plugins/elements/modulebuild.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/elements/pip.py b/buildstream/plugins/elements/pip.py index e62f713a6..02b593af3 100644 --- a/buildstream/plugins/elements/pip.py +++ b/buildstream/plugins/elements/pip.py @@ -26,6 +26,9 @@ Python modules with pip The pip default configuration: .. literalinclude:: ../../../buildstream/plugins/elements/pip.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/elements/qmake.py b/buildstream/plugins/elements/qmake.py index 9f5bc4018..d6776b0b2 100644 --- a/buildstream/plugins/elements/qmake.py +++ b/buildstream/plugins/elements/qmake.py @@ -26,6 +26,9 @@ the qmake build system The qmake default configuration: .. literalinclude:: ../../../buildstream/plugins/elements/qmake.yaml :language: yaml + +See :ref:`built-in functionality documentation <core_buildelement_builtins>` for +details on common configuration options for build elements. """ from buildstream import BuildElement diff --git a/buildstream/plugins/sources/bzr.py b/buildstream/plugins/sources/bzr.py index 3afd0f04f..f52472918 100644 --- a/buildstream/plugins/sources/bzr.py +++ b/buildstream/plugins/sources/bzr.py @@ -31,9 +31,6 @@ bzr - stage files from a bazaar repository # Specify the bzr source kind kind: bzr - # Optionally specify a relative staging directory - # directory: path/to/stage - # Specify the bzr url. Bazaar URLs come in many forms, see # `bzr help urlspec` for more information. Using an alias defined # in your project configuration is encouraged. @@ -53,6 +50,8 @@ bzr - stage files from a bazaar repository # revision number to the one on the tip of the branch specified in 'track'. ref: 6622 +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. """ import os diff --git a/buildstream/plugins/sources/deb.py b/buildstream/plugins/sources/deb.py index e1d4b65d1..1b7dafd31 100644 --- a/buildstream/plugins/sources/deb.py +++ b/buildstream/plugins/sources/deb.py @@ -33,9 +33,6 @@ deb - stage files from .deb packages # Specify the deb source kind kind: deb - # Optionally specify a relative staging directory - # directory: path/to/stage - # Specify the deb url. Using an alias defined in your project # configuration is encouraged. 'bst track' will update the # sha256sum in 'ref' to the downloaded file's sha256sum. @@ -47,6 +44,8 @@ deb - stage files from .deb packages # Specify the basedir to return only the specified dir and its children base-dir: '' +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. """ import tarfile diff --git a/buildstream/plugins/sources/git.py b/buildstream/plugins/sources/git.py index ced52d023..23e3369b1 100644 --- a/buildstream/plugins/sources/git.py +++ b/buildstream/plugins/sources/git.py @@ -32,9 +32,6 @@ git - stage files from a git repository # Specify the git source kind kind: git - # Optionally specify a relative staging directory - # directory: path/to/stage - # Specify the repository url, using an alias defined # in your project configuration is recommended. url: upstream:foo.git @@ -74,6 +71,9 @@ git - stage files from a git repository url: upstream:baz.git checkout: False +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. + **Configurable Warnings:** This plugin provides the following configurable warnings: diff --git a/buildstream/plugins/sources/local.py b/buildstream/plugins/sources/local.py index 8b18f9b59..bbb42d06a 100644 --- a/buildstream/plugins/sources/local.py +++ b/buildstream/plugins/sources/local.py @@ -29,11 +29,11 @@ local - stage local files and directories # Specify the local source kind kind: local - # Optionally specify a relative staging directory - # directory: path/to/stage - # Specify the project relative path to a file or directory path: files/somefile.txt + +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. """ import os diff --git a/buildstream/plugins/sources/ostree.py b/buildstream/plugins/sources/ostree.py index 177bdcc4f..770cfd55f 100644 --- a/buildstream/plugins/sources/ostree.py +++ b/buildstream/plugins/sources/ostree.py @@ -29,9 +29,6 @@ ostree - stage files from an OSTree repository # Specify the ostree source kind kind: ostree - # Optionally specify a relative staging directory - # directory: path/to/stage - # Specify the repository url, using an alias defined # in your project configuration is recommended. url: upstream:runtime @@ -48,6 +45,9 @@ ostree - stage files from an OSTree repository # For signed ostree repositories, specify a local project relative # path to the public verifying GPG key for this remote. gpg-key: keys/runtime.gpg + +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. """ import os diff --git a/buildstream/plugins/sources/patch.py b/buildstream/plugins/sources/patch.py index 2fa002080..8e833b411 100644 --- a/buildstream/plugins/sources/patch.py +++ b/buildstream/plugins/sources/patch.py @@ -37,12 +37,11 @@ patch - apply locally stored patches # Specify the project relative path to a patch file path: files/somefile.diff - # Optionally specify the root directory for the patch - # directory: path/to/stage - # Optionally specify the strip level, defaults to 1 strip-level: 1 +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. """ import os diff --git a/buildstream/plugins/sources/pip.py b/buildstream/plugins/sources/pip.py index 18e65c73d..6ba3a0407 100644 --- a/buildstream/plugins/sources/pip.py +++ b/buildstream/plugins/sources/pip.py @@ -54,19 +54,18 @@ Downloaded tarballs will be stored in a directory called ".bst_pip_downloads". packages: - flake8 - # Optionally specify a relative staging directory - directory: path/to/stage - # Specify the ref. It is a list of strings of format # "<package-name>==<version>", separated by "\\n". # Usually this will be contents of a requirements.txt file where all # package versions have been frozen. ref: "flake8==3.5.0\\nmccabe==0.6.1\\npkg-resources==0.0.0\\npycodestyle==2.3.1\\npyflakes==1.6.0" +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. + .. note:: The ``pip`` plugin is available since :ref:`format version 16 <project_format_version>` - """ import errno diff --git a/buildstream/plugins/sources/remote.py b/buildstream/plugins/sources/remote.py index a0809cb10..a6b02fd1c 100644 --- a/buildstream/plugins/sources/remote.py +++ b/buildstream/plugins/sources/remote.py @@ -28,9 +28,6 @@ remote - stage files from remote urls # Specify the remote source kind kind: remote - # Optionally specify a relative staging directory - # directory: path/to/stage - # Optionally specify a relative staging filename. # If not specified, the basename of the url will be used. # filename: customfilename @@ -47,12 +44,12 @@ remote - stage files from remote urls # Specify the ref. It's a sha256sum of the file you download. ref: 6c9f6f68a131ec6381da82f2bff978083ed7f4f7991d931bfa767b7965ebc94b - +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. .. note:: The ``remote`` plugin is available since :ref:`format version 10 <project_format_version>` - """ import os from buildstream import SourceError, utils diff --git a/buildstream/plugins/sources/tar.py b/buildstream/plugins/sources/tar.py index 8bbc8fce5..195c05958 100644 --- a/buildstream/plugins/sources/tar.py +++ b/buildstream/plugins/sources/tar.py @@ -32,9 +32,6 @@ tar - stage files from tar archives # Specify the tar source kind kind: tar - # Optionally specify a relative staging directory - # directory: path/to/stage - # Specify the tar url. Using an alias defined in your project # configuration is encouraged. 'bst track' will update the # sha256sum in 'ref' to the downloaded file's sha256sum. @@ -53,6 +50,9 @@ tar - stage files from tar archives # To extract the root of the tarball directly, this can be set # to an empty string. base-dir: '*' + +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. """ import os diff --git a/buildstream/plugins/sources/zip.py b/buildstream/plugins/sources/zip.py index 0bbb2cd27..f5fac3a48 100644 --- a/buildstream/plugins/sources/zip.py +++ b/buildstream/plugins/sources/zip.py @@ -28,9 +28,6 @@ zip - stage files from zip archives # Specify the zip source kind kind: zip - # Optionally specify a relative staging directory - # directory: path/to/stage - # Specify the zip url. Using an alias defined in your project # configuration is encouraged. 'bst track' will update the # sha256sum in 'ref' to the downloaded file's sha256sum. @@ -50,11 +47,13 @@ zip - stage files from zip archives # to an empty string. base-dir: '*' +See :ref:`built-in functionality doumentation <core_source_builtins>` for +details on common configuration options for sources. + .. attention:: File permissions are not preserved. All extracted directories have permissions 0755 and all extracted files have permissions 0644. - """ import os diff --git a/buildstream/source.py b/buildstream/source.py index 483fd2341..af0ba0d96 100644 --- a/buildstream/source.py +++ b/buildstream/source.py @@ -20,6 +20,8 @@ Source - Base source class ========================== +.. _core_source_builtins: + Built-in functionality ---------------------- |