diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2017-10-14 18:18:21 +0900 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2017-10-14 18:18:21 +0900 |
commit | bed926b0d8bced4a058f72656214a8febc9db1b0 (patch) | |
tree | 90ac1517a99bbe7c4b4377ff627473e9a5ba213b /doc | |
parent | 3944b2d1debba6cc3e2cfdb18cd611cef7b8434d (diff) | |
download | buildstream-bed926b0d8bced4a058f72656214a8febc9db1b0.tar.gz |
doc/source/projectconf.rst: Document option variable exporting feature
Diffstat (limited to 'doc')
-rw-r--r-- | doc/source/projectconf.rst | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/doc/source/projectconf.rst b/doc/source/projectconf.rst index 2f4d997bc..2a03cf538 100644 --- a/doc/source/projectconf.rst +++ b/doc/source/projectconf.rst @@ -144,11 +144,37 @@ dictionary. default: False +Common Properties +~~~~~~~~~~~~~~~~~ +All option types accept the following common attributes + +* ``type`` + + Indicates the type of option to declare + +* ``description`` + + A description of the meaning of the option + +* ``variable`` + + Optionally indicate a :ref:`variable <format_variables>` name to + export the option to. A string form of the selected option will + be used to set the exported value. + + If used, this value will override any existing value for the + variable declared in ``project.conf``, and will be overridden in + the regular :ref:`composition order <format_composition>`. + + Boolean ~~~~~~~ The ``bool`` option type allows specifying boolean values which can be cased in conditional expressions. + +**Declaring** + .. code:: yaml options: @@ -157,6 +183,9 @@ can be cased in conditional expressions. description: Whether to enable debugging default: False + +**Evaluating** + Boolean options can be tested in expressions with equality tests: .. code:: yaml @@ -177,11 +206,21 @@ Or simply treated as truthy values: - debug: enable-debug: True + +**Exporting** + +When exporting boolean options as variables, a ``True`` option value +will be exported as ``1`` and a ``False`` option as ``0`` + + Enumeration ~~~~~~~~~~~ The ``enum`` option type allows specifying a string value with a restricted set of possible values. + +**Declaring** + .. code:: yaml options: @@ -194,6 +233,9 @@ with a restricted set of possible values. - warning default: info + +**Evaluating** + Enumeration options must be tested as strings in conditional expressions: @@ -206,6 +248,12 @@ expressions: enable-debug: True +**Exporting** + +When exporting enumeration options as variables, the value is +exported as a variable directly, as it is a simple string. + + Flags ~~~~~ The ``flags`` option type allows specifying a list of string @@ -214,6 +262,9 @@ values with a restricted set of possible values. In contrast with the ``enum`` option type, the *default* value need not be specified and will default to an empty set. + +**Declaring** + .. code:: yaml options: @@ -227,6 +278,9 @@ need not be specified and will default to an empty set. default: - info + +**Evaluating** + Flags type options can be tested in conditional expressions using a pythonic *in* syntax to test if an element is present in a set: @@ -239,6 +293,12 @@ a pythonic *in* syntax to test if an element is present in a set: enable-debug: True +**Exporting** + +When exporting flags options as variables, the value is +exported as a comma separated list of selected value strings. + + Architecture ~~~~~~~~~~~~ The ``arch`` type option is special enumeration option which |