Add environment element at board and component level (#234)

Commit related to issue #230. --------- Signed-off-by: Silvio Lucio Oliva <[email protected]>
Open-CMSIS-Pack · May 8, 2023 · 17ecc0a · 17ecc0a
1 parent 646ff5a
commit 17ecc0a
Show file tree

Hide file tree

Showing 6 changed files with 129 additions and 8 deletions.
diff --git a/doxygen/pack.dxy b/doxygen/pack.dxy
@@ -38,7 +38,7 @@ PROJECT_NAME           = "Open-CMSIS-Pack"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "Version 1.7.23"
+PROJECT_NUMBER         = "Version 1.7.24"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

diff --git a/doxygen/src/General.txt b/doxygen/src/General.txt
@@ -83,6 +83,12 @@ Pack\\Tutorials | Tutorials for \ref cp_Packs "Creating Packs" |
     <th>Version</th>
     <th>Description</th>
   </tr>
+  <tr>
+    <td>1.7.24</td>
+    <td>
+     - added \ref element_environment "environment" element as child element of \ref element_board "/package/boards/board" and \ref element_component_environments "/package/components/.../component/environments"
+    </td>
+  </tr>
   <tr>
     <td>1.7.23</td>
     <td>

diff --git a/doxygen/src/boards_schema.txt b/doxygen/src/boards_schema.txt
@@ -19,6 +19,8 @@ A development board is described by the following properties:
 - \ref element_board_debugProbe "debugProbe": describing the on-board debug probe.
 - \ref element_board_memory "memory": additional memory provided by the board
 - \ref element_board_algorithm "algorithm": additional flash programming algorithms for the board-specific memory
+- \ref element_board_environment "environment":  tool specific settings
+
 
 
 \b Example
@@ -222,6 +224,12 @@ This element provides information to specify the \ref createPackBoard "Board Sup
     <td>AlgorithmType</td>
     <td>0..*</td>
   </tr>
+  <tr>
+    <td>\ref element_board_environment "environment"</td>
+    <td>Specify tool specif settings.</td>
+    <td>EnvironmentType</td>
+    <td>0..*</td>
+  </tr>
 </table>
 
 <p>&nbsp;</p>
@@ -795,6 +803,8 @@ By convention, the following \<book\> entry:
 \endcode
 specifies a Markdown based documentation page for the board that can be displayed on web sites.
 
+<p>&nbsp;</p>		
+<hr>
 
 \section element_board_memory /package/boards/board/memory
 
@@ -904,6 +914,9 @@ This element specifies memory regions that boards may add. Memory types are pred
   </tr>
 </table>
 
+<p>&nbsp;</p>		
+<hr>
+
 \section element_board_algorithm /package/boards/board/algorithm
 
 Specify Flash programming algorithms with the address range and its size for board-specific memory.  An algorithm with 
@@ -987,5 +1000,12 @@ Specify Flash programming algorithms with the address range and its size for boa
 
 </table>
 
+<p>&nbsp;</p>
+<hr>
+
+\section element_board_environment /package/boards/board/environment
+
+See description at \ref element_environment "/package/devices/family/.../environment".
+
 <p>&nbsp;</p>
 */
diff --git a/doxygen/src/components_schema.txt b/doxygen/src/components_schema.txt
@@ -593,20 +593,24 @@ A component describes a collection of files (source, header, configuration, libr
     <td>xs:string </td>
     <td>0..1 </td>
   </tr>
-
   <tr>
     <td>\ref element_files "files"</td>
     <td>Grouping element for all files that are part of this component.</td>
     <td>group</td>
     <td>1</td>
   </tr>
-
   <tr>
     <td>\ref element_extensions "extensions"</td>
     <td>Grouping element for all extensions concerning this component.</td>
     <td>group</td>
     <td>1</td>
   </tr>
+  <tr>
+    <td>\ref element_component_environments "environments"</td>
+    <td>Grouping element for all environments concerning this component.</td>
+    <td>group</td>
+    <td>0..1</td>
+  </tr>
 </table>
 
 <p>&nbsp;</p>
@@ -1100,6 +1104,7 @@ The table lists the predefined values for the scope attribute.
 
 <p>&nbsp;</p>
 <hr>
+
 \section element_extensions /package/.../extensions
 
 The group <b>extensions</b> can appear in various Pack elements. This group is the frame for defining individual extensions.
@@ -1210,4 +1215,61 @@ The possible values are not imposed by this specification.
 
 <p>&nbsp;</p>
 <hr>
+
+\section element_component_environments /package/.../environments
+
+The group <b>environments</b> can appear in \ref element_component "component" element. This group is the frame for defining individual \ref element_component_environment "environment".
+
+\b Example:
+\code
+<package>
+  ...
+  <components>
+    <component Cclass="Device" Cgroup="Startup" Cversion="3.1.1" >
+      <environments>
+        ...
+      </environments>
+    </component>
+  </components>
+  ...
+</package>
+\endcode
+
+<p>&nbsp;</p>
+
+<table class="cmtable" summary="Element: Environments">
+  <tr>
+    <th>Parents</th>
+    <th colspan="3">Element Chain</th>
+  </tr>
+  <tr>
+    <td>\ref element_component "component"</td>
+    <td colspan="3">\ref element_component "/package/components/component"</td>
+  </tr>
+  <tr>
+    <td>\ref element_component "component"</td>
+    <td colspan="3">\ref element_component "/package/components/bundle/component"</td>
+  </tr>
+  <tr>
+    <th>Child&nbsp;Elements</th>
+    <th>Description</th>
+    <th>Type</th>
+    <th>Occurrence</th>
+  </tr>
+  <tr>
+    <td>\ref element_component_environment "environment"</td>
+    <td>Specify tool options.
+    <td>EnvironmentType</td>
+    <td>1..*</td>
+  </tr>
+</table>
+
+<p>&nbsp;</p>
+<hr>
+
+\section element_component_environment /package/.../environments/environment
+
+See description at \ref element_environment "/package/devices/family/.../environment".
+
+<p>&nbsp;</p>
 */
diff --git a/doxygen/src/devices_schema.txt b/doxygen/src/devices_schema.txt
@@ -1356,6 +1356,14 @@ full control of the \em element usage.
     <td>\ref element_part "part"</td>
     <td colspan="3">\ref element_part</td>
   </tr>
+  <tr>
+    <td>\ref element_board "board"</td>
+    <td colspan="3">\ref element_board</td>
+  </tr>
+  <tr>
+    <td>\ref element_component_environments "environments"</td>
+    <td colspan="3">\ref element_component_environments</td>
+  </tr>
   <tr>
     <th>Attributes</th>
     <th>Description</th>
@@ -1373,7 +1381,13 @@ full control of the \em element usage.
     <td>Identifies the processor the setting belongs to.
         Only alphabetical characters, decimal digits, '-' and '_' are allowed.
         <br><br>
-        Must not be used for \ref element_part "package/parts/part".</td>
+        Must not be used for:
+        <ul>
+          <li>\ref element_part "/package/parts/part"</li>
+          <li>\ref element_board "/package/boards/board"</li>
+          <li>\ref element_component_environments "/package/components/.../component/environments"</li>
+        </ul>
+    </td>
     <td>RestrictedString</td>
     <td>optional</td>
   </tr>

diff --git a/schema/PACK.xsd b/schema/PACK.xsd
@@ -17,13 +17,15 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 
-  $Date:        27. Apr 2023
-  $Revision:    1.7.23
+  $Date:        04. May 2023
+  $Revision:    1.7.24
   $Project: Schema File for Package Description File Format Specification
 
   Package file name convention <vendor>.<name>.<version>.pack
-  SchemaVersion=1.7.23
+  SchemaVersion=1.7.24
 
+  04. May 2023: v1.7.24
+   - added environment element as child element of /package/boards/board and /package/components/.../component/environments
   27. Apr 2023: v1.7.23
    - specified that url to a website in book element is allowed
    - aligned /package/boards/board/book element occurrence in documentation to XSD schema
@@ -194,7 +196,7 @@
 
 -->
 
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="qualified" version="1.7.23">
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="qualified" version="1.7.24">
 
   <!-- NonNegativeInteger specifies the format in which numbers are represented in hexadecimal or decimal format -->
   <xs:simpleType name="NonNegativeInteger">
@@ -1510,6 +1512,7 @@
       <xs:element name="mountedDevice"    type="BoardsDeviceType"     maxOccurs="unbounded" />
       <xs:element name="compatibleDevice" type="CompatibleDeviceType" maxOccurs="unbounded" />
       <xs:element name="mountedPart"      type="MountedPartType"      minOccurs="0" maxOccurs="unbounded" />
+      <xs:element name="environment"      type="EnvironmentType"      minOccurs="0" maxOccurs="unbounded" />
       <xs:element name="image" minOccurs="0">
         <xs:complexType>
           <!-- attribute 'large' displays the 'top' side of the board -->
@@ -2161,6 +2164,14 @@
                           <xs:element name="Pre_Include_Global_h" type="xs:string" minOccurs="0" />
                           <!-- content to be added to generated Pre_Include_Local_<ComponentID>.h file -->
                           <xs:element name="Pre_Include_Local_Component_h" type="xs:string" minOccurs="0" />
+                          <!-- list of environments (elements containing information that is specific for a development tool) -->
+                          <xs:element name="environments" minOccurs="0" >
+                            <xs:complexType>
+                              <xs:sequence>
+                                <xs:element name="environment" type="EnvironmentType" minOccurs="1" maxOccurs="unbounded" />
+                              </xs:sequence>
+                            </xs:complexType>
+                          </xs:element>
                           <!-- list of files / content -->
                           <xs:element name="files">
                             <xs:complexType>
@@ -2232,6 +2243,14 @@
                     <xs:element name="Pre_Include_Global_h" type="xs:string" minOccurs="0" />
                     <!-- content to be added to generated Pre_Include_Local_<ComponentID>.h file -->
                     <xs:element name="Pre_Include_Local_Component_h" type="xs:string" minOccurs="0" />
+                    <!-- list of environments (elements containing information that is specific for a development tool) -->
+                    <xs:element name="environments" minOccurs="0" >
+                      <xs:complexType>
+                        <xs:sequence>
+                          <xs:element name="environment" type="EnvironmentType" minOccurs="1" maxOccurs="unbounded" />
+                        </xs:sequence>
+                      </xs:complexType>
+                    </xs:element>
                     <!-- list of files / content -->
                     <xs:element name="files">
                       <xs:complexType>