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         *  @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     *  @(#) xdc.tools.product; 1, 0, 0,87; 5-23-2013 16:33:09; /db/ztree/library/trees/xdctools/xdctools-f28x/src/
   412     */
   413