[rtems-docs commit] eng: Clarify stlib build attribute

[Sebastian Huber]

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

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Thu Oct  1 07:37:04 2020 +0200

eng: Clarify stlib build attribute

Update #4107.

---

 eng/req/items.rst | 45 ++++++++++++++++++++++++++++++++-------------
 1 file changed, 32 insertions(+), 13 deletions(-)

diff --git a/eng/req/items.rst b/eng/req/items.rst
index d660d2f..3d1ef2a 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -279,9 +279,8 @@ source
     :ref:`SpecTypeBuildSource`.
 
 stlib
-    The attribute value shall be a list of strings. It shall be a list of
-    external static library identifiers used to link this test program, e.g.
-    ``m`` for ``libm.a``.
+    The attribute value shall be a list. Each list element shall be a
+    :ref:`SpecTypeBuildLinkStaticLibraryDirective`.
 
 target
     The attribute value shall be a :ref:`SpecTypeBuildTarget`.
@@ -821,9 +820,8 @@ prepare-configure
     context.
 
 stlib
-    The attribute value shall be a list of strings. It shall be a list of
-    external static library identifiers used to link this test program, e.g.
-    ``m`` for ``libm.a``.
+    The attribute value shall be a list. Each list element shall be a
+    :ref:`SpecTypeBuildLinkStaticLibraryDirective`.
 
 use-after
     The attribute value shall be a list. Each list element shall be a
@@ -954,9 +952,8 @@ source
     :ref:`SpecTypeBuildSource`.
 
 stlib
-    The attribute value shall be a list of strings. It shall be a list of
-    external static library identifiers used to link this test program, e.g.
-    ``m`` for ``libm.a``.
+    The attribute value shall be a list. Each list element shall be a
+    :ref:`SpecTypeBuildLinkStaticLibraryDirective`.
 
 target
     The attribute value shall be a :ref:`SpecTypeBuildTarget`.
@@ -2712,6 +2709,26 @@ This type is used by the following types:
 
 * :ref:`SpecTypeBuildStartFileItemType`
 
+.. _SpecTypeBuildLinkStaticLibraryDirective:
+
+Build Link Static Library Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The value shall be a string. It shall be an external static library identifier.
+The library is used to link programs referenced by this item, e.g. ``m`` for
+``libm.a``.  The library is added to the build command through the ``stlib``
+attribute. It shall not be used for internal static libraries.  Internal static
+libraries shall be specified through the ``use-after`` and ``use-before``
+attributes to enable a proper build dependency tracking.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeBuildAdaTestProgramItemType`
+
+* :ref:`SpecTypeBuildScriptItemType`
+
+* :ref:`SpecTypeBuildTestProgramItemType`
+
 .. _SpecTypeBuildLinkerOption:
 
 Build Linker Option
@@ -3123,8 +3140,9 @@ Build Use After Directive
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The value shall be a string. It shall be an internal static library identifier.
-They are used to link programs referenced by this item, e.g. ``z`` for
-``libz.a``.  They are placed after the use items of the build item context.
+The library is used to link programs referenced by this item, e.g. ``z`` for
+``libz.a``.  The library is placed after the use items of the build item
+context.
 
 This type is used by the following types:
 
@@ -3142,8 +3160,9 @@ Build Use Before Directive
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The value shall be a string. It shall be an internal static library identifier.
-They are used to link programs referenced by this item, e.g. ``z`` for
-``libz.a``.  They are placed before the use items of the build item context.
+The library is used to link programs referenced by this item, e.g. ``z`` for
+``libz.a``.  The library is placed before the use items of the build item
+context.
 
 This type is used by the following types: