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 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 `deviceFamily`, `deviceName`, `deviceVariant`, `endianness` 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         *      deviceName:          "MSP430F5.*",
   102         *      deviceFamily:        "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         *  ======== platformSourceFile ========
   334         *  File with available RTSC platforms
   335         *
   336         *  This parameter points to a JSON file that contains names of platform
   337         *  packages, and project properties that must be matched for a specific
   338         *  platform to be selected.
   339         *  The file path is relative to the top directory of the product.
   340         *  The RTSC platforms should be delivered in the repositories defined in
   341         *  {@link #repositoryArr}
   342         */
   343        config String platformSourceFile;
   344    
   345        /*!
   346         *  ======== helpTocArr ========
   347         *  Array of table of contents elements in product
   348         *
   349         *  Tools generating table of contents are required
   350         *  to preserve the order of elements specified in this array.
   351         */
   352        config HelpToc helpTocArr[];
   353    
   354        /*!
   355         *  ======== tocIndexFile ========
   356         *  Top level help index file
   357         *
   358         *  In eclipse help, for example, this file is displayed when the
   359         *  product's top-level entry is selected in eclipse's help table of
   360         *  contents.  If this file is not provided a very basic list of links
   361         *  to the entries listed in `@{link #helpTocArr}` is displayed.
   362         */
   363        config String tocIndexFile;
   364    
   365        /*!
   366         *  ======== icon ========
   367         *  Icon to be displayed alongside the product description
   368         *
   369         *  In TIREX, this file is used in the top page, where all products are
   370         *  listed, with their icons and names under icons.
   371         */
   372        config String icon;
   373    
   374        /*!
   375         *  ======== exclusive ========
   376         *  This product is a singleton
   377         *
   378         *  This flag indicates whether multiple versions of this product are
   379         *  accessable within the IDE or whether only the latest version is
   380         *  available.
   381         *
   382         *  When flag is set to `true` it indicates that only one 
   383         *  version of the product can be active in the system. Otherwise
   384         *  the system can handle multiple versions of the same product.
   385         */
   386        config Bool exclusive = false;
   387    
   388        /*!
   389         *  ======== otherFiles ========
   390         *  Array of paths to files or directories to copy into the product
   391         *
   392         *  A product may need to contain "arbitrary" files important to its
   393         *  operation. For example a product may provide text, images and video
   394         *  files that provide templates or branding information for the product.
   395         *  These files may then be consumed by tools like IDE's via
   396         *  hooks defined in the IDE framework.
   397         *
   398         *  The source file path is defined relative to the directory containing
   399         *  the implementation  of `IProduct`.  All files or directories are
   400         *  copied to the base directory of the plugin; e.g.,
   401         *  "../branding/about.ini" is copied to "about.ini" at the top of the
   402         *  plugin.
   403         *
   404         *  Path names that begin with the prefix "tc:" are copied into "target
   405         *  content" plugin whereas path names with any other prefix (such as
   406         *  "ui:" or no prefix) are copied into the "IDE plugin".
   407         */
   408        config String otherFiles[];
   409    
   410        /*!
   411         *  ======== macro ========
   412         *  Macro associated with the product
   413         *
   414         *  Product macros are often used in IDEs for providing
   415         *  portable build environments. A unique macro name should
   416         *  be selected for the product.
   417         */
   418        config MacroDescriptor macro;
   419    
   420        /*!
   421         *  ======== externalPlugins ========
   422         *  External plugins delivered with the product
   423         */
   424        config PluginDescriptor externalPlugins[];
   425    
   426        /*!
   427         *  ======== externalRequirements ========
   428         *  External plugins required by this product
   429         */
   430        config String externalRequirements[];
   431    
   432        /*!
   433         *  ======== projectSpecPath ========
   434         *  Directory containing project spec files
   435         *
   436         *  This path is relative to the product install location.
   437         */
   438        config String projectSpecPath = "resources";
   439    }
   440    /*
   441     *  @(#) xdc.tools.product; 1, 0, 0,0; 1-9-2017 12:51:47; /db/ztree/library/trees/xdctools/xdctools-h00/src/
   442     */
   443