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 version required eg. '3.22.1.1_eng'
   143         *  @field(groups)            Array of strings referring example groups
   144         *                            that a particular example may
   145         *                            belong. Products may
   146         *                            provide examples that are part of an
   147         *                            existing example group eg."Empty Projects" 
   148         *                            that are defined elsewhere. The
   149         *                            groups are identified by an unique id.
   150         *  @field(configOnly)        Flag indicating to the IDE
   151         *                            whether example contributes only
   152         *                            to a RTSC configuration project.
   153         *  @field(configuroOptions)  This string contains options that are passed
   154         *                            to `xdc.tools.configuro`.  You must be
   155         *                            careful to quote embedded special characters
   156         *                            in this string in such a way that they can
   157         *                            be directly embedded in an XML file.  For
   158         *                            example, to pass '-foo "bar"' to `configuro`
   159         *                            you must use the string
   160         *                            '-foo &quot;bar&quot;'.
   161         *
   162         *  @field(isHybrid)          Flag indicating to the IDE 
   163         *                            whether example contains RTSC 
   164         *                            configuration  and target 
   165         *                            content files in one project.
   166         *                            If this field is set to `true` 
   167         *                            then the IDE consuming this example will 
   168         *                            create one project with all the
   169         *                            files. Otherwise multiple projects will 
   170         *                            be created - one containing the
   171         *                            target content and the other containing 
   172         *                            the RTSC configuration files. This flag
   173         *                            is applies only when `configOnly`
   174         *                            flag is set to `false`.
   175         *  @field(filterArr)         Array of {@link #Filter}. Used to specify
   176         *                            the constraints for a particular
   177         *                            example. The filter array is evaluated using
   178         *                            an OR operation on the individual array
   179         *                            elements. Note that individual elements 
   180         *                            within a {@link #Filter filter} is evaluated
   181         *                            with the 'AND' operation. 
   182         *
   183         *  @field(options)           Comma separated list of options used to
   184         *                            specify various configurable items for this
   185         *                            template.  For example, the
   186         *                            `{@link xdc.tools.product.trexgen trexgen}` 
   187         *                            tool recognizes the following flags:
   188         *                                "NPW" - display this example in the New
   189         *                                        Project Wizard, and
   190         *                                "TREX" - display this example in the
   191         *                                         Resource Explorer
   192         *
   193         *  @field(references)        Comma separated list of referenced project names
   194         *
   195         *  @field(buildCommandFlags) Comma separated list of build-command flags.
   196         *
   197         *  @field(launchWizard)      Flag indicating to launch the New Project wizard allowing the user to adjust the details.
   198         *
   199         *  @field(preBuildStep)      Shell cmd to run before the build. Cmd is run within the debug/release directory
   200         *
   201         *  @field(postBuildStep)     Shell cmd to run after the build. Cmd is run within the debug/release directory
   202         *
   203         *
   204         */
   205        struct TemplateInfo {
   206            String   title;              /*! Title of this example */
   207            String   name;               /*! Name of the project imported from this template */
   208            FileDesc fileList[];         /*! List of files along with properties 
   209                                          *  for this example
   210                                          */
   211            String   description;        /*! Description of this example */
   212            String   target;             /*! RTSC target */
   213            String   platform;           /*! RTSC platform */
   214            String   buildProfile;       /*! RTSC build profile */
   215            String   linkerCommandFile;  /*! Linker command file for this example */
   216            String   compilerBuildOptions; /*! Special compiler options for this example */
   217            String   linkerBuildOptions; /*! Special linker options for this example */
   218            String   requiredProducts[]; /*! List of products required to build
   219                                          *  this example
   220                                          */
   221            String   xdcToolsVersion;    /*! Version of xdctools this template requires eg. '3.22.1.1_eng' */
   222            String   groups[];           /*! Array of group ids for groups
   223                                          * containing this example */ 
   224            Bool     legacyTcf;          /* obsolete option */
   225            String   configuroOptions;   /*! configuro options */
   226            Bool     configOnly;         /*! Indicates whether only a RTSC
   227                                          *  configuration project should
   228                                          *  be created for this example.
   229                                          */
   230            Bool     isHybrid;           /*! Indicates whether application and
   231                                          * configuration content exists in
   232                                          * one project
   233                                          */ 
   234            Filter   filterArr[];        /*! Array of filters for this example */
   235            String   options;            /*! Comma separated attributes for the example */
   236            String   references;         /*! Comma seperated list of referenced project names */
   237            String   buildCommandFlags;  /*! Comma seperated list of build-command flags */
   238            Bool     launchWizard;       /*! Flag indicating to launch the New Project Wizard allowing the user to adjust the details */
   239            String   preBuildStep;       /*! Shell cmd to run before the build. Cmd is run within the debug/release directory */
   240            String   postBuildStep;      /*! Shell cmd to run after the build. Cmd is run within the debug/release directory */
   241        };
   242    
   243        /*!
   244         *  ======== TemplateGroup ========
   245         *  TemplateGroup structure
   246         *
   247         *  This structure may be used to define a hierarchy of examples
   248         *  for the product.  Examples may be logically organized into groups 
   249         *  with an unique `id` and may specify membership of other groups
   250         *  by referring to their ids in the `groups` array. In this manner 
   251         *  the example producer can define a tree topology of examples for 
   252         *  their product.  Once the template groups are defined, the  
   253         *  individual examples may specify their membership within a template
   254         *  group in the `groups` array of {@link #TemplateInfo}.  The example
   255         *  provider may specify all the defined groups for their product in 
   256         *  {@link #templateGroupArr}.
   257         *
   258         *  @field(id) Unique id for the template group
   259         *  @field(name) Name of the group
   260         *  @field(description) Description of the group
   261         *  @field(groups) Array of group ids used to specify
   262         *                 membership of other groups.
   263         * 
   264         */ 
   265        struct TemplateGroup {
   266            String id;
   267            String name;
   268            String description;
   269            String groups[];
   270        }; 
   271        
   272        /*!
   273         *  ======== templateArr ========
   274         *  Examples contained in the product
   275         */ 
   276        config TemplateInfo templateArr[];
   277    
   278        /*!
   279         *  ======== templateGroupArr ========
   280         *  Array of template group ids
   281         *
   282         *  This array may be optionally specified by Products that
   283         *  organize their examples into groups. 
   284         */
   285        config TemplateGroup templateGroupArr[] = [];
   286    }
   287    /*
   288     *  @(#) xdc.tools.product; 1, 0, 0,80; 3-2-2013 08:51:33; /db/ztree/library/trees/xdctools/xdctools-f21x/src/
   289     */
   290