diff options
Diffstat (limited to 'doc/source/index/authoring')
-rw-r--r-- | doc/source/index/authoring/projectconf.rst | 50 |
1 files changed, 23 insertions, 27 deletions
diff --git a/doc/source/index/authoring/projectconf.rst b/doc/source/index/authoring/projectconf.rst index 9fe28cea2..8ecd30b06 100644 --- a/doc/source/index/authoring/projectconf.rst +++ b/doc/source/index/authoring/projectconf.rst @@ -24,6 +24,12 @@ Essentials Project Name ~~~~~~~~~~~~ +The project name is a unique symbol for your project and will +be used to distinguish your project from others in user preferences, +namspaceing of your project's artifacts in shared artifact caches, +and in any case where BuildStream needs to distinguish between multiple +projects. + The first thing to setup in your ``project.conf`` should be the name of your project. @@ -31,8 +37,10 @@ of your project. name: my-project-name -The project name will be used in user configuration and anywhere -that a project needs to be specified. +.. note:: + + The project name may contain alphanumeric characters, dashes and + underscores, and may not start with a leading digit. .. _project_format_version: @@ -55,7 +63,7 @@ to support a new feature. .. note:: - :mod:`Element <buildstream.element>` and :mod:`Source <buildstream.source>` + External :mod:`Element <buildstream.element>` and :mod:`Source <buildstream.source>` plugins also implement their own YAML configuration fragments and as such are revisioned separately from the core format. See :ref:`project_plugins` for details on specifying a minimum version of a specific plugin. @@ -193,34 +201,11 @@ External Plugins ---------------- If your project makes use of any custom :mod:`Element <buildstream.element>` or :mod:`Source <buildstream.source>` plugins, then the project must inform BuildStream -of the plugins it means to make use of and the origin from which it can be loaded. +of the plugins it means to make use of and the origin from which they can be loaded. Note that plugins with the same name from different origins are not permitted. -Core plugins -~~~~~~~~~~~~ -Plugins provided by the BuildStream core need not be explicitly specified -here, but you may use this section to specify a minimal format version -to ensure that they provide the features which your project requires. - -.. code:: yaml - - plugins: - - origin: core - - # We require a new feature of the `git` source plugin, and - # a new feature introduced in version 2 of the `patch` plugin. - sources: - git: 1 - patch: 2 - - # ... And a new feature of the `script` element, added - # in version 2 of it's own format version. - elements: - script: 2 - - Local Plugins ~~~~~~~~~~~~~ Local plugins are expected to be found in a subdirectory of the actual @@ -296,6 +281,11 @@ Users can configure those options when invoking BuildStream with the $ bst --option debug True ... +.. note:: + + The name of the option may contain alphanumeric characters + underscores, and may not start with a leading digit. + Common Properties ~~~~~~~~~~~~~~~~~ @@ -319,6 +309,12 @@ All option types accept the following common attributes variable declared in ``project.conf``, and will be overridden in the regular :ref:`composition order <format_composition>`. + .. note:: + + The name of the variable to export may contain alphanumeric + characters, dashes, underscores, and may not start with a leading + digit. + Boolean ~~~~~~~ |