[rtems-docs commit] eng: Improve build option default values

[Sebastian Huber]

Module:    rtems-docs
Branch:    master
Commit:    f3811f29a8afa1810204d9c845ab33eb0f3fbd45
Changeset: http://git.rtems.org/rtems-docs/commit/?id=f3811f29a8afa1810204d9c845ab33eb0f3fbd45

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Jan 17 15:14:02 2023 +0100

eng: Improve build option default values

Merge "default" and "default-by-variant" attributes.  Use an enabled-by
expression to select the default value.

---

 eng/req/items.rst | 62 ++++++++++++++++++++++---------------------------------
 1 file changed, 25 insertions(+), 37 deletions(-)

diff --git a/eng/req/items.rst b/eng/req/items.rst
index eb7ce38..c037a93 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -714,8 +714,6 @@ option. The following explicit attributes are mandatory:
 
 * ``default``
 
-* ``default-by-variant``
-
 * ``description``
 
 The explicit attributes for this type are:
@@ -729,19 +727,11 @@ actions
     actions are carried out during the configure command execution.
 
 default
-    The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. It shall be
-    the default value of the option if no variant-specific default value is
-    specified.  Use ``null`` to specify that no default value exits.  The
-    variant-specific default values may be specified by the
-    ``default-by-variant`` attribute.
-
-default-by-variant
     The attribute value shall be a list. Each list element shall be a
-    :ref:`SpecTypeBuildOptionDefaultByVariant`. The list is checked two times
-    and processed from top to bottom. Firstly, the base BSP name is used to
-    match with a variant. Secondly, the BSP family name prefixed by ``bsps/``
-    is used to match with a variant.  If a matching variant is found, then the
-    processing stops.
+    :ref:`SpecTypeBuildOptionDefaultValue`. It shall be the list of default
+    values of the option.  When a default value is needed, the first value on
+    the list which is enabled according to the enabled set is choosen.  If no
+    value is enabled, then the default value is ``null``.
 
 description
     The attribute value shall be an optional string. It shall be the
@@ -766,17 +756,17 @@ Please have a look at the following example:
     - define: null
     build-type: option
     copyrights:
-    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-    default: 115200
-    default-by-variant:
-    - value: 9600
-      variants:
+    - Copyright (C) 2020, 2022 embedded brains GmbH (http://www.embedded-brains.de)
+    default:
+    - enabled-by:
       - bsps/powerpc/motorola_powerpc
       - m68k/m5484FireEngine
       - powerpc/hsc_cm01
-    - value: 19200
-      variants:
-      - m68k/COBRA5475
+      value: 9600
+    - enabled-by: m68k/COBRA5475
+      value: 19200
+    - enabled-by: true
+      value: 115200
     description: |
       Default baud for console and other serial devices.
     enabled-by: true
@@ -3423,22 +3413,20 @@ This type is used by the following types:
 
 * :ref:`SpecTypeBuildOptionAction`
 
-.. _SpecTypeBuildOptionDefaultByVariant:
+.. _SpecTypeBuildOptionDefaultValue:
 
-Build Option Default by Variant
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Build Option Default Value
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This set of attributes specifies build option default values by variant. All
-explicit attributes shall be specified. The explicit attributes for this type
-are:
+This set of attributes specifies a build option default value. All explicit
+attributes shall be specified. The explicit attributes for this type are:
 
-value
-    The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. It value
-    shall be the default value for the matching variants.
+enabled-by
+    The attribute value shall be an :ref:`SpecTypeEnabledByExpression`.
 
-variants
-    The attribute value shall be a list of strings. It shall be a list of
-    Python regular expression matching with the desired variants.
+value
+    The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. Its value
+    shall be the default value for the associated enabled-by expression.
 
 This type is used by the following types:
 
@@ -3495,9 +3483,7 @@ This type is used by the following types:
 
 * :ref:`SpecTypeBuildOptionAction`
 
-* :ref:`SpecTypeBuildOptionDefaultByVariant`
-
-* :ref:`SpecTypeBuildOptionItemType`
+* :ref:`SpecTypeBuildOptionDefaultValue`
 
 .. _SpecTypeBuildSource:
 
@@ -3681,6 +3667,8 @@ This type is used by the following types:
 
 * :ref:`SpecTypeActionRequirementTransition`
 
+* :ref:`SpecTypeBuildOptionDefaultValue`
+
 * :ref:`SpecTypeEnabledByExpression`
 
 * :ref:`SpecTypeInterfaceIncludeLinkRole`