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 template
   115         *  @field(fileList)          Array of {@link #FileDesc} defining the
   116         *                            properties of the files contributed by this
   117         *                            example.
   118         *  @field(description)       String containing  description of example
   119         *  @field(target)            String containing RTSC target
   120         *  @field(platform)          String containing RTSC platform
   121         *  @field(buildProfile)      String containing RTSC build profile
   122         *  @field(linkerCommandFile) Linker command file for the example. If
   123         *                            this is set to the empty string then no
   124         *                            linker command file is added by the IDE
   125         *                            to the example. If this is not defined 
   126         *                            then the wizard picks the default
   127         *                            linker command file for the selected device. 
   128         *  @field(compilerBuildOptions) Special compiler options required to
   129         *                               build template. For example the template
   130         *                               may need special -I and -D options
   131         *                               to build and these may be specified
   132         *                               here.
   133         *  @field(linkerBuildOptions)   Special linker options to build template
   134         *  @field(requiredProducts)  Products required to build this
   135         *                            example. Products are  identified by
   136         *                            their globally unique 
   137         *                            {@link xdc.tools.product.IProduct#id} 
   138         *                            eg. 'com.ti.bios'. Dependency on a 
   139         *                            minimum version of a product may be
   140         *                            defined in the following manner
   141         *                            : <product-id>:<min-version>
   142         *  @field(xdcToolsVersion)   String containing XDCTools the exact version
   143         *                            required eg. '3.24.6.63'.  Note that this
   144         *                            number must be an 'eclipse' version number:
   145         *                            no leading 0's in the first three segments
   146         *                            and the forth is treated as an arbitrary
   147         *                            string.
   148         *
   149         *                            If this string is `undefined`, any
   150         *                            version of XDCtools will be allowed.
   151         *                            
   152         *                            If the exact version doesn't exist for some
   153         *                            reason, the project will still be
   154         *                            created, but the project will give a 'this
   155         *                            version of XDCtools doesn't exist' warning.
   156         *                            The user can then select a version that is
   157         *                            hopefully compatible.
   158         *                             
   159         *  @field(groups)            Array of strings referring example groups
   160         *                            that a particular example may
   161         *                            belong. Products may
   162         *                            provide examples that are part of an
   163         *                            existing example group eg."Empty Projects" 
   164         *                            that are defined elsewhere. The
   165         *                            groups are identified by an unique id.
   166         *  @field(configOnly)        Flag indicating to the IDE
   167         *                            whether example contributes only
   168         *                            to a RTSC configuration project.
   169         *  @field(configuroOptions)  This string contains options that are passed
   170         *                            to `xdc.tools.configuro`.  You must be
   171         *                            careful to quote embedded special characters
   172         *                            in this string in such a way that they can
   173         *                            be directly embedded in an XML file.  For
   174         *                            example, to pass '-foo "bar"' to `configuro`
   175         *                            you must use the string
   176         *                            '-foo &quot;bar&quot;'.
   177         *
   178         *  @field(isHybrid)          Flag indicating to the IDE 
   179         *                            whether example contains RTSC 
   180         *                            configuration  and target 
   181         *                            content files in one project.
   182         *                            If this field is set to `true` 
   183         *                            then the IDE consuming this example will 
   184         *                            create one project with all the
   185         *                            files. Otherwise multiple projects will 
   186         *                            be created - one containing the
   187         *                            target content and the other containing 
   188         *                            the RTSC configuration files. This flag
   189         *                            is applies only when `configOnly`
   190         *                            flag is set to `false`.
   191         *  @field(filterArr)         Array of {@link #Filter}. Used to specify
   192         *                            the constraints for a particular
   193         *                            example. The filter array is evaluated using
   194         *                            an OR operation on the individual array
   195         *                            elements. Note that individual elements 
   196         *                            within a {@link #Filter filter} is evaluated
   197         *                            with the 'AND' operation. 
   198         *
   199         *  @field(options)           Comma separated list of options used to
   200         *                            specify various configurable items for this
   201         *                            template.  For example, the
   202         *                            `{@link xdc.tools.product.trexgen trexgen}` 
   203         *                            tool recognizes the following flags:
   204         *                                "NPW" - display this example in the New
   205         *                                        Project Wizard, and
   206         *                                "TREX" - display this example in the
   207         *                                         Resource Explorer
   208         *
   209         *  @field(references)        Comma separated list of referenced project
   210         *                            names
   211         *
   212         *  @field(buildCommandFlags) Comma separated list of build-command flags.
   213         *
   214         *  @field(launchWizard)      Flag indicating to launch the New Project
   215         *                            wizard allowing the user to adjust the
   216         *                            details.
   217         *
   218         *  @field(preBuildStep)      Shell cmd to run before the build. Cmd is
   219         *                            run within the debug/release directory
   220         *
   221         *  @field(postBuildStep)     Shell cmd to run after the build. Cmd is run
   222         *                            within the debug/release directory
   223         */
   224        struct TemplateInfo {
   225            String   title;              /*! Title of this example */
   226            String   name;               /*! Name of the project imported from
   227                                          * this template */
   228            FileDesc fileList[];         /*! List of files along with properties 
   229                                          *  for this example
   230                                          */
   231            String   description;        /*! Description of this example */
   232            String   target;             /*! RTSC target */
   233            String   platform;           /*! RTSC platform */
   234            String   buildProfile;       /*! RTSC build profile */
   235            String   linkerCommandFile;  /*! Linker file for this example */
   236            String   compilerBuildOptions; /*! Special compiler options */
   237            String   linkerBuildOptions; /*! Special linker options */
   238            String   requiredProducts[]; /*! List of products required to build
   239                                          *  this example
   240                                          */
   241            String   xdcToolsVersion;    /*! Version of xdctools this template
   242                                          *  requires eg. '3.24.6.63' */
   243            String   groups[];           /*! Array of group ids for groups
   244                                          * containing this example */ 
   245            Bool     legacyTcf;          /* obsolete option */
   246            String   configuroOptions;   /*! configuro options */
   247            Bool     configOnly;         /*! Indicates whether only a RTSC
   248                                          *  configuration project should
   249                                          *  be created for this example.
   250                                          */
   251            Bool     isHybrid;           /*! Indicates whether application and
   252                                          * configuration content exists in
   253                                          * one project
   254                                          */ 
   255            Filter   filterArr[];        /*! Array of filters for this example */
   256            String   options;            /*! Comma separated attributes */
   257            String   references;         /*! Comma separated list of referenced
   258                                          * project names */
   259            String   buildCommandFlags;  /*! Comma seperated list of build-command
   260                                          * flags */
   261            Bool     launchWizard;       /*! Flag indicating to launch the New
   262                                          * Project Wizard allowing the user to
   263                                          * adjust the details */
   264            String   preBuildStep;       /*! Shell cmd to run before the build.
   265                                          * Cmd is run within the debug/release
   266                                          * directory */
   267            String   postBuildStep;      /*! Shell cmd to run after the build. Cmd
   268                                          * is run within the debug/release
   269                                          * directory */
   270        };
   271    
   272        /*!
   273         *  ======== TemplateGroup ========
   274         *  TemplateGroup structure
   275         *
   276         *  This structure may be used to define a hierarchy of examples
   277         *  for the product.  Examples may be logically organized into groups 
   278         *  with an unique `id` and may specify membership of other groups
   279         *  by referring to their ids in the `groups` array. In this manner 
   280         *  the example producer can define a tree topology of examples for 
   281         *  their product.  Once the template groups are defined, the  
   282         *  individual examples may specify their membership within a template
   283         *  group in the `groups` array of {@link #TemplateInfo}.  The example
   284         *  provider may specify all the defined groups for their product in 
   285         *  {@link #templateGroupArr}.
   286         *
   287         *  @field(id) Unique id for the template group
   288         *  @field(name) Name of the group
   289         *  @field(description) Description of the group
   290         *  @field(groups) Array of group ids used to specify
   291         *                 membership of other groups.
   292         */ 
   293        struct TemplateGroup {
   294            String id;
   295            String name;
   296            String description;
   297            String groups[];
   298        }; 
   299        
   300        /*!
   301         *  ======== templateArr ========
   302         *  Examples contained in the product
   303         */ 
   304        config TemplateInfo templateArr[];
   305    
   306        /*!
   307         *  ======== templateGroupArr ========
   308         *  Array of template group ids
   309         *
   310         *  This array may be optionally specified by Products that
   311         *  organize their examples into groups. 
   312         */
   313        config TemplateGroup templateGroupArr[] = [];
   314    }
   315    /*
   316     *  @(#) xdc.tools.product; 1, 0, 0,87; 5-23-2013 16:33:09; /db/ztree/library/trees/xdctools/xdctools-f28x/src/
   317     */
   318