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(endianness) String containing the endianness of the
162 * project (little|big|be8|be32).
163 * @field(outputFormat) String indicating object file format (COFF, ELF)
164 * @field(requiredProducts) Products required to build this
165 * example. Products are identified by
166 * their globally unique
167 * {@link xdc.tools.product.IProduct#id}
168 * eg. 'com.ti.bios'. Dependency on a
169 * minimum version of a product may be
170 * defined in the following manner
171 * : <product-id>:<min-version>
172 * @field(xdcToolsVersion) String containing XDCTools the exact version
173 * required eg. '3.24.6.63'. Note that this
174 * number must be an 'eclipse' version number:
175 * no leading 0's in the first three segments
176 * and the forth is treated as an arbitrary
177 * string.
178 *
179 * If this string is `undefined`, any
180 * version of XDCtools will be allowed.
181 *
182 * If the exact version doesn't exist for some
183 * reason, the project will still be
184 * created, but the project will give a 'this
185 * version of XDCtools doesn't exist' warning.
186 * The user can then select a version that is
187 * hopefully compatible.
188 *
189 * @field(groups) Array of strings referring example groups
190 * that a particular example may
191 * belong. Products may
192 * provide examples that are part of an
193 * existing example group eg."Empty Projects"
194 * that are defined elsewhere. The
195 * groups are identified by an unique id.
196 * @field(configOnly) Flag indicating to the IDE
197 * whether example contributes only
198 * to a RTSC configuration project.
199 * @field(configuroOptions) This string contains options that are passed
200 * to `xdc.tools.configuro`. You must be
201 * careful to quote embedded special characters
202 * in this string in such a way that they can
203 * be directly embedded in an XML file. For
204 * example, to pass '-foo "bar"' to `configuro`
205 * you must use the string
206 * '-foo "bar"'.
207 *
208 * @field(isHybrid) Flag indicating to the IDE whether example
209 * contains RTSC configuration and target
210 * content files in one project.
211 * If this field is set to `true`, then the IDE
212 * consuming this example will create one project
213 * with all the files. Otherwise, multiple
214 * projects will be created - one containing the
215 * target content and the other containing the
216 * RTSC configuration files. This flag applies
217 * only when `configOnly` flag is set to `false`.
218 *
219 * @field(filterArr) Array of {@link #Filter}. Used to specify
220 * the constraints for a particular
221 * example. The filter array is evaluated using
222 * an OR operation on the individual array
223 * elements. Note that individual elements
224 * within a {@link #Filter filter} is evaluated
225 * with the 'AND' operation.
226 *
227 * @field(ignoreDefaults) Property {@link #Filter filter} commonly
228 * specifies a device. Each device has an XML
229 * file with default settings, which are applied
230 * to a project, in addition to properties
231 * specified here. Whe this parameter is set to
232 * 'true', these default options are ignored.
233 *
234 * @field(options) Comma separated list of options used to
235 * specify various configurable items for this
236 * template. For example, the
237 * `{@link xdc.tools.product.trexgen trexgen}`
238 * tool recognizes the following flags:
239 * "NPW" - display this example in the New
240 * Project Wizard, and
241 * "TREX" - display this example in the
242 * Resource Explorer
243 *
244 * @field(references) Comma separated list of referenced project
245 * names
246 *
247 * @field(buildCommandFlags) Comma separated list of build-command flags.
248 *
249 * @field(launchWizard) Flag indicating to launch the New Project
250 * wizard allowing the user to adjust the
251 * details.
252 *
253 * @field(preBuildStep) Shell cmd to run before the build. Cmd is
254 * run within the debug/release directory
255 *
256 * @field(postBuildStep) Shell cmd to run after the build. Cmd is run
257 * within the debug/release directory
258 */
259 struct TemplateInfo {
260 String title; /*! Title of this example */
261 String name; /*! Name of the project imported from
262 * this template
263 */
264 FileDesc fileList[]; /*! List of files along with properties
265 * for this example
266 */
267 String description; /*! Description of this example */
268 String target; /*! RTSC target */
269 String platform; /*! RTSC platform */
270 Board board; /*! Properties of the board */
271 String buildProfile; /*! RTSC build profile */
272 String linkerCommandFile; /*! Linker file for this example */
273 String compilerBuildOptions; /*! Special compiler options */
274 String linkerBuildOptions; /*! Special linker options */
275 String endianness; /*! endian setting (little|big|be8|be32) */
276 String outputFormat; /*! format of object file (COFF or ELF) */
277 String requiredProducts[]; /*! List of products required to build
278 * this example
279 */
280 String xdcToolsVersion; /*! Version of xdctools this template
281 * requires eg. '3.24.6.63' */
282 String groups[]; /*! Array of group ids for groups
283 * containing this example */
284 Bool legacyTcf;
285 String configuroOptions; /*! configuro options */
286 Bool configOnly; /*! Indicates whether only a RTSC
287 * configuration project should
288 * be created for this example.
289 */
290 Bool isHybrid; /*! Indicates whether application and
291 * configuration content exists in
292 * one project
293 */
294 Bool isFragment; /*! Indicates whether this template
295 * can be applied "incrementally"
296 * to an already existing project
297 */
298 Filter filterArr[]; /*! Array of filters for this example */
299 Bool ignoreDefaults; /*! Indicates if settings from the
300 * device XML file are ignored.
301 */
302 String options; /*! Comma separated attributes */
303 String references; /*! Comma separated list of referenced
304 * project names */
305 String buildCommandFlags; /*! Comma seperated list of build-command
306 * flags */
307 Bool launchWizard; /*! Flag indicating to launch the New
308 * Project Wizard allowing the user to
309 * adjust the details */
310 String preBuildStep; /*! Shell cmd to run before the build.
311 * Cmd is run within the debug/release
312 * directory */
313 String postBuildStep; /*! Shell cmd to run after the build. Cmd
314 * is run within the debug/release
315 * directory */
316 String projectType; /*! type of project. If this field is
317 * not set, a default will be used that
318 * is based on other settings. If it is
319 * set to "ccs", the project will be a
320 * "Code Composer Studio" project.
321 */
322 String outputType; /*! type of output produced by this
323 * project: "executable" or
324 * "staticLibrary", or "any". The "any"
325 * type indicates that this project
326 * template applies to type of output,
327 * executable, library, etc.
328 *
329 * If this field is not set "any" is
330 * used.
331 */
332 };
333
334 /*!
335 * ======== TemplateGroup ========
336 * TemplateGroup structure
337 *
338 * This structure may be used to define a hierarchy of examples for the
339 * product. Examples may be logically organized into groups with a unique
340 * `id` and may specify membership of other groups by referring to their
341 * ids in the `groups` array. In this manner, the example producer
342 * can define a tree topology of examples for their product. Once the
343 * template groups are defined, the individual examples may specify their
344 * membership within a template group in the `groups` array of
345 * {@link #TemplateInfo}. The example provider may specify all the defined
346 * groups for their product in {@link #templateGroupArr}.
347 *
348 * @field(id) Unique id for the template group
349 * @field(name) Name of the group
350 * @field(description) Description of the group
351 * @field(groups) Array of group ids used to specify
352 * membership of other groups.
353 */
354 struct TemplateGroup {
355 String id;
356 String name;
357 String description;
358 String groups[];
359 };
360
361 /*!
362 * ======== templateArr ========
363 * Examples contained in the product
364 */
365 config TemplateInfo templateArr[];
366
367 /*!
368 * ======== templateGroupArr ========
369 * Array of template group ids
370 *
371 * This array may be optionally specified by Products that
372 * organize their examples into groups.
373 */
374 config TemplateGroup templateGroupArr[] = [];
375 }
376 377 378
379