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