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