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