1    /* 
     2     *  Copyright (c) 2009 Texas Instruments and others.
     3     *  All rights reserved. This program and the accompanying materials
     4     *  are made available under the terms of the Eclipse Public License v1.0
     5     *  which accompanies this distribution, and is available at
     6     *  http://www.eclipse.org/legal/epl-v10.html
     7     * 
     8     *  Contributors:
     9     *      Texas Instruments - initial implementation
    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     *  @(#) xdc.tools.product; 1, 0, 0,79; 12-19-2012 16:40:08; /db/ztree/library/trees/xdctools/xdctools-f20x/src/
   407     */
   408