rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-15 03:26:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

eng: Update application configuration how-to

Browse Source 
Change paths to be in line with the actual specification.  Fix group
membership link role.

Update #3715.
This commit is contained in:
Sebastian Huber 2023-05-04 13:32:06 +02:00
parent 77e8b566b7
commit 7158449cc5
2 changed files with 28 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
eng/req/howto.rst
View File

@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0 .. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2020, 2022 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 2020, 2023 embedded brains GmbH & Co. KG
How-To How-To
====== ======
@ -131,12 +131,12 @@ Application Configuration Options
--------------------------------- ---------------------------------
The application configuration options and groups are maintained by The application configuration options and groups are maintained by
specification items in the directory :file:`spec/if/acfg`. Application specification items in the directory :file:`spec/acfg/if`. Application
configuration options are grouped by configuration options are grouped by
:ref:`SpecTypeApplicationConfigurationGroupItemType` items which should be :ref:`SpecTypeApplicationConfigurationGroupItemType` items which should be
stored in files using the :file:`spec/if/acfg/group-*.yml` pattern. Each stored in files using the :file:`spec/acfg/if/group-*.yml` pattern. Each
application configuration option shall link to exactly one group item with the application configuration option shall link to exactly one group item with the
:ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole`. There are four :ref:`SpecTypeInterfaceGroupMembershipLinkRole`. There are four
application option item types available which cover all existing options: application option item types available which cover all existing options:
* The *feature enable options* let the application enable a feature option. If * The *feature enable options* let the application enable a feature option. If
@ -177,9 +177,9 @@ restricted Sphinx formatting. Emphasis via one asterisk ("*"), strong emphasis
via two asterisk ("**"), code samples via blockquotes ("``"), code blocks (".. via two asterisk ("**"), code samples via blockquotes ("``"), code blocks ("..
code-block:: c") and lists are allowed. References to interface items are also code-block:: c") and lists are allowed. References to interface items are also
allowed, for example "${appl-needs-clock-driver:/name}" and allowed, for example "${appl-needs-clock-driver:/name}" and
"${../rtems/tasks/create:/name}". References to other parts of the "${/rtems/task/if/create:/name}". References to other parts of the
documentation are possible, however, they are currently provided by hard-coded documentation are possible, however, they have to be provided by
tables in :file:`rtemsspec/applconfig.py`. :file:`spec:/doc/if/*` items.
Modify an Existing Group Modify an Existing Group
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
@ -189,9 +189,9 @@ file. For example:
.. code-block:: none .. code-block:: none
$ grep -rl "name: General System Configuration" spec/if/acfg $ grep -rl "name: General System Configuration" spec/acfg/if
spec/if/acfg/group-general.yml spec/acfg/if/group-general.yml
$ vi spec/if/acfg/group-general.yml $ vi spec/acfg/if/group-general.yml
Modify an Existing Option Modify an Existing Option
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
@ -201,20 +201,20 @@ specification item file. For example:
.. code-block:: none .. code-block:: none
$ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/if/acfg $ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/acfg/if
spec/if/acfg/appl-needs-clock-driver.yml spec/acfg/if/appl-needs-clock-driver.yml
$ vi spec/if/acfg/appl-needs-clock-driver.yml $ vi spec/acfg/if/appl-needs-clock-driver.yml
Add a New Group Add a New Group
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
Let ``new`` be the UID name part of the new group. Create the file 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 :file:`spec/acfg/if/group-new.yml` and provide all attributes for an
:ref:`SpecTypeApplicationConfigurationGroupItemType` item. For example: :ref:`SpecTypeApplicationConfigurationGroupItemType` item. For example:
.. code-block:: none .. code-block:: none
$ vi spec/if/acfg/group-new.yml $ vi spec/acfg/if/group-new.yml
Add a New Option Add a New Option
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
@ -226,7 +226,7 @@ example:
.. code-block:: none .. code-block:: none
$ vi spec/if/acfg/my-new-option.yml $ vi spec/acfg/if/my-new-option.yml
Generate Content after Changes Generate Content after Changes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -263,7 +263,7 @@ specification.
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights: copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 2020 embedded brains GmbH & Co. KG
enabled-by: true enabled-by: true
glossary-type: term glossary-type: term
links: links:
@ -300,23 +300,25 @@ Interface Specification
Specify an API Header File Specify an API Header File
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
The RTEMS :term:`API` header files are specified under ``spec:/if/rtems/*``. The RTEMS :term:`API` header files are specified under ``spec:/rtems/*/if``.
Create a subdirectory with a corresponding name for the API, for example in Create a subdirectory with a corresponding name for the API, for example in
:file:`spec/if/rtems/foo` for the `foo` API. In this new subdirectory place an :file:`spec/rtems/foo/if` for the `foo` API. In this new subdirectory place an
:ref:`SpecTypeInterfaceHeaderFileItemType` item named :file:`header.yml` :ref:`SpecTypeInterfaceHeaderFileItemType` item named :file:`header.yml`
(:file:`spec/if/rtems/foo/header.yml`) and populate it with the required (:file:`spec/rtems/foo/if/header.yml`) and populate it with the required
attributes. attributes.
.. code-block:: yaml .. code-block:: yaml
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights: copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 2020 embedded brains GmbH & Co. KG
enabled-by: true enabled-by: true
interface-type: header-file interface-type: header-file
links: links:
- role: interface-placement - role: interface-placement
uid: /if/domains/api uid: /if/domain
- role: interface-ingroup
uid: ../req/group
path: rtems/rtems/foo.h path: rtems/rtems/foo.h
prefix: cpukit/include prefix: cpukit/include
type: interface type: interface
@ -327,7 +329,7 @@ Specify an API Element
Figure out the corresponding header file item. If it does not exist, see Figure out the corresponding header file item. If it does not exist, see
:ref:`ReqEngAddAPIHeaderFile`. Place a specialization of an :ref:`ReqEngAddAPIHeaderFile`. Place a specialization of an
:ref:`SpecTypeInterfaceItemType` item into the directory of the header file :ref:`SpecTypeInterfaceItemType` item into the directory of the header file
item, for example :file:`spec/if/rtems/foo/bar.yml` for the :c:func:`bar` item, for example :file:`spec/rtems/foo/if/bar.yml` for the :c:func:`bar`
function. Add the required attributes for the new interface item. Do not hard function. Add the required attributes for the new interface item. Do not hard
code interface names which are used to define the new interface. Use code interface names which are used to define the new interface. Use
``${uid-of-interface-item:/name}`` instead. If the referenced interface is ``${uid-of-interface-item:/name}`` instead. If the referenced interface is
@ -344,7 +346,7 @@ an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item.
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: Tries to create a magic object and returns it. brief: Tries to create a magic object and returns it.
copyrights: copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 2020 embedded brains GmbH & Co. KG
definition: definition:
default: default:
body: null body: null
@ -371,7 +373,7 @@ an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item.
return: Otherwise, the magic object is returned. return: Otherwise, the magic object is returned.
return-values: return-values:
- description: The caller did not have enough magic power. - description: The caller did not have enough magic power.
value: ${/if/c/null} value: ${/c/if/null}
type: interface type: interface
Requirements Depending on Build Configuration Options Requirements Depending on Build Configuration Options
@ -608,7 +610,7 @@ presentation we use a structured order.
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights: copyrights:
- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 2021 embedded brains GmbH & Co. KG
enabled-by: true enabled-by: true
functional-type: action functional-type: action
rationale: null rationale: null

2
eng/req/items.rst
View File

@ -4522,8 +4522,6 @@ uid
This type is refined by the following types: This type is refined by the following types:
* :ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole`
* :ref:`SpecTypeBuildDependencyConditionalLinkRole` * :ref:`SpecTypeBuildDependencyConditionalLinkRole`
* :ref:`SpecTypeBuildDependencyLinkRole` * :ref:`SpecTypeBuildDependencyLinkRole`