The element /package/generators/generator specifies a tool or utility that is used to generate and/or configure software (source code, header files, configuration files, etc.) in the context of a project. For this purpose, a generator package description file (GPDSC) needs to be created (see <gpdsc>). The GPDSC file details the selected device, components, project files and conditions, as well as information about the generator and how it can be launched again for iterative development cycles. A GPDSC file follows the same schema as a static Pack. However, the files generated by the utility are not installed and managed centrally in the Pack folder, but locally within the project folder.

A generator can be associated with one or more components by it's name. Selecting the component will automatically include the files provided by the generator, described by the GPDSC file,in the project. If the specified GPDSC file is not present, the generator command is executed by the environment to generate the files and GPDSC. In this way project specific configurations can be made, files being generated and included and maintained as part of the project. Note: If multiple components are associated with a single generator, this generator is expected to generate the code for all components with a single invokation and via a single GPDSC file.

Example Generator Section

<generators>
  <generator id = "MyGen">
    <gpdsc name ="$P/RTE/MyGen/myGen.gpdsc"/>
    <exe>
      <command host = "win">MyGen.bat</command>
      <command host = "linux">MyGen.script</command>
      <argument>$P/RTE/MyGen/myGen.gpdsc</argument>
      <argument host="linux" switch="--device=">$D</argument>
      <argument host="win"   switch="/device=">$D</argument>
    </exe>
 
    <eclipse plugin="com.mygen.plugin" class="com.mygen.plugin.generator.launcher" method="launch" >
      <argument>$D</argument>
      <argument>$P/RTE/MyGen/myGen.gpdsc</argument>
    </eclipse>
 
    <web url="http://mygen.com/mygen">
      <argument switch="device">$D</argument>
      <argument switch="gpdsc">$P/RTE/MyGen/myGen.gpdsc</argument>
    </web>
  </generator>
</generators>

Example Generator Package Description File (gpdsc)

<?xml version="1.0" encoding="UTF-8"?>
 
<package xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" schemaVersion="1.0" xs:noNamespaceSchemaLocation="PACK.xsd">
  <vendor>Keil</vendor>
  <name>FrameworkCubeMX</name>
  <description>STM32CubeMX generated pack description</description>
  <url>project-path</url>
  <releases>
    <release version="1.0.0">
     - Generated: 08/11/2016 09:20:21
    </release>
  </releases>
  <generators>
    <generator id="STM32CubeMX" Gvendor="STMicroelectronics" Gtool="STM32CubeMX" Gversion="4.10.0">
      <description>STM32CubeMX Environment</description>
      <select Dname="STM32F746NGHx" Dvendor="STMicroelectronics:13"/>
      <exe>
        <command host = "win">MDK/CubeMX/STM32CubeMXLauncher.exe</command>
        <command host = "linux">MDK/CubeMX/STM32CubeMXLauncher</command>
        <argument>$P/RTE/MyGen/myGen.gpdsc</argument>
        <argument>$D.ioc</argument>
      </exe>
      <workingDir>$P/RTE/Device/STM32F746NGHx</workingDir>
      <project_files>
        <file category="source" name="STCubeGenerated/Src/main.c" />
        <file category="header" name="STCubeGenerated/Inc/stm32f7xx_it.h"/>
        <file category="source" name="STCubeGenerated/Src/stm32f7xx_it.c"/>
      </project_files>
    </generator>
  </generators>
  <taxonomy>
    <description Cclass="Device" Cgroup="STM32Cube Framework" generator="STM32CubeMX">STM32Cube Framework</description>
  </taxonomy>
  <conditions>
    <condition id="STCubeMX">
      <description>Condition to include CMSIS-Core (Cortex-M) and Device Startup components</description>
      <require Dvendor="STMicroelectronics:13" Dname="STM32F7*"/>
      <require Cclass="CMSIS"  Cgroup="Core"          Csub=""/>
      <require Cclass="Device" Cgroup="Startup"/>
      <require Cclass="Device" Cgroup="STM32Cube HAL" Csub="Common"/>
      <require Cclass="Device" Cgroup="STM32Cube HAL" Csub="GPIO"/>
    </condition>
  </conditions>
  <components>
    <component generator="STM32CubeMX" Cvendor="Keil" Cclass="Device" Cgroup="STM32Cube Framework" Csub="STM32CubeMX" Cversion="1.0.0" condition="STCubeMX">
      <description>Configuration via STM32CubeMX</description>
      <RTE_Components_h>
        #define RTE_DEVICE_FRAMEWORK_CUBE_MX
      </RTE_Components_h>
      <files>
        <file category="header" name="MX_Device.h"/>
        <file category="header" name="STCubeGenerated/Inc/stm32f7xx_hal_conf.h"/>
        <file category="source" name="STCubeGenerated/Src/stm32f7xx_hal_msp.c"/>
      </files>
    </component>
  </components>
</package>

/package/generators

Grouping element for generators. Only one such group can exist in a Pack.

Parent	Chain
package	/package
Child Elements	Description	Type	Occurrence
generator	Description of the generator and the related files	GeneratorType	1..*

The following variables can be used in the elements <command>, <workingDir>, <argument>, <gpdsc>:

Variable	Description
$P	PATH to current project
#P	PATH and name of the current project
$S	PATH to Pack folder containing the Device description used by the current project
$D	Name of the device configured in the current project
$B	Name of the board configured in the current project
$G	Absolute PATH to the generator input file describing the project and component context. Note $G is only available in the `<command>` and `<argument>` elements

/package/generators/generator

The generator section is used to provide the details about the tool that has been used to create the GPDSC file. At least one generator element must exist.

Parent	Chain
generators	/package/generators
Attributes	Description	Type	Use
id	Identifier of the generator tool. Can be used by other elements to determine the generator.	xs:string	required
Gvendor	Vendor name of the generator tool.	xs:string	optional
Gtool	Plain text name of the generator.	xs:string	optional
Gversion	Version of the generator tool.	xs:string	optional
Child Elements	Description	Type	Occurrence
description	Briefly describes the generator tool (maximum 256 characters, recommended 128 characters).	BriefDescType	0..1
select	Complex type specifying the configured device. A device is uniquely identified by vendor, name or variant and processor name in case of devices with multiple processors.	GeneratorSelectType	0..1
workingDir	Optional directory that is used to store the generator output. When ommitted, the `csolution` project manager uses ./generated/<id> which is the recommended default for other implementations.	xs:string	0..1
command	Deprecated; use exe, web and/or eclipse. Invocation command for the generator tool.	xs:string	0..1
arguments	Deprecated; use argument tags under exe, web and/or eclipse.	GeneratorCommandArgumentsType	0..1
gpdsc	Path and name of the GPDSC that the generator creates and updates. The path is either absolute or relative to the working directory. If no explicit gpdsc file is provided, then a gpdsc file named after the project with extension gpdsc in the working directory is assumed (`<project>`.gpdsc).	GpdscFileType	0..1
exe	Section to specify a binary/executable to generate the GPDSC file.	xs:string	0..1
eclipse	Section to specify an Eclipse plug-in to generate the GPDSC file.	xs:string	0..1
web	Section to specify a web page to generate the GPDSC file.	xs:string	0..1
project_files	Grouping element for all project files generated by the tool.	group	0..1
files	Grouping element for generator tool files.	group	0..1
extensions	Generator vendor specific section ignored by other tools	N/A	0..1

/package/generators/generator/select

This element contains information about the vendor and device the GPDSC file has been generated for. Only one such element can exist in <generator>.

Example:

<generators>
  <generator id="STM32CubeMX" Gvendor="STMicroelectronics" Gtool="STM32CubeMX" Gversion="4.10.0">
    <select Dname="STM32F746NGHx" Dvendor="STMicroelectronics:13"/>
  </generator>
</generators>

Parent	Chain
generator	/package/generators/generator
Attributes	Description	Type	Use
Dvendor	Vendor name of the targeted device. Use predefined values as listed in the table Device Vendor.	DeviceVendorEnum	required
Dname	Name of the targeted device. If no Dvariant is specified this tag is required	xs:string	optional
Dvariant	Name of the targeted device variant. If a variant is specified, the device name will be ignored and the variant rules. If no Dname is specified, this tag is required.	xs:string	optional
Pname	Name of the targeted processor of a device with multiple processors. For devices with multiple processors this tag is required.	xs:string	optional

/package/generators/generator/gpdsc

Path and name of the GPDSC that the generator creates and updates. The path is either absolute or relative to the working directory. If no explicit gpdsc file is provided, then a gpdsc file named after the project with extension gpdsc in the working directory is assumed (<project>.gpdsc). Only one such element can exist in <generator>.

Example:

<generators>
  <generator id="MyGen">
    <gpdsc name="$P/RTE/MyGen/myGen.gpdsc"/>
  </generator>
</generators>

Parent	Chain
generator	/package/generators/generator
Attributes	Description	Type	Use
name	Path and name of the GPDSC that the generator creates and updates.	xs:string	required

/package/generators/generator/exe

This element contains information about the generation binary/executable.

Example:

<exe>
  <command host = "win">MyGen.bat</command>
  <command host = "linux">MyGen.script</command>
  <argument>$P/RTE/MyGen/myGen.gpdsc</argument>
  <argument host="linux" switch="--device=">$D</argument>
  <argument host="win"   switch="/device=">$D</argument>
</exe>

Parent	Chain
generator	/package/generators/generator
Child Elements	Description	Type	Occurrence
command	Invocation command for the generator tool. Command line options should be passed via `<arguments>`.	GeneratorCommandType	1..4
argument	Arguments passed along with the `<command>` of the format `<argument` `switch="-data">myFileName</argument>`. Path information for files can be specified absolute or relative to the location (path) of the GPDSC file.	GeneratorCommandArgumentType	1..*

/package/generators/generator/eclipse

This element contains information about the Eclipse based generation tool.

Example:

<eclipse plugin="com.mygen.plugin" class="com.mygen.plugin.generator.launcher" method="launch" >
  <argument>$D</argument>
  <argument>$P/RTE/MyGen/myGen.gpdsc</argument>
</eclipse>

Parent	Chain
generator	/package/generators/generator
Attributes	Description	Type	Use
plugin	Name of the plugin.	xs:string	required
class	Plugin's class name.	xs:string	required
method	Method used to launch the plugin.	xs:string	required
Child Elements	Description	Type	Occurrence
argument	Arguments passed to the plugin.	GeneratorCommandArgumentType	1..*

/package/generators/generator/web

This element contains information about the web generation application.

Example:

<web url="http://mygen.com/mygen">
  <argument switch="device">$D</argument>
  <argument switch="gpdsc">$P/RTE/MyGen/myGen.gpdsc</argument>
</web>

Parent	Chain
generator	/package/generators/generator
Attributes	Description	Type	Use
url	Specifies the URL of the web service.	URL	required
Child Elements	Description	Type	Occurrence
argument	Arguments passed along to the web service.	GeneratorCommandArgumentType	0..*

/package/generators/generator/.../command

This element describes a single command line for launching the generator. Arguments should be passed along with an argument.

Example

<exe>
  <command host = "win">MyGen.bat</command>
  <command host = "linux">MyGen.script</command>
  <argument>$P/RTE/MyGen/myGen.gpdsc</argument>
  <argument host="linux" switch="--device=">$D</argument>
  <argument host="win"   switch="/device=">$D</argument>
</exe>

Parent	Element Chain
exe	/package/generators/generator/exe
Current	Description	Type
command	generator command line	xs:string
Attributes	Description	Type	Use
host	Specifies the host operating system. Possible values are `all`, `win`, `linux`, `mac`, `other`. Only available with element exe.	xs:string	optional

/package/generators/generator/.../argument

This element describes one or multiple arguments passed along with the parent element.

Example

<generators>
    <generator id = "MyGen">
      <gpdsc name ="$P/RTE/MyGen/myGen.gpdsc"/>
      <exe>
        <command host = "win">MyGen.bat</command>
        <command host = "linux">MyGen.script</command>
        <argument>$P/RTE/MyGen/myGen.gpdsc</argument>
        <argument host="linux" switch="--device=">$D</argument>
        <argument host="win"   switch="/device=">$D</argument>
        <argument mode="dry-run">--dry-run</argument>
      </exe>
 
      <eclipse plugin="com.mygen.plugin" class="com.mygen.plugin.generator.launcher" method="launch" >
        <argument>$D</argument>
        <argument>$P/RTE/MyGen/myGen.gpdsc</argument>
      </eclipse >
 
      <web url="http://mygen.com/mygen">
        <argument switch="device">$D</argument>
        <argument switch="gpdsc">$P/RTE/MyGen/myGen.gpdsc</argument>
      </web>
    </generator>
</generators>

Parent	Element Chain
exe, eclipse, web	/package/generators/generator/exe, /package/generators/generator/eclipse, /package/generators/generator/web
Current	Description	Type
argument	value of argument without command line switch	xs:string
Attributes	Description	Type	Use
mode	Specifies the execution mode. Possible values are `normal` and `dry-run`. If set, the argument is only passed to the generator if the value matches the mode the generator is started in. For example, an argument with mode set to `dry-run` is only passed to the generator if it is started in dry-run mode. Arguments not specifying mode are always passed to the generator. In `dry-run` mode, the generator must not generate any files. Instead of writing the GPDSC file to disk, its contents is written to standard output (stdout), enclosed within the marks `-----BEGIN GPDSC-----` and `-----END GPDSC-----`. Only available with element exe.	xs:string	optional
host	Specifies the host operating system. Possible values are `all`, `win`, `linux`, `mac`, `other`. Only available with element exe.	xs:string	optional
switch	Specifies the command line switch separated from the argument value. Not available with element eclipse.	xs:string	optional

/package/generators/generator/project_files

The group project_files specifies all files that are required for the project setup. Only one such group can exist.

Example

<generators>
  <generator id="STM32CubeMX" Gvendor="STMicroelectronics" Gtool="STM32CubeMX" Gversion="4.10.0">
    <description>STM32CubeMX Environment</description>
    <select Dname="STM32F746NGHx" Dvendor="STMicroelectronics:13"/>
    <exe>
      <command host = "win">MDK/CubeMX/STM32CubeMXLauncher.exe</command>
      <command host = "linux">MDK/CubeMX/STM32CubeMXLauncher</command>
      <argument>$P/RTE/MyGen/myGen.gpdsc</argument>
      <argument>$D.ioc</argument>
    </exe>
    <workingDir>$P/RTE/Device/STM32F746NGHx</workingDir>
    <project_files>
      <file category="source" name="STCubeGenerated/Src/main.c" />
      <file category="header" name="STCubeGenerated/Inc/stm32f7xx_it.h"/>
      <file category="source" name="STCubeGenerated/Src/stm32f7xx_it.c"/>
    </project_files>
  </generator>
</generators>

Parent	Element Chain
generator	/package/generators/generator
Child Elements	Description	Type	Occurrence
file	Frame for files created by the generator and used in a project.	group	0..1

/package/generators/generator/files

The group files specifies files that are required by the generator tool. Only one such group can exist.

Example

<generators>
  <generator id="MyGenerator">
    <files>
      ...
    <files>
  </generator>
</generators>

Parent	Element Chain
generator	/package/generators/generator
Child Elements	Description	Type	Occurrence
file	Frame for files used by the generator.	group	0..1

/package/generators/generator/files/file

This element contains information about files used by a generator.

Example

<generators>
  <generator id="MyGenerator">
    <files>
      <file category="generator" name="Main.c"/>
      <file category="you_name_it" name="database/connection.odbc" version="1.2.3"/>
      ...
    <files>
  </generator>
</generators>

Parent	Element Chain
files	/package/generators/generator/files
Attributes	Description	Type	Use
condition	Reference using the name of the respective condition specified in the conditions section of this package (/package/conditions). If the condition resolves to false, then the element will be ignored and treated as if not present.	xs:string	optional
category	Describes the file type (for example: doc, header, library). You can use predefined values as listed in the table File Categories, however, this is not mandatory.	xs:string	required
name	Can consist of the path (relative to the Pack base directory) and the file name with extension.	xs:string	required
version	File-specific version information. The version format is described in Version Type.	VersionType	optional