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 specify the mapping between device names and/or device
66 * family names and a RTSC target module in a JSON file located in the
67 * product itself. The field `sourceFile` contains the file name including
68 * the path relative to the top directory of the product.
69 *
70 * The content of the file is read whenever a product is used in a project
71 * and the information from the file is leveraged by tools to derive an
72 * appropriate RTSC target when given a device name, device family,
73 * endiness, and OMF selection (COFF verses ELF).
74 *
75 * The JSON file contains objects, and each object is matched against the
76 * device and build options selected for a particular project. If all
77 * object attributes, except for the target specification, are matched by
78 * supplied options, the target represented by the object is returned.
79 * Objects are matched against the options in the order they are listed in
80 * the JSON file. As soon as a match is found, the search stops.
81 *
82 * Currently used object attributes that are matched against build options
83 * are `deviceFamilyPattern`, `deviceNamePattern`, `deviceVariant` and
84 * `elf`. Object attributes that specify a target are `packageName` and
85 * `baseTargetName`, where `packageName` is the name of a package that
86 * contains targets, while `baseTargetName` is a name of a target module
87 * in that package.
88 *
89 * In particular, if the device name and family name selected for a project
90 * match `deviceNamePattern` and `deviceFamilyPattern` in an object, the
91 * target name generated will be:
92 * @p(code)
93 * <packageName>[.elf].<baseTargetName>[_big_endian]
94 * @p
95 * The strings ".elf" and "_big_endian" are added if the corresponding
96 * project options are specified.
97 *
98 * Suppose, for example, a product specifies the following target mapping:
99 * @p(code)
100 * {
101 * deviceNamePattern: "MSP430F5.*",
102 * deviceFamilyPattern: "MSP430.*",
103 * packageName: "ti.targets.msp430",
104 * baseTargetName: "MSP430X"
105 * }
106 * @p
107 * If the device specified is "`MSP430F5529`", the family is "`MSP430`",
108 * and the OMF is COFF, the generated target will be:
109 * @p(code)
110 * ti.targets.msp430.MSP430X
111 * @p
112 * On the other hand, if the OMF is ELF the target will be:
113 * @p(code)
114 * ti.targets.msp430.elf.MSP430X
115 * @p
116 *
117 * @field(sourceFile) The path to a file that defines the mapping
118 * in a JSON file
119 */
120 struct Target {
121 String sourceFile; /*! Name of a file with target mapping */
122 };
123
124 /*!
125 * ======== UrlDescriptor ========
126 * URL Descriptor structure
127 *
128 * @field(url) Uniform Resource Locator(URL)
129 * @field(text) Summary text for the URL
130 * @field(targetText) Optional summary text for any target content
131 * portion
132 */
133 struct UrlDescriptor {
134 String url; /*! Uniform Resource Locator(URL) */
135 String text; /*! Summary text for the URL */
136 String targetText; /*! (optional) Summary for target portion */
137 };
138
139 /*!
140 * ======== PluginDescriptor ========
141 * Plugin Descriptor structure
142 *
143 * @field(id) Plugin id
144 * @field(version) Plugin version
145 * @field(path) Path to plugin relative to `IProduct` implementation
146 */
147 struct PluginDescriptor {
148 String id; /*! Plugin id */
149 String version; /*! Plugin version */
150 String path; /*! Plugin path */
151 };
152
153 /*!
154 * ======== MacroDescriptor ========
155 * Macro Descriptor structure
156 */
157 struct MacroDescriptor {
158 String name; /*! Macro name */
159 String desc; /*! Macro description */
160 };
161
162 /*!
163 * ======== name ========
164 * Product name
165 *
166 * String containing product name eg. System BIOS
167 */
168 config String name;
169
170 /*!
171 * ======== id ========
172 * A unique product id
173 *
174 * For example, product developers may choose to follow namespace
175 * conventions for Java packages or Eclipse plugins to specify a
176 * unique id like `org.eclipse.rtsc.xdctools.product`.
177 */
178 config String id;
179
180 /*!
181 * ======== version ========
182 * Product version
183 *
184 * The product version should follow the format
185 * -`major.minor.service.qualifier` where
186 * `major`,`minor` and `service` are integers and
187 * `qualifier` is a string. Example - 3.16.02.31-eng.
188 *
189 * Products may specify their own guidelines for
190 * updating `major`,`minor`,`service` and `qualifier` portions of the
191 * version number as long as they are unique for the product.
192 * Products may also choose to follow popular versioning conventions
193 * like those followed for versioning Eclipse plugins.
194 */
195 config String version;
196
197 /*!
198 * ======== featureId ========
199 * A unique feature id
200 *
201 * @_nodoc - Deprecated
202 *
203 * Feature ids are used by a system to install product upgrades.
204 * Typically a system will look at various versions of a
205 * feature available in the system and allow the user to upgrade
206 * to the latest version. The product developer can use the `featureId`
207 * to manage the granularity of product upgrades in a system. For
208 * example the version `3.20.0.00` for product
209 * `org.eclipse.rtsc.xdctools.product` may have the `featureId`
210 * `org.eclipse.rtsc.xdctools.product_3.20`.
211 * The product developer may allow the upgrade system to pick up
212 * patch releases to `3.20.0.00` release by specifying different
213 * versions of the product (eg. 3.20.0.01) with `featureId`
214 * `org.eclipse.rtsc.xdctools.product_3.20`
215 */
216 config String featureId;
217
218 /*!
219 * ======== updateSite ========
220 * Update site for product
221 *
222 * @field(url) the `url` field should contain the URL containing
223 * product upgrades.
224 *
225 * @field(text) the `text` field should contain summary description of
226 * the update site
227 */
228 config UrlDescriptor updateSite;
229
230 /*!
231 * ======== companyName ========
232 * Name of company releasing product
233 *
234 * Example : "Texas Instruments"
235 */
236 config String companyName;
237
238 /*!
239 * ======== productDescriptor ========
240 * Product description
241 *
242 * @field(url) the `url` field should contain a product-specific "home"
243 * page URL or, if there is none, the URL of organization
244 * releasing the product.
245 *
246 * @field(text) the `text` field should contain summary description of
247 * the target content portion of the product.
248 */
249 config UrlDescriptor productDescriptor;
250
251 /*!
252 * ======== licenseDescriptor ========
253 * License information for product
254 *
255 * @field(url) field should contain the URL containing the
256 * license text.
257 *
258 * @field(text) field should contain a summary description of the license
259 */
260 config UrlDescriptor licenseDescriptor;
261
262 /*!
263 * ======== copyRightNotice ========
264 * Copyright notice for product
265 */
266 config String copyRightNotice;
267
268 /*!
269 * ======== repositoryArr ========
270 * Repositories contained in the product
271 *
272 * Repositories are specified relative to the product installation
273 * directory.
274 */
275 config String repositoryArr[];
276
277 /*!
278 * ======== docsLocArr ========
279 * Directories containing documents in the product
280 *
281 * Directories are specified relative to the product installation
282 * directory. These directories are searched when resolving URI links
283 * to specific pages within the docs.
284 */
285 config String docsLocArr[];
286
287 /*!
288 * ======== templateModule ========
289 * Name of module implementing {@link xdc.tools.product.IProductTemplate}
290 *
291 * Products that deliver examples provide a module that implements the
292 * {@link xdc.tools.product.IProductTemplate} interface. This module
293 * must be delivered in one of the repositories defined in
294 * {@link #repositoryArr}.
295 */
296 config String templateModule;
297
298 /*!
299 * ======== productViewModule ========
300 * Name of module implementing {@link xdc.tools.product.IProductView}
301 *
302 * Products must provide a module that implements the
303 * {@link xdc.tools.product.IProductView} interface. This
304 * module defines the "top-level" modules that are visible to the user
305 * and must be delivered in the repositories defined in
306 * {@link #repositoryArr}.
307 */
308 config String productViewModule;
309
310 /*!
311 * ======== bundleName ========
312 * Product bundle name
313 *
314 * Product bundle name is embedded in the top level folder name of
315 * the product. Example: The top level folder for XDCtools version
316 * 3.16.02.31-eng is `xdctools_3_16_02_31-eng`. In this case the
317 * bundle name is `xdctools`.
318 * The bundle name is used by tools to discover the product
319 * installed on a filesystem.
320 */
321 config String bundleName;
322
323 /*!
324 * ======== targetFile ========
325 * File with available RTSC target modules
326 *
327 * The RTSC target modules should be delivered
328 * in the repositories defined in {@link #repositoryArr}
329 */
330 config Target targetFile;
331
332 /*!
333 * ======== helpTocArr ========
334 * Array of table of contents elements in product
335 *
336 * Tools generating table of contents are required
337 * to preserve the order of elements specified in this array.
338 */
339 config HelpToc helpTocArr[];
340
341 /*!
342 * ======== tocIndexFile ========
343 * Top level help index file
344 *
345 * In eclipse help, for example, this file is displayed when the
346 * product's top-level entry is selected in eclipse's help table of
347 * contents. If this file is not provided a very basic list of links
348 * to the entries listed in `@{link #helpTocArr}` is displayed.
349 */
350 config String tocIndexFile;
351
352 /*!
353 * ======== exclusive ========
354 * This product is a singleton
355 *
356 * This flag indicates whether multiple versions of this product are
357 * accessable within the IDE or whether only the latest version is
358 * available.
359 *
360 * When flag is set to `true` it indicates that only one
361 * version of the product can be active in the system. Otherwise
362 * the system can handle multiple versions of the same product.
363 */
364 config Bool exclusive = false;
365
366 /*!
367 * ======== otherFiles ========
368 * Array of paths to files or directories to copy into the product
369 *
370 * A product may need to contain "arbitrary" files important to its
371 * operation. For example a product may provide text, images and video
372 * files that provide templates or branding information for the product.
373 * These files may then be consumed by tools like IDE's via
374 * hooks defined in the IDE framework.
375 *
376 * The source file path is defined relative to the directory containing
377 * the implementation of `IProduct`. All files or directories are
378 * copied to the base directory of the plugin; e.g.,
379 * "../branding/about.ini" is copied to "about.ini" at the top of the
380 * plugin.
381 *
382 * Path names that begin with the prefix "tc:" are copied into "target
383 * content" plugin whereas path names with any other prefix (such as
384 * "ui:" or no prefix) are copied into the "IDE plugin".
385 */
386 config String otherFiles[];
387
388 /*!
389 * ======== macro ========
390 * Macro associated with the product
391 *
392 * Product macros are often used in IDEs for providing
393 * portable build environments. A unique macro name should
394 * be selected for the product.
395 */
396 config MacroDescriptor macro;
397
398 /*!
399 * ======== externalPlugins ========
400 * External plugins delivered with the product
401 */
402 config PluginDescriptor externalPlugins[];
403
404 /*!
405 * ======== externalRequirements ========
406 * External plugins required by this product
407 */
408 config String externalRequirements[];
409
410 /*!
411 * ======== projectSpecPath ========
412 * Directory containing project spec files
413 *
414 * This path is relative to the product install location.
415 */
416 config String projectSpecPath = "resources";
417 }
418 419 420
421