![]() |
CMSIS-Pack
Version 1.3
Delivery Mechanism for Software Packs
|
The element /package/components describes software components contained in the PACK. A component lists the files that belong to a component and that are relevant for a project. The component itself or each individual file may refer to a condition that must resolve to true; if it is false the component or file is not applicable in the given context.
Each component must have a Class (Cclass=), a Group (Cgroup=), and a Version (Cversion=) which is used to identify the component. Optionally a component may have a Sub-Group (Csub=) and Variant (Cvariant=) to add further categories. The Class, Group, Sub-Group, Variant and Version is used together with the vendor specified by the PACK, to identify a component. A component vendor must ensure that the combination Class, Group, Sub-Group and Version is unique and not used by multiple components.
In case multiple interdependant components that belong to the same Cclass form part of a solution, these can be grouped in a so called bundle. A bundle specifies the attributes Cclass, Cversion and optionally Cgroup and Cvendor. Components within a bundle inherit the attributes set by the bundle and must not set these attributes. Bundles ensure consistency of attributes across multiple interworking components and restrict the mix and match of components within a Cclass from different solutions.
Example
Grouping element containing a choice of at least one bundle or component. No more than one element components can exist in a PACK.
Parent | Element Chain | ||
---|---|---|---|
package | /package | ||
Attributes | Description | Type | Use |
generator | Specifies the generator tool that has been used to create the component. | xs:string | optional |
Child Elements | Description | Type | Occurrence |
bundle | Grouping element for a collection of interoperable components belonging to the same Cclass | ComponentType | 1..* |
component | Grouping element for components | ComponentType | 1..* |
A bundle describes a named collection of interoperable components of the identical Cvendor, Cclass and Cversion. Components enclosed in a bundle must not specify any of the following attributes Cvendor, Cclass and Cversion.
Parent | Element Chain | ||
---|---|---|---|
components | /package/components | ||
Attributes | Description | Type | Use |
Cbundle | Defines the name of the bundle. It becomes a mandatory part of the component ID. | xs:string | required |
Cvendor | Defines the component vendor all components of this bundle belong to. If not explicitly set the component vendor is derived from the package vendor. The component vendor is a mandatory part of the component ID. | xs:string | optional |
Cclass | Defines the component class to which all components in the bundle belong. Is a mandatory part of the component ID. Predefined values can be used as listed in the table Component Classes. | CclassType | required |
Cversion | Defines the version of all components contained in the bundle. The component version is a mandatory part of the component ID. The version format is described in Version Type. | VersionType | required |
Child Elements | Description | Type | Occurrence |
description | Brief description of the bundle | xs:string | 1..1 |
doc | Documentation for the bundle: File path, file name, and file extension in the format path/name.extension. The file path is relative to the root directory of the PACK. | xs:string | 1..1 |
component | Grouping element for components. | ComponentType | 1..* |
A component describes a collection of files (source, header, configuration, library) that can be versioned and categorized.
Parent | Element Chain | ||
---|---|---|---|
components | /package/components | ||
components | /package/components/bundle | ||
Attributes | Description | Type | Use |
Cvendor | Defines the component vendor this component is shipped by. It is a mandatory part of the component ID and will be inherited from the package vendor if not specified. Must not be specified for a component within a bundle. | xs:string | optional |
Cclass | Defines the component class to which the component belongs. This is a mandatory part of the component ID. Predefined values can be used as listed in the table Component Classes. Must not be specified for a component within a bundle. | CclassType | required |
Cgroup | Defines the component group to whoch the component belongs. Is a mandatory part of the component ID. Predefined values can be used as listed in the table Component Groups. | CgroupType | required |
Csub | Defines the component subgroup. Is an optional part of the component ID. The type is described in Component Subgroups. | CsubType | optional |
Cvariant | Defines a variant of a component. Is an optional part of the component ID. The variant specifier is a brief string (for example: release, debug). | VariantType | optional |
Cversion | Defines the version of this component. Is a mandatory part of the component ID. The version format is described in Version Type. Must not be specified for a component within a bundle. | VersionType | required |
Capiversion | For components that are based on an API, it defines the version of the API used by this component. It ensures that the API header file with this or any higher version is acceptable for using that component. The version format is described in Version Type. | VersionType | optional |
condition | Enter the id of a condition. The component is used when the condition is true. | xs:string | optional |
maxInstances | Maximum allowed instances of a component in a project. Default is 1 for one instance. The range is [1..10]. | xs:integer | optional |
Child Elements | Description | Type | Occurrence |
deprecated | When set to true, then the component is deprecated and no longer maintained. Default is false to indicate an actively maintained component. | xs:boolean | 0..1 |
description | Brief description of the component. | xs:string | 1..1 |
RTE_Components_h | Source code that is copied into the file RTE_Components.h when the component is included into a software project. | xs:string | 0..1 |
files | Grouping element for all files that are part of this component. | group | 0..1 |
Component Subgroups are specified by the element Csub, and create subcategories within Component Classes (Cclass) and Component Groups (Cgroup). A Csub name is of type xs:string whith a length between 3 and 32 characters. No Csub names have been predefined.
Subgroups exists in the elements:
Example:
The group files can appear in various PACK elements. This group is the frame for defining individual file properties.
Example:
Parents | Element Chain | ||
---|---|---|---|
api | /package/apis/api | ||
component | /package/components/component | ||
component | /package/components/bundle/component | ||
Child Elements | Description | Type | Occurrence |
file | Frame for the individual file of a component. | group | 0..1 |
The element file is the mechanism to attach files to the software. The file purpose is defined through the category attribute. The name attribute identifies the file.
Example:
Parents | Element Chain | ||
---|---|---|---|
files | /package/apis/api/files | ||
files | /package/components/component/files | ||
files | /package/components/bundle/component/files | ||
files | /package/generators/generator/project_files | ||
Attributes | Description | Type | Use |
name | File path, file name, and file extension in the format path/name.extension. The file path is relative to the root directory of the PACK. | xs:string | required |
category | Defines the purpose of the file. Select the predefined value as listed in the table File Categories. | FileCategoryEnum | required |
attr | Defines the special use and handling of a file. Select a predefined value as defeind in the table File Attributes. | FileAttributeEnum | optional |
condition | Ener the identifier (attribute id) of a condition. The element is used if the condition resolves to true. If the condition resolves to false, then the element will be ignored. For example, a library might be specific for a certain toolchain or processor instruction set. | xs:string | optional |
select | Brief description and purpose of the file. The select attribute is required when attr is set to template or interface. When multiple template files of a component have the same select string, they are treated as a single selectable template. This way, multiple template or interface files can be bundled. | xs:string | optional |
src | Path information. The path is specified relative to the PACK Description File. If category is set to library, then the src string can contain a list of directory paths separated by semicolons. A debugger will search those paths for locating the source files of the modules archived in the library supporting the debugging of library code. | xs:string | optional |
version | File-specific version information. This is used particularly for files copied into the project workspace. Before a file gets copied, a version check avoids unnecessary copy actions. If a file does not have a version, then the component version is used. The version format is described in Version Type. | VersionType | optional |
The file attribute defines the special handling in the project when being used as configuration, template, or interface file. The table lists the values available as a file attribute.
attr= | Description |
---|---|
config | The file is a configuration file of the component. It is expected that only configuration options are modified. The file is managed as part of the component, as a project-specific file typically copied into the component section of the project. |
template | The file is used as a source code template file. It is expected to be edited and extended by the software developer. The file can be copied into a user section of the project. |
interface | The file contains the source code of an interface that connects two software components. It is a working reference implementation that may need customization. The file can be copied to a user section of the project. |
File category types define the use of component files within the application. Typically these files are added to the project and processed by the build tools.
The table lists the predefined values for a file category. These values can be use also in the element /package/generators/generator/files/file.
category= | Description |
---|---|
doc | Documentation |
header | Header file used in the component. Sets an include file path. |
include | Sets an include file path. |
library | Library file |
object | Object file that can be added to the application |
source | Startup-, system-, and other C/C++, assembler, etc. source files |
sourceC | C source file |
sourceCpp | C++ source file |
sourceAsm | Assembly source file |
linkerScript | linker script file that can be selected by tool-chains |
utility | a command line tool that can be configured for pre- or post-processing during the build process |
image | Files of image type are marked for special processing into a Filesystem Image embedded into the application. This category requires the attr being set to template or interface. |
other | Other file types not covered in the list above |