1    /* 
     2     *  Copyright (c) 2008 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    package xdc.tools.product;
    13    
    14    /*!
    15     *  ======== IProductTemplate ========
    16     *  Interface to provide examples for a product
    17     *  
    18     *  This interface allows products to contribute examples to
    19     *  development environments like IDE's. This is an experimental 
    20     *  interface and is subject to change.
    21     */
    22    metaonly interface IProductTemplate
    23    {
    24        /*!
    25         *  ======== FileDesc ========
    26         *  Structure defining properties of a file included in an example
    27         *
    28         *  @field(path)                    Path to file relative to the package
    29         *                                  containing the implementation of
    30         *                                  `IProductTemplate`
    31         *  @field(excludeFromBuild)        Flag indicating whether file
    32         *                                  should be excluded from build inside
    33         *                                  an IDE project 
    34         *  @field(openOnCreation)          Flag indicating whether the file
    35         *                                  should be opened when a project
    36         *                                  containing the example file is created
    37         *                                  by the IDE. 
    38         *  @field(copyIntoConfiguration)   Flag indicating whether the file
    39         *                                  should be copied into RTSC
    40         *                                  configuration. This flag
    41         *                                  applies only when the `isHybrid`
    42         *                                  flag of the
    43         *                                  {@link #TemplateInfo template} is set
    44         *                                  to `false`.
    45         *
    46         *  @field(action)                  Flag indicating whether the file
    47         *                                  should be copied into the project or linked in.
    48         *                                  For example, the
    49         *                                  `{@link xdc.tools.product.trexgen trexgen}`
    50         *                                  tool recognizes the following flags:
    51         *                                  "COPY" - copy the file into the project
    52         *                                  "LINK" - link the file into the project
    53         */
    54        struct FileDesc {
    55            String path;                    /*! path to file */
    56            Bool   excludeFromBuild;        /*! exclude from build */
    57            Bool   openOnCreation;          /*! open on project creation */
    58            Bool   copyIntoConfiguration;   /*! copy into RTSC configuration */
    59            String action;                  /*! Flag indicating whether the file should be copied into the project or linked in */
    60        };
    61    
    62        /*!
    63         *  ======== Filter ========
    64         *  Structure defining filter properties for an example
    65         *
    66         *  This structure allows products to define constraints for their
    67         *  examples. IDEs use the `Filter` properties of an example
    68         *  to decide whether the example should be presented to the user.
    69         *  
    70         *  The filter is evaluated by performing an 'AND' operation
    71         *  on its individual elements. In other words, all the defined
    72         *  elements must evaluate to `true` for the filter to evaluate
    73         *  to `true`.
    74         *
    75         *  Each example typically defines an array of more than one filter;
    76         *  see {@link #TemplateInfo TemplateInfo.filterArr}. This filter array
    77         *  is evaluated using the 'OR' operation.  In other words, the example
    78         *  is presented to the user when any one of the filters evaluate
    79         *  to `true`.
    80         *
    81         *  Each filter property can be an arbitrary Java regular expression.
    82         *  In addition, each allows the user to define the NOT property
    83         *  by inserting a "~" character at the start of the string. For
    84         *  example, if the deviceFamily field is set to "~MSP430", the example
    85         *  will be displayed for all device families except "MSP430".
    86         *
    87         *  @field(deviceFamily)   String indicating the device family 
    88         *                         eg. "MSP430","C6000"
    89         *  @field(deviceVariant)  String indicating device variant
    90         *                         eg. "C674X", "CortexA8"
    91         *  @field(deviceId)       String indicating the device part number
    92         *                         eg. "TMS320C6747"
    93         *  @field(endianness)     String indicating the device endianness
    94         *                         eg. "little", "big"
    95         *  @field(toolChain)      String indicating the tool chain
    96         *                         eg. "TI", "GNU"
    97         *  @field(outputFormat)   String indicating the object file format
    98         *                         eg. "COFF", "ELF"
    99         */ 
   100        struct Filter {
   101            String deviceFamily; 
   102            String deviceVariant;
   103            String deviceId;    
   104            String endianness;
   105            String toolChain;
   106            String outputFormat;
   107        }; 
   108    
   109        /*!
   110         *  ======== TemplateInfo ========
   111         *  TemplateInfo structure
   112         *
   113         *  @field(title)             String containing the title of the template
   114         *  @field(name)              String containing the name of the project created from this
   115         *                            template
   116         *  @field(fileList)          Array of {@link #FileDesc} defining the
   117         *                            properties of the files contributed by this
   118         *                            example.
   119         *  @field(description)       String containing  description of example
   120         *  @field(target)            String containing RTSC target
   121         *  @field(platform)          String containing RTSC platform
   122         *  @field(buildProfile)      String containing RTSC build profile
   123         *  @field(linkerCommandFile) Linker command file for the example. If
   124         *                            this is set to the empty string then no
   125         *                            linker command file is added by the IDE
   126         *                            to the example. If this is not defined 
   127         *                            then the wizard picks the default
   128         *                            linker command file for the selected device. 
   129         *  @field(compilerBuildOptions) Special compiler options required to
   130         *                               build template. For example the template
   131         *                               may need special -I and -D options
   132         *                               to build and these may be specified
   133         *                               here.
   134         *  @field(linkerBuildOptions)   Special linker options to build template
   135         *  @field(requiredProducts)  Products required to build this
   136         *                            example. Products are  identified by
   137         *                            their globally unique 
   138         *                            {@link xdc.tools.product.IProduct#id} 
   139         *                            eg. 'com.ti.bios'. Dependency on a 
   140         *                            minimum version of a product may be
   141         *                            defined in the following manner
   142         *                            : <product-id>:<min-version>
   143         *  @field(xdcToolsVersion)   String containing XDCTools the exact version
   144         *                            required eg. '3.24.6.63'.  Note that this
   145         *                            number must be an 'eclipse' version number:
   146         *                            no leading 0's in the first three segments
   147         *                            and the forth is treated as an arbitrary
   148         *                            string.
   149         *
   150         *                            If this string is `undefined`, any
   151         *                            version of XDCtools will be allowed.
   152         *                            
   153         *                            If the exact version doesn't exist for some
   154         *                            reason, the project will still be
   155         *                            created, but the project will give a 'this
   156         *                            version of XDCtools doesn't exist' warning.
   157         *                            The user can then select a version that is
   158         *                            hopefully compatible.
   159         *                             
   160         *  @field(groups)            Array of strings referring example groups
   161         *                            that a particular example may
   162         *                            belong. Products may
   163         *                            provide examples that are part of an
   164         *                            existing example group eg."Empty Projects" 
   165         *                            that are defined elsewhere. The
   166         *                            groups are identified by an unique id.
   167         *  @field(configOnly)        Flag indicating to the IDE
   168         *                            whether example contributes only
   169         *                            to a RTSC configuration project.
   170         *  @field(configuroOptions)  This string contains options that are passed
   171         *                            to `xdc.tools.configuro`.  You must be
   172         *                            careful to quote embedded special characters
   173         *                            in this string in such a way that they can
   174         *                            be directly embedded in an XML file.  For
   175         *                            example, to pass '-foo "bar"' to `configuro`
   176         *                            you must use the string
   177         *                            '-foo &quot;bar&quot;'.
   178         *
   179         *  @field(isHybrid)          Flag indicating to the IDE 
   180         *                            whether example contains RTSC 
   181         *                            configuration  and target 
   182         *                            content files in one project.
   183         *                            If this field is set to `true` 
   184         *                            then the IDE consuming this example will 
   185         *                            create one project with all the
   186         *                            files. Otherwise multiple projects will 
   187         *                            be created - one containing the
   188         *                            target content and the other containing 
   189         *                            the RTSC configuration files. This flag
   190         *                            is applies only when `configOnly`
   191         *                            flag is set to `false`.
   192         *  @field(filterArr)         Array of {@link #Filter}. Used to specify
   193         *                            the constraints for a particular
   194         *                            example. The filter array is evaluated using
   195         *                            an OR operation on the individual array
   196         *                            elements. Note that individual elements 
   197         *                            within a {@link #Filter filter} is evaluated
   198         *                            with the 'AND' operation. 
   199         *
   200         *  @field(options)           Comma separated list of options used to
   201         *                            specify various configurable items for this
   202         *                            template.  For example, the
   203         *                            `{@link xdc.tools.product.trexgen trexgen}` 
   204         *                            tool recognizes the following flags:
   205         *                                "NPW" - display this example in the New
   206         *                                        Project Wizard, and
   207         *                                "TREX" - display this example in the
   208         *                                         Resource Explorer
   209         *
   210         *  @field(references)        Comma separated list of referenced project
   211         *                            names
   212         *
   213         *  @field(buildCommandFlags) Comma separated list of build-command flags.
   214         *
   215         *  @field(launchWizard)      Flag indicating to launch the New Project
   216         *                            wizard allowing the user to adjust the
   217         *                            details.
   218         *
   219         *  @field(preBuildStep)      Shell cmd to run before the build. Cmd is
   220         *                            run within the debug/release directory
   221         *
   222         *  @field(postBuildStep)     Shell cmd to run after the build. Cmd is run
   223         *                            within the debug/release directory
   224         */
   225        struct TemplateInfo {
   226            String   title;              /*! Title of this example */
   227            String   name;               /*! Name of the project imported from
   228                                          *  this template
   229                                          */
   230            FileDesc fileList[];         /*! List of files along with properties 
   231                                          *  for this example
   232                                          */
   233            String   description;        /*! Description of this example */
   234            String   target;             /*! RTSC target */
   235            String   platform;           /*! RTSC platform */
   236            String   buildProfile;       /*! RTSC build profile */
   237            String   linkerCommandFile;  /*! Linker file for this example */
   238            String   compilerBuildOptions; /*! Special compiler options */
   239            String   linkerBuildOptions; /*! Special linker options */
   240            String   requiredProducts[]; /*! List of products required to build
   241                                          *  this example
   242                                          */
   243            String   xdcToolsVersion;    /*! Version of xdctools this template
   244                                          *  requires eg. '3.24.6.63' */
   245            String   groups[];           /*! Array of group ids for groups
   246                                          * containing this example */ 
   247            Bool     legacyTcf;          /* obsolete option */
   248            String   configuroOptions;   /*! configuro options */
   249            Bool     configOnly;         /*! Indicates whether only a RTSC
   250                                          *  configuration project should
   251                                          *  be created for this example.
   252                                          */
   253            Bool     isHybrid;           /*! Indicates whether application and
   254                                          * configuration content exists in
   255                                          * one project
   256                                          */ 
   257            Filter   filterArr[];        /*! Array of filters for this example */
   258            String   options;            /*! Comma separated attributes */
   259            String   references;         /*! Comma separated list of referenced
   260                                          * project names */
   261            String   buildCommandFlags;  /*! Comma seperated list of build-command
   262                                          * flags */
   263            Bool     launchWizard;       /*! Flag indicating to launch the New
   264                                          * Project Wizard allowing the user to
   265                                          * adjust the details */
   266            String   preBuildStep;       /*! Shell cmd to run before the build.
   267                                          * Cmd is run within the debug/release
   268                                          * directory */
   269            String   postBuildStep;      /*! Shell cmd to run after the build. Cmd
   270                                          * is run within the debug/release
   271                                          * directory */
   272        };
   273    
   274        /*!
   275         *  ======== TemplateGroup ========
   276         *  TemplateGroup structure
   277         *
   278         *  This structure may be used to define a hierarchy of examples
   279         *  for the product.  Examples may be logically organized into groups 
   280         *  with an unique `id` and may specify membership of other groups
   281         *  by referring to their ids in the `groups` array. In this manner 
   282         *  the example producer can define a tree topology of examples for 
   283         *  their product.  Once the template groups are defined, the  
   284         *  individual examples may specify their membership within a template
   285         *  group in the `groups` array of {@link #TemplateInfo}.  The example
   286         *  provider may specify all the defined groups for their product in 
   287         *  {@link #templateGroupArr}.
   288         *
   289         *  @field(id) Unique id for the template group
   290         *  @field(name) Name of the group
   291         *  @field(description) Description of the group
   292         *  @field(groups) Array of group ids used to specify
   293         *                 membership of other groups.
   294         */ 
   295        struct TemplateGroup {
   296            String id;
   297            String name;
   298            String description;
   299            String groups[];
   300        }; 
   301        
   302        /*!
   303         *  ======== templateArr ========
   304         *  Examples contained in the product
   305         */ 
   306        config TemplateInfo templateArr[];
   307    
   308        /*!
   309         *  ======== templateGroupArr ========
   310         *  Array of template group ids
   311         *
   312         *  This array may be optionally specified by Products that
   313         *  organize their examples into groups. 
   314         */
   315        config TemplateGroup templateGroupArr[] = [];
   316    }
   317    /*
   318     *  @(#) xdc.tools.product; 1, 0, 0,91; 7-9-2013 12:07:38; /db/ztree/library/trees/xdctools/xdctools-f32x/src/
   319     */
   320