1 2 3 4 5 6 7 8 9 10 11
12
13 /*!
14 * ======== IProduct ========
15 * Interface specifying product details.
16 *
17 * This interface allows products describe themselves for the benefit
18 * of development tools such as IDE's. For example, a tool
19 * can read the information provided by a product that implements this
20 * interface and generate an eclipse plugin that leverages the product's
21 * "resources".
22 *
23 * By expressing the product's information in this interface, a product
24 * can be delivered into multiple development tools without explicit
25 * knowledge of these tools. For example, an online "product repository"
26 * can extract sufficient information from this interface to enable it
27 * to provide a searchable catalog of interesting products.
28 *
29 * This is an experimental interface and is subject to change
30 */
31 metaonly interface IProduct
32 {
33 /*!
34 * ======== HelpToc ========
35 * Help table of contents (TOC) element
36 *
37 * A help TOC element defines a file, URL, or a secondary table of
38 * contents that is referenced from a global table of contents.
39 *
40 * @field(label) Summary description of help element which
41 * is displayed in the global table of contents.
42 * @field(filePath) Relative path to help documentation file or a
43 * secondary table of contents file or a URL. Relative
44 * paths are relative to the directories specified in
45 * {@link #docsLocArr}; files are searched for, in
46 * order, within each directory and the first file
47 * found that matches the name is used.
48 * @field(tocFile) Flag indicates whether the element is a
49 * table of contents (TOC) file. Tools may
50 * process TOC files in a special way. For
51 * example, a tool to generate eclipse plugins
52 * must copy the TOC file to the plugin folder
53 * for integrating with eclipse help.
54 */
55 struct HelpToc {
56 String label; /*! Help element description */
57 String filePath; /*! Path to help doc */
58 Bool tocFile; /*! Indicates whether element is a TOC file */
59 };
60
61 /*!
62 * ========= Target ==============
63 * Structure containing information on RTSC targets
64 *
65 * Products may specify the mapping between device names and/or device
66 * family names and a RTSC target module.
67 *
68 * This information is leveraged by tools to derive an appropriate
69 * RTSC target when given a device name, device family, endiness, and
70 * OMF selection (COFF verses ELF). In particular, if the device name
71 * and family name match `deviceNamePattern` and
72 * `deviceFamilyPattern`, the target name generated will be:
73 * @p(code)
74 * <packageName>[.elf].<baseTargetName>[_big_endian]
75 * @p
76 * where `<packageName>` and `<baseTargetName>` are the strings specified
77 * by the corespondingly named fields of this structure, and the strings
78 * `".elf"` and `"_big_endian"` are added as necessary.
79 *
80 * Suppose, for example, a product specifies the following target mapping:
81 * @p(code)
82 * {
83 * deviceNamePattern: "MSP430F5.*",
84 * deviceFamilyPattern: "MSP430.*",
85 * packageName: "ti.targets.msp430",
86 * baseTargetName: "MSP430X"
87 * }
88 * @p
89 * If the device specified is "`MSP430F5529`", the family is "`MSP430`",
90 * and the OMF is COFF, the generated target will be:
91 * @p(code)
92 * ti.targets.msp430.MSP430X
93 * @p
94 * On the other hand, if the OMF is ELF the target will be:
95 * @p(code)
96 * ti.targets.msp430.elf.MSP430X
97 * @p
98 *
99 * @field(deviceNamePattern) A regular expression for device names
100 * @field(deviceFamilyPattern) A regular expression for device families
101 * @field(packageName) The name of a package containing a
102 * target module that can be used with
103 * the devices that match the
104 * device name and family patterns
105 * @field(baseTargetName) The name of the module
106 * (without the package prefix) in
107 * the package named by `packageName`.
108 */
109 struct Target {
110 String deviceNamePattern; /*! Device name regex eg. MSP430* */
111 String deviceFamilyPattern; /*! Device family regex eg. C6* */
112 String compilerOptsPattern; /*! Compiler opts regx; e.g. .*-me .* */
113 String packageName; /*! Package containing RTSC target */
114 String baseTargetName; /*! Name of RTSC target module */
115 };
116
117 /*!
118 * ======== UrlDescriptor ========
119 * URL Descriptor structure
120 *
121 * @field(url) Uniform Resource Locator(URL)
122 * @field(text) Summary text for the URL
123 * @field(targetText) Optional summary text for any target content
124 * portion
125 */
126 struct UrlDescriptor {
127 String url; /*! Uniform Resource Locator(URL) */
128 String text; /*! Summary text for the URL */
129 String targetText; /*! (optional) Summary for target portion */
130 };
131
132 /*!
133 * ======== PluginDescriptor ========
134 * Plugin Descriptor structure
135 *
136 * @field(id) Plugin id
137 * @field(version) Plugin version
138 * @field(path) Path to plugin relative to `IProduct` implementation
139 */
140 struct PluginDescriptor {
141 String id; /*! Plugin id */
142 String version; /*! Plugin version */
143 String path; /*! Plugin path */
144 };
145
146 /*!
147 * ======== MacroDescriptor ========
148 * Macro Descriptor structure
149 */
150 struct MacroDescriptor {
151 String name; /*! Macro name */
152 String desc; /*! Macro description */
153 };
154
155 /*!
156 * ======== name ========
157 * Product name
158 *
159 * String containing product name eg. System BIOS
160 */
161 config String name;
162
163 /*!
164 * ======== id ========
165 * A unique product id
166 *
167 * For example, product developers may choose to follow namespace
168 * conventions for Java packages or Eclipse plugins to specify a
169 * unique id like `org.eclipse.rtsc.xdctools.product`.
170 */
171 config String id;
172
173 /*!
174 * ======== version ========
175 * Product version
176 *
177 * The product version should follow the format
178 * -`major.minor.service.qualifier` where
179 * `major`,`minor` and `service` are integers and
180 * `qualifier` is a string. Example - 3.16.02.31-eng.
181 *
182 * Products may specify their own guidelines for
183 * updating `major`,`minor`,`service` and `qualifier` portions of the
184 * version number as long as they are unique for the product.
185 * Products may also choose to follow popular versioning conventions
186 * like those followed for versioning Eclipse plugins.
187 */
188 config String version;
189
190 /*!
191 * ======== featureId ========
192 * A unique feature id
193 *
194 * @_nodoc - Deprecated
195 *
196 * Feature ids are used by a system to install product upgrades.
197 * Typically a system will look at various versions of a
198 * feature available in the system and allow the user to upgrade
199 * to the latest version. The product developer can use the `featureId`
200 * to manage the granularity of product upgrades in a system. For
201 * example the version `3.20.0.00` for product
202 * `org.eclipse.rtsc.xdctools.product` may have the `featureId`
203 * `org.eclipse.rtsc.xdctools.product_3.20`.
204 * The product developer may allow the upgrade system to pick up
205 * patch releases to `3.20.0.00` release by specifying different
206 * versions of the product (eg. 3.20.0.01) with `featureId`
207 * `org.eclipse.rtsc.xdctools.product_3.20`
208 */
209 config String featureId;
210
211 /*!
212 * ======== updateSite ========
213 * Update site for product
214 *
215 * @field(url) the `url` field should contain the URL containing
216 * product upgrades.
217 *
218 * @field(text) the `text` field should contain summary description of
219 * the update site
220 */
221 config UrlDescriptor updateSite;
222
223 /*!
224 * ======== companyName ========
225 * Name of company releasing product
226 *
227 * Example : "Texas Instruments"
228 */
229 config String companyName;
230
231 /*!
232 * ======== productDescriptor ========
233 * Product description
234 *
235 * @field(url) the `url` field should contain the URL of the organization
236 * releasing the product.
237 *
238 * @field(text) the `text` field should contain summary description of
239 * the target content portion of the product. Alternate text for the
240 * UI portion can be specified via {@link #productUIDescription}`.
241 */
242 config UrlDescriptor productDescriptor;
243
244 /*!
245 * ======== licenseDescriptor ========
246 * License information for product
247 *
248 * @field(url) field should contain the URL containing the
249 * license text.
250 *
251 * @field(text) field should contain a summary description of the license
252 */
253 config UrlDescriptor licenseDescriptor;
254
255 /*!
256 * ======== copyRightNotice ========
257 * Copyright notice for product
258 */
259 config String copyRightNotice;
260
261 /*!
262 * ======== repositoryArr ========
263 * Repositories contained in the product
264 *
265 * Repositories are specified relative to the product installation
266 * directory.
267 */
268 config String repositoryArr[];
269
270 /*!
271 * ======== docsLocArr ========
272 * Directories containing documents in the product
273 *
274 * Directories are specified relative to the product installation
275 * directory. These directories are searched when resolving URI links
276 * to specific pages within the docs.
277 */
278 config String docsLocArr[];
279
280 /*!
281 * ======== templateModule ========
282 * Name of module implementing {@link xdc.tools.product.IProductTemplate}
283 *
284 * Products that deliver examples provide a module that implements the
285 * {@link xdc.tools.product.IProductTemplate} interface. This module
286 * must be delivered in one of the repositories defined in
287 * {@link #repositoryArr}.
288 */
289 config String templateModule;
290
291 /*!
292 * ======== productViewModule ========
293 * Name of module implementing {@link xdc.tools.product.IProductView}
294 *
295 * Products must provide a module that implements the
296 * {@link xdc.tools.product.IProductView} interface. This
297 * module defines the "top-level" modules that are visible to the user
298 * and must be delivered in the repositories defined in
299 * {@link #repositoryArr}.
300 */
301 config String productViewModule;
302
303 /*!
304 * ======== bundleName ========
305 * Product bundle name
306 *
307 * Product bundle name is embedded in the top level folder name of
308 * the product. Example: The top level folder for XDCtools version
309 * 3.16.02.31-eng is `xdctools_3_16_02_31-eng`. In this case the
310 * bundle name is `xdctools`.
311 * The bundle name is used by tools to discover the product
312 * installed on a filesystem.
313 */
314 config String bundleName;
315
316 /*!
317 * ======== targetArr ========
318 * RTSC target modules contained in product
319 *
320 * The RTSC target modules should be delivered
321 * in the repositories defined in {@link #repositoryArr}
322 */
323 config Target targetArr[];
324
325 /*!
326 * ======== helpTocArr ========
327 * Array of table of contents elements in product
328 *
329 * Tools generating table of contents are required
330 * to preserve the order of elements specified in this array
331 */
332 config HelpToc helpTocArr[];
333
334 /*!
335 * ======== tocIndexFile ========
336 * Top level index file referred in table of contents
337 */
338 config String tocIndexFile;
339
340 /*!
341 * ======== exclusive ========
342 * This product is a singlton
343 *
344 * This flag indicates whether multiple versions of this product are
345 * accessable within the IDE or whether only the latest version is
346 * available.
347 *
348 * When flag is set to `true` it indicates that only one
349 * version of the product can be active in the system. Otherwise
350 * the system can handle multiple versions of the same product.
351 */
352 config Bool exclusive = false;
353
354 /*!
355 * ======== otherFiles ========
356 * Array of paths to files that describe the product
357 *
358 * A product may wish to supply files that describing certain aspects
359 * of itself. For example a product may provide text, images and video
360 * files that provide branding information for the product.
361 * These files may then be consumed by tools like IDE's via
362 * hooks defined in the IDE framework.
363 *
364 * The source file path is defined relative to the directory containing
365 * the implementation of `IProduct`. All files are copied to the base
366 * directory of the plugin; e.g., "../branding/about.ini" is copied to
367 * "about.ini" at the top of the plugin.
368 *
369 * File names that begin with the prefix "tc:" are copied into "target
370 * content" plugin whereas file names with any other prefix (such as
371 * "ui:" or no prefix) are copied into the "IDE plugin".
372 */
373 config String otherFiles[];
374
375 /*!
376 * ======== macro ========
377 * Macro associated with the product
378 *
379 * Product macros are often used in IDEs for providing
380 * portable build environments. A unique macro name should
381 * be selected for the product.
382 */
383 config MacroDescriptor macro;
384
385 /*!
386 * ======== externalPlugins ========
387 * External plugins delivered with the product
388 */
389 config PluginDescriptor externalPlugins[];
390
391 /*!
392 * ======== externalRequirements ========
393 * External plugins required by this product
394 */
395 config String externalRequirements[];
396
397 /*!
398 * ======== projectSpecPath ========
399 * Directory containing project spec files
400 *
401 * This path is relative to the product install location.
402 */
403 config String projectSpecPath = "resources";
404 }
405 406 407
408