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