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