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

Thu Aug 6 16:57:38 UTC 2020

Thanks for this. I saw just a few typos and grammatical fixes/suggestions.

On Wed, Aug 5, 2020 at 11:47 PM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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
s/options/option

> +: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 *feature enable options* let the application enable a feature option."

I like the wording in the third/fourth bullets, mirror it here and
below for consistency.

> +  the application configuration, then the feature is simply not available or
delete "by the application configuration" it is implied?

> +  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
"The *feature options* let the application enable a specific feature
option. If the option is not defined, then a default feature option is
used. Feature-specific code may be linked"

Note "may be"

> +  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
English grammar reads better when the subject comes first, and putting
the prepositional phrase ("from") closer to its action verb:
"Sphinx documentation sources and header files with Doxygen markup are
generated from the specification items."

> +restricted Sphinx formatting.  Emphasis via one asterix ("*"), strong emphasis
s/asterix/asterisk

> +via two asterix ("**"), code samples via blockquotes ("``"), code blocks ("..
s/asterix/asterisks

> +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.
May be clearer to say "CPP define" or "#define"?

> +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
The rest of this document is in the third person or second-person
understood (meaning, we never say "you" but it is understood that
"you" do the things). It may be more consistent to remove these "you":

"After modification of an existing item ..."

> +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
"Before calling this script, ..."

> +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
s/as/as if

> +where work done by a human and follow the normal patch review process described
s/where/were

> +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
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel