1 2 3 4 5 6 7 8 9 10 11
12 package xdc.tools.product;
13
14 /*!
15 * ======== IProductTemplate ========
16 * Interface to provide examples for a product
17 *
18 * This interface allows products to contribute examples to
19 * development environments like IDE's. This is an experimental
20 * interface and is subject to change.
21 */
22 metaonly interface IProductTemplate
23 {
24 /*!
25 * ======== FileDesc ========
26 * Structure defining properties of a file included in an example
27 *
28 * @field(path) Path to file relative to the package
29 * containing the implementation of
30 * `IProductTemplate`
31 * @field(excludeFromBuild) Flag indicating whether file
32 * should be excluded from build inside
33 * an IDE project
34 * @field(openOnCreation) Flag indicating whether the file
35 * should be opened when a project
36 * containing the example file is created
37 * by the IDE.
38 * @field(copyIntoConfiguration) Flag indicating whether the file
39 * should be copied into RTSC
40 * configuration. This flag
41 * applies only when the `isHybrid`
42 * flag of the
43 * {@link #TemplateInfo template} is set
44 * to `false`.
45 *
46 * @field(action) Flag indicating whether the file
47 * should be copied into the project or linked in.
48 * For example, the
49 * `{@link xdc.tools.product.trexgen trexgen}`
50 * tool recognizes the following flags:
51 * "COPY" - copy the file into the project
52 * "LINK" - link the file into the project
53 */
54 struct FileDesc {
55 String path; /*! path to file */
56 Bool excludeFromBuild; /*! exclude from build */
57 Bool openOnCreation; /*! open on project creation */
58 Bool copyIntoConfiguration; /*! copy into RTSC configuration */
59 String action; /*! Flag indicating whether the file should be copied into the project or linked in */
60 };
61
62 /*!
63 * ======== Filter ========
64 * Structure defining filter properties for an example
65 *
66 * This structure allows products to define constraints for their
67 * examples. IDEs use the `Filter` properties of an example
68 * to decide whether the example should be presented to the user.
69 *
70 * The filter is evaluated by performing an 'AND' operation
71 * on its individual elements. In other words, all the defined
72 * elements must evaluate to `true` for the filter to evaluate
73 * to `true`.
74 *
75 * Each example typically defines an array of more than one filter;
76 * see {@link #TemplateInfo TemplateInfo.filterArr}. This filter array
77 * is evaluated using the 'OR' operation. In other words, the example
78 * is presented to the user when any one of the filters evaluate
79 * to `true`.
80 *
81 * Each filter property can be an arbitrary Java regular expression.
82 * In addition, each allows the user to define the NOT property
83 * by inserting a "~" character at the start of the string. For
84 * example, if the deviceFamily field is set to "~MSP430", the example
85 * will be displayed for all device families except "MSP430".
86 *
87 * @field(deviceFamily) String indicating the device family
88 * eg. "MSP430","C6000"
89 * @field(deviceVariant) String indicating device variant
90 * eg. "C674X", "CortexA8"
91 * @field(deviceId) String indicating the device part number
92 * eg. "TMS320C6747"
93 * @field(endianness) String indicating the device endianness
94 * eg. "little", "big"
95 * @field(toolChain) String indicating the tool chain
96 * eg. "TI", "GNU"
97 * @field(outputFormat) String indicating the object file format
98 * eg. "COFF", "ELF"
99 */
100 struct Filter {
101 String deviceFamily;
102 String deviceVariant;
103 String deviceId;
104 String endianness;
105 String toolChain;
106 String outputFormat;
107 };
108
109 /*!
110 * ======== TemplateInfo ========
111 * TemplateInfo structure
112 *
113 * @field(title) String containing the title of the template
114 * @field(name) String containing the name of the project created from this
115 * template
116 * @field(fileList) Array of {@link #FileDesc} defining the
117 * properties of the files contributed by this
118 * example.
119 * @field(description) String containing description of example
120 * @field(target) String containing RTSC target
121 * @field(platform) String containing RTSC platform
122 * @field(buildProfile) String containing RTSC build profile
123 * @field(linkerCommandFile) Linker command file for the example. If
124 * this is set to the empty string then no
125 * linker command file is added by the IDE
126 * to the example. If this is not defined
127 * then the wizard picks the default
128 * linker command file for the selected device.
129 * @field(compilerBuildOptions) Special compiler options required to
130 * build template. For example the template
131 * may need special -I and -D options
132 * to build and these may be specified
133 * here.
134 * @field(linkerBuildOptions) Special linker options to build template
135 * @field(requiredProducts) Products required to build this
136 * example. Products are identified by
137 * their globally unique
138 * {@link xdc.tools.product.IProduct#id}
139 * eg. 'com.ti.bios'. Dependency on a
140 * minimum version of a product may be
141 * defined in the following manner
142 * : <product-id>:<min-version>
143 * @field(xdcToolsVersion) String containing XDCTools the exact version
144 * required eg. '3.24.6.63'. Note that this
145 * number must be an 'eclipse' version number:
146 * no leading 0's in the first three segments
147 * and the forth is treated as an arbitrary
148 * string.
149 *
150 * If this string is `undefined`, any
151 * version of XDCtools will be allowed.
152 *
153 * If the exact version doesn't exist for some
154 * reason, the project will still be
155 * created, but the project will give a 'this
156 * version of XDCtools doesn't exist' warning.
157 * The user can then select a version that is
158 * hopefully compatible.
159 *
160 * @field(groups) Array of strings referring example groups
161 * that a particular example may
162 * belong. Products may
163 * provide examples that are part of an
164 * existing example group eg."Empty Projects"
165 * that are defined elsewhere. The
166 * groups are identified by an unique id.
167 * @field(configOnly) Flag indicating to the IDE
168 * whether example contributes only
169 * to a RTSC configuration project.
170 * @field(configuroOptions) This string contains options that are passed
171 * to `xdc.tools.configuro`. You must be
172 * careful to quote embedded special characters
173 * in this string in such a way that they can
174 * be directly embedded in an XML file. For
175 * example, to pass '-foo "bar"' to `configuro`
176 * you must use the string
177 * '-foo "bar"'.
178 *
179 * @field(isHybrid) Flag indicating to the IDE
180 * whether example contains RTSC
181 * configuration and target
182 * content files in one project.
183 * If this field is set to `true`
184 * then the IDE consuming this example will
185 * create one project with all the
186 * files. Otherwise multiple projects will
187 * be created - one containing the
188 * target content and the other containing
189 * the RTSC configuration files. This flag
190 * is applies only when `configOnly`
191 * flag is set to `false`.
192 * @field(filterArr) Array of {@link #Filter}. Used to specify
193 * the constraints for a particular
194 * example. The filter array is evaluated using
195 * an OR operation on the individual array
196 * elements. Note that individual elements
197 * within a {@link #Filter filter} is evaluated
198 * with the 'AND' operation.
199 *
200 * @field(options) Comma separated list of options used to
201 * specify various configurable items for this
202 * template. For example, the
203 * `{@link xdc.tools.product.trexgen trexgen}`
204 * tool recognizes the following flags:
205 * "NPW" - display this example in the New
206 * Project Wizard, and
207 * "TREX" - display this example in the
208 * Resource Explorer
209 *
210 * @field(references) Comma separated list of referenced project
211 * names
212 *
213 * @field(buildCommandFlags) Comma separated list of build-command flags.
214 *
215 * @field(launchWizard) Flag indicating to launch the New Project
216 * wizard allowing the user to adjust the
217 * details.
218 *
219 * @field(preBuildStep) Shell cmd to run before the build. Cmd is
220 * run within the debug/release directory
221 *
222 * @field(postBuildStep) Shell cmd to run after the build. Cmd is run
223 * within the debug/release directory
224 */
225 struct TemplateInfo {
226 String title; /*! Title of this example */
227 String name; /*! Name of the project imported from
228 * this template
229 */
230 FileDesc fileList[]; /*! List of files along with properties
231 * for this example
232 */
233 String description; /*! Description of this example */
234 String target; /*! RTSC target */
235 String platform; /*! RTSC platform */
236 String buildProfile; /*! RTSC build profile */
237 String linkerCommandFile; /*! Linker file for this example */
238 String compilerBuildOptions; /*! Special compiler options */
239 String linkerBuildOptions; /*! Special linker options */
240 String requiredProducts[]; /*! List of products required to build
241 * this example
242 */
243 String xdcToolsVersion; /*! Version of xdctools this template
244 * requires eg. '3.24.6.63' */
245 String groups[]; /*! Array of group ids for groups
246 * containing this example */
247 Bool legacyTcf;
248 String configuroOptions; /*! configuro options */
249 Bool configOnly; /*! Indicates whether only a RTSC
250 * configuration project should
251 * be created for this example.
252 */
253 Bool isHybrid; /*! Indicates whether application and
254 * configuration content exists in
255 * one project
256 */
257 Filter filterArr[]; /*! Array of filters for this example */
258 String options; /*! Comma separated attributes */
259 String references; /*! Comma separated list of referenced
260 * project names */
261 String buildCommandFlags; /*! Comma seperated list of build-command
262 * flags */
263 Bool launchWizard; /*! Flag indicating to launch the New
264 * Project Wizard allowing the user to
265 * adjust the details */
266 String preBuildStep; /*! Shell cmd to run before the build.
267 * Cmd is run within the debug/release
268 * directory */
269 String postBuildStep; /*! Shell cmd to run after the build. Cmd
270 * is run within the debug/release
271 * directory */
272 };
273
274 /*!
275 * ======== TemplateGroup ========
276 * TemplateGroup structure
277 *
278 * This structure may be used to define a hierarchy of examples
279 * for the product. Examples may be logically organized into groups
280 * with an unique `id` and may specify membership of other groups
281 * by referring to their ids in the `groups` array. In this manner
282 * the example producer can define a tree topology of examples for
283 * their product. Once the template groups are defined, the
284 * individual examples may specify their membership within a template
285 * group in the `groups` array of {@link #TemplateInfo}. The example
286 * provider may specify all the defined groups for their product in
287 * {@link #templateGroupArr}.
288 *
289 * @field(id) Unique id for the template group
290 * @field(name) Name of the group
291 * @field(description) Description of the group
292 * @field(groups) Array of group ids used to specify
293 * membership of other groups.
294 */
295 struct TemplateGroup {
296 String id;
297 String name;
298 String description;
299 String groups[];
300 };
301
302 /*!
303 * ======== templateArr ========
304 * Examples contained in the product
305 */
306 config TemplateInfo templateArr[];
307
308 /*!
309 * ======== templateGroupArr ========
310 * Array of template group ids
311 *
312 * This array may be optionally specified by Products that
313 * organize their examples into groups.
314 */
315 config TemplateGroup templateGroupArr[] = [];
316 }
317 318 319
320