[rtems-docs commit] eng: Add ObjectsItem details

[Sebastian Huber]

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

Author:    Kinsey Moore <kinsey.moore at oarcorp.com>
Date:      Tue Feb  7 16:02:47 2023 -0600

eng: Add ObjectsItem details

This adds a section on adding ObjectsItems.

---

 eng/build-system.rst | 29 +++++++++++++++++++++++++++++
 eng/req/items.rst    |  8 ++++++--
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/eng/build-system.rst b/eng/build-system.rst
index 6974aa8..89d27b2 100644
--- a/eng/build-system.rst
+++ b/eng/build-system.rst
@@ -489,3 +489,32 @@ Add a link to the new library item using a relative UID:
    links:
    - role: build-dependency
      uid: libnew
+
+Add an Object
+-------------
+
+Build objects logically separate relatively independent segments of
+functionality (for example a device driver, an architecture-dependent feature,
+etc.). Let *new* be the name of the new object.  You can add the new object
+with:
+
+.. code-block:: none
+
+    $ vi spec/build/cpukit/objnew.yml
+
+Define the attributes of your new object according to
+:ref:`SpecTypeBuildObjectsItemType`.
+
+Edit corresponding group item:
+
+.. code-block:: none
+
+    $ vi spec/build/cpukit/grp.yml
+
+Add a link to the new objects item using a relative UID:
+
+.. code-block:: yaml
+
+    links:
+    - role: build-dependency
+      uid: objnew
diff --git a/eng/req/items.rst b/eng/req/items.rst
index 19e8726..35cde23 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -649,8 +649,12 @@ Build Objects Item Type
 
 This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
 attribute if the value is ``objects``. This set of attributes specifies a set
-of object files used to build static libraries or test programs. All explicit
-attributes shall be specified. The explicit attributes for this type are:
+of object files used to build static libraries or test programs. Objects Items
+must not be included on multiple paths through the build dependency graph with
+identical build options. Violating this can cause race conditions in the build
+system due to duplicate installs and multiple instances of build tasks. All
+explicit attributes shall be specified. The explicit attributes for this type
+are:
 
 cflags
     The attribute value shall be a list. Each list element shall be a