[PATCH 1/2] eng: Add application config options how-to

[Sebastian Huber]

Update #3715.
---
 eng/req/howto.rst | 118 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)

diff --git a/eng/req/howto.rst b/eng/req/howto.rst
index 9a28427..475794c 100644
--- a/eng/req/howto.rst
+++ b/eng/req/howto.rst
@@ -34,6 +34,124 @@ environment in your shell:
     cd rtems-qual
     . env/bin/activate
 
+Application Configuration Options
+---------------------------------
+
+The application configuration options and groups are maintained by
+specification items in the directory :file:`spec/if/acfg`.  Application
+configuration options are grouped by
+:ref:`SpecTypeApplicationConfigurationGroupItemType` items which should be
+stored in files using the :file:`spec/if/acfg/group-*.yml` pattern.  Each
+application configuration options shall link to exactly one group item with the
+:ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole`.  There are four
+application option item types available which cover all existing options:
+
+* The *feature enable options* enable feature.  If the option is not defined by
+  the application configuration, then the feature is simply not available or
+  active.  There should be no feature-specific code linked to the application
+  if the option is not defined.  Examples are options which enable a device
+  driver like ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``.  These options are
+  specified by
+  :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` items.
+
+* The *feature options* enable a feature if the option is defined by the
+  application configuration, otherwise another feature is active.  If the
+  option is not defined, then feature-specific code may linked to the
+  application.  Examples are options which disable a feature if the option is
+  defined such as ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` and options
+  which provide a stub implementation of a feature by default and a full
+  implementation if the option is defined such as
+  ``CONFIGURE_IMFS_ENABLE_MKFIFO``.  These options are specified by
+  :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` items.
+
+* The *integer value options* let the application define a specific value for a
+  system parameter.  If the option is not defined, then a default value is used
+  for the system parameter.  Examples are options which define the maximum
+  count of objects available for application use such as
+  ``CONFIGURE_MAXIMUM_TASKS``.  These options are specified by
+  :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items.
+
+* The *initializer options* let the application define a specific initializer
+  for a system parameter.  If the option is not defined, then a default setting
+  is used for the system parameter.  An example option of this type is
+  ``CONFIGURE_INITIAL_EXTENSIONS``.  These options are specified by
+  :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items.
+
+From the specification items Sphinx documentation sources and header files with
+Doxygen markup are generated.  The descriptions in the items shall use a
+restricted Sphinx formatting.  Emphasis via one asterix ("*"), strong emphasis
+via two asterix ("**"), code samples via blockquotes ("``"), code blocks ("..
+code-block:: c") and lists are allowed.  References to interface items are also
+allowed, for example "${appl-needs-clock-driver:/name}" and
+"${../rtems/tasks/create:/name}".  References to other parts of the
+documentation are possible, however, they are currently provided by hard-coded
+tables in :file:`rtemsspec/applconfig.py`.
+
+Modify an Existing Group
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Search for the group by its section header and edit the specification item
+file.  For example:
+
+.. code-block:: none
+
+    $ grep -rl "name: General System Configuration" spec/if/acfg
+    spec/if/acfg/group-general.yml
+    $ vi spec/if/acfg/group-general.yml
+
+Modify an Existing Option
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Search for the option by its define name and edit the specification item file.
+For example:
+
+.. code-block:: none
+
+    $ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/if/acfg
+    spec/if/acfg/appl-needs-clock-driver.yml
+    $ vi spec/if/acfg/appl-needs-clock-driver.yml
+
+Add a New Group
+^^^^^^^^^^^^^^^
+
+Let ``new`` be the UID name part of the new group.  Create the file
+:file:`spec/if/acfg/group-new.yml` and provide all attributes for an
+:ref:`SpecTypeApplicationConfigurationGroupItemType` item.  For example:
+
+.. code-block:: none
+
+    $ vi spec/if/acfg/group-new.yml
+
+Add a New Option
+^^^^^^^^^^^^^^^^
+
+Let ``my-new-option`` be the UID name of the option.  Create the file
+:file:`if/acfg/my-new-option.yml` and provide all attributes for an appropriate
+refinement of :ref:`SpecTypeApplicationConfigurationOptionItemType`.  For
+example:
+
+.. code-block:: none
+
+    $ vi spec/if/acfg/my-new-option.yml
+
+Generate Content after Changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Once you are done with the modifications of an existing item or the creation of
+a new item, the changes need to be propagated to generated source files.  This
+is done by the :file:`spec2doc.py` script.  Before you call this script, make
+sure the Git submodules are up-to-date.
+
+.. code-block:: none
+
+    $ ./spec2doc.py
+
+The script modifies or creates source files in :file:`modules/rtems` and
+:file:`modules/rtems-docs`.  Create patch sets for these changes just as these
+where work done by a human and follow the normal patch review process described
+in the *RTEMS User Manual*.  When the changes are integrated, update the Git
+submodules and check in the changed items.
+
 Glossary Specification
 ----------------------
 
-- 
2.26.2