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    
    13    /*
    14     *  ======== Executable.xdc ========
    15     */
    16    package xdc.bld;
    17    
    18    /*!
    19     *  ======== Executable ========
    20     *  Model of a file that can be loaded and executed on a platform.
    21     *
    22     *  Executable instances represent executable files.  Instances must be
    23     *  created via the `{@link xdc.bld.PackageContents#addExecutable()}`
    24     *  function; this ensures that each executable created appears in the
    25     *  package's manifest and that it properly "inherits" appropriate default
    26     *  attributes from the containing package.
    27     */
    28    metaonly module Executable {
    29        
    30        /*!
    31         *  ======== Attrs ========
    32         *  Optional attributes for an Executable instance.
    33         *
    34         *  Unspecified attributes are "inherited" from
    35         *  `{@link xdc.bld.PackageContents#attrs}`;
    36         *  i.e., if one of fields in this structure is unspecified *and* this
    37         *  field's name matches a field name in
    38         *  `{@link xdc.bld.PackageContents#attrs}`, then this field's value
    39         *  defaults to the value in specified by
    40         *  `{@link xdc.bld.PackageContents#attrs}`.  This mechanism makes it
    41         *  possible to establish package-wide default values for any of the
    42         *  "inherited" attributes.
    43         *
    44         *  Suppose, for example, that you want all executable files in this
    45         *  package to be built with the 'release' profile, but one particular file
    46         *  must be built with 'debug' (because it is a source example).  The
    47         *  following build script fragment shows how this can be accomplished:
    48         *  @p(code)
    49         *      Pkg.attrs.profile = 'release';
    50         *      var exe = Pkg.addExecutable('example', ..., {profile: 'debug'});
    51         *  @p
    52         *  @field(cfgArgs) This string may contain any expression that can be
    53         *          assigned to a JavaScript property.  It is evaluated in
    54         *          the configuration domain after the platform package is
    55         *          imported and just prior to running the executable's
    56         *          configuration script.  Its value (after evaluation) is
    57         *          assigned to `Program.build.cfgArgs`; so, program
    58         *          configuration scripts can use this property to adjust their
    59         *          behavior based on values specified in a build script.
    60         *
    61         *          For example, a package's build script might build an
    62         *          executable for each possible level of a "trace" value:
    63         *          @p(code)
    64         *              for (t = 0; t < NUM_TRACE_LEVELS; t++) {
    65         *                      :
    66         *                  Pkg.addExecutable("myExe" + t, targ, plat, {
    67         *                      cfgArgs:   "{traceLevel: " + t + "}",
    68         *                      cfgScript: "myExe.cfg"
    69         *                  });
    70         *              }
    71         *          @p
    72         *
    73         *          In this case, the configuration script `myExe.cfg` can
    74         *          reference the "trace level" set in the build script by
    75         *          referencing the `Program.build.cfgArgs` object directly:
    76         *          @p(code)
    77         *              if (Program.build.cfgArgs.traceLevel == 1) {
    78         *                  :
    79         *              }
    80         *          @p
    81         *
    82         *  @field(cfgArgsEncoded) This boolean flag indicates whether the
    83         *  string `cfgArgs` should be treated as an encoded string (via ECMA-262
    84         *  `escape()`) or not.  If this field is `true`, the string is treated
    85         *  as an encoded string and is decoded via `unescape()` prior to
    86         *  interpretation.
    87         *
    88         *  @field(incs)  This string contains include path options used by
    89         *          the compiler (or assembler) to locate include files; e.g.,
    90         *          "-I ../../include -I ../c55xx".  Note that the syntax of 
    91         *          this string may be target dependent.
    92         *
    93         *  @field(defs)  This string contains options used by the
    94         *          compiler (or assembler) to define macros; e.g.,
    95         *          "-D_C6xxx -DDEBUG=1".  Note that the syntax of 
    96         *          this string may be target dependent.
    97         *
    98         *  @field(aopts)  This string contains options used by the assembler
    99         *          to produce object files; e.g., "-mP1".  Note that the syntax
   100         *          of this string may be target dependent.
   101         *
   102         *  @field(copts)  This string contains options used by the C/C++
   103         *          compiler to produce object files; e.g., "-o3 -mi1".  Note
   104         *          that the syntax of this string may be target dependent.
   105         *
   106         *  @field(cfgcopts)  This string contains options used by the C/C++
   107         *          compiler to compile the generated C config file. If `cfgcopts`
   108         *          is not specified, either explicitly or through
   109         *          `Pkg.attrs.cfgcopts`, the options specified in `copts` are
   110         *          used instead. 
   111         *
   112         *  @field(lopts)  This string contains options used by the linker
   113         *          produce object files; e.g., "-l mylib.lib".  Note
   114         *          that the syntax of this string may be target dependent.
   115         *
   116         *  @field(xsopts)  This string contains options passed to the
   117         *          `{@link http://rtsc.eclipse.org/docs-tip/Command_-_xs xs}`
   118         *          command that's used to run configuration scripts.  This option
   119         *          can be used, for example, to define name-value pairs accessible
   120         *          to configuration scripts via the XDCscript global
   121         *          `environment` hash-table.  For example, setting `xsopts` to
   122         *          `"-DFOO=bar"` enables the configuration script to get the
   123         *          value of `FOO` via the expression `environment["FOO"]`.  For
   124         *          more information about XDCscript and `environment` see
   125         *          {@link http://rtsc.eclipse.org/docs-tip/The_XDCscript_Language The XDCscript Language}.
   126         *
   127         *  @field(cfgHome)  This string names the package that is bound to
   128         *          the Configuration Model's `$homepkg`.  This home package
   129         *          is automatically loaded as part of configuration and, as
   130         *          a result, may contribute libraries to the configuration.
   131         *
   132         *          If this parameter is not specified, the package containing
   133         *          the configuration script is used as the home package.  This
   134         *          ensures that the results of a configuration script are
   135         *          independent of the package building the configuration.  In
   136         *          most cases, the build package is the package containing the
   137         *          configuration script and this distinction is not important.
   138         *          But there are times when it is important to control the home
   139         *          package; e.g., when an external tool generates a
   140         *          configuration script from information supplied by another
   141         *          package or when a configuration script in not in any package.
   142         *
   143         *  @field(cfgScript)  This string names the program configuration
   144         *          script used to create the files necessary to create the
   145         *          executable.  If `cfgScript` is not specified, the configuration
   146         *          script is assumed to be `<name>.cfg`, where `<name>` is the
   147         *          base name of the executable.  If `cfgScript` is set to `null`,
   148         *          the executable is assumed to be a "legacy" application that
   149         *          defines `main()` directly and does not require any
   150         *          `{@link xdc.runtime}` support.
   151         *
   152         *          If this string is set to a non-`null` value, and does not have
   153         *          an extension, then the extension `".cfg"` is automatically
   154         *          added.
   155         *
   156         *          If the specified configuration file does not exist in the
   157         *          package where the executable is being built and
   158         *          the name does not begin with `"./"`, it is searched 
   159         *          for along the package path.  Thus, it is possible to use
   160         *          configuration scripts in other packages to build executables;
   161         *          e.g., to use the configuration script "myExe.cfg" from a
   162         *          `ti.bios.examples.hello` package, `cfgScript` should be set
   163         *          to `"ti/bios/examples/hello/myExe.cfg"`.
   164         *
   165         *          The package containing the specified configuration script is 
   166         *          imported prior to running the configuration script and this
   167         *          package is used to set `xdc.$homepkg`; thus, configuration
   168         *          scripts that use `xdc.$homepkg` will configure the same
   169         *          executable independent of the package building the executable.
   170         *
   171         *  @field(profile)  This string names a profile defined by the
   172         *          executable's target.  The profile specifies a set of compiler,
   173         *          linker, and archiver options that are to be used when 
   174         *          producing the executable.  Note that these tool options are
   175         *          in addition to any options specified via `aopts`, `copts`,
   176         *          etc.
   177         *
   178         *          If this field is not set or set to `null`, the value of
   179         *          `{@link xdc.bld.PackageContents#attrs.profile}` is used.  If
   180         *          `{@link xdc.bld.PackageContents#attrs.profile}` is not
   181         *          specified or equal to `null`, the `"release"` profile is used.
   182         *
   183         *  @field(cpuId)  This string is used to uniquely identify the
   184         *          particular CPU on a platform that will run the executable; on
   185         *          platforms that contain a single CPU, this string is ignored.
   186         *
   187         *  @field(rtsName)  This string names a package that contributes a
   188         *          compiled form of the `{@link xdc.runtime}` runtime support
   189         *          modules.
   190         *
   191         *          This package is implicitly loaded prior to running the
   192         *          executable's configuration script.  If this field is set to
   193         *          `null`, no package will be pre-loaded.  If this field is not
   194         *          set (or set to `undefined`), the package specified by this
   195         *          executable's target will be used (see
   196         *          {@link xdc.bld.ITarget#rts}) .
   197         *
   198         *  @field(cpuArgs)  This field is a hash-table of name-value pairs
   199         *          interpreted by the CPU as register settings that exist at the
   200         *          time that the executable is loaded; e.g., it is possible to
   201         *          specify a non-reset value for the `PMST` register on a C54xx
   202         *          CPU by setting this parameter to `{PMST: 0xffff}`.
   203         *
   204         *  @field(exportCfg)  If this field is set to true, the configuration
   205         *          script will be part of the releases named in the releases
   206         *          array.  If it is unspecified (or set to `null`) and the
   207         *          release specifies that configurations are to be exported,
   208         *          the configuration script will be part of the release.  In
   209         *          all other cases, the configuration is not part of the
   210         *          release.
   211         *
   212         *  @field(exportSrc)  If this field is set to true, the sources
   213         *          specified via `{@link xdc.bld.Executable#addObjects()}`
   214         *          will be part of the releases named in the releases
   215         *          array.  If it is unspecified (or set to `null`) and the
   216         *          release specifies that sources are to be exported,
   217         *          the sources will be part of the release.  In
   218         *          all other cases, the sources are not added to the
   219         *          release.
   220         *
   221         *  @field(exportExe)  If this field is set to true, the executable
   222         *          will be part of the releases named in the releases
   223         *          array.  If it is unspecified (or set to `null`) and the
   224         *          release specifies that configurations are to be exported,
   225         *          the executable will be part of the release.  In
   226         *          all other cases, the executable is not part of the
   227         *          release.
   228         *
   229         *  @field(releases)  This array contains releases that will contain the
   230         *          executable.  Thus, a single executable can be part of any set 
   231         *          of releases.  Each executable is always added to the 
   232         *          package's "default release" in addition to any releases
   233         *          specified in the releases array.
   234         *
   235         *  @field(test) If this field is set, it defines default attributes for
   236         *          tests added to this executable, including the implicitly
   237         *          added test (see {@link xdc.bld.PackageContents#addExecutable}).
   238         *
   239         *  @field(linkTemplate) If this field is set, it defines the linker 
   240         *          command file template to be used to link this executable.  
   241         *          This specification may, however, be overridden by the
   242         *          configuration script (see
   243         *          {@link xdc.cfg.Program#linkTemplate}).
   244         *
   245         *          As with configuration scripts, if the specified file does not
   246         *          exist in the package where the executable is being built and
   247         *          the name does not begin with `"./"`, it is searched for along
   248         *          the package path.  Thus, it is possible to use templates in
   249         *          other packages to build executables; e.g., to use the linker
   250         *          command file "`myExe.cmd`" from the `ti.bios.examples.hello`
   251         *          package, `linkTemplate` should be set to
   252         *          `"ti/bios/examples/hello/myExe.cmd"`.
   253         *
   254         *  @see #attrs
   255         *  @see xdc.bld.PackageContents#Attrs
   256         */
   257        struct Attrs {
   258            String  profile;        /*! target options profile */
   259            String  aopts;          /*! asm options for objs added to this exe */
   260            String  copts;          /*! C/C++ options for objs added to this exe */
   261            String  cfgcopts;       /*! C/C++ options for the C config file */
   262            String  defs;           /*! definitions for objs added to this exe */
   263            String  incs;           /*! include opts for objs added to this exe */
   264            String  lopts;          /*! linker options for this exe */
   265            String  xsopts;         /*! `xs` options for this exe */
   266            String  cpuId;          /*! optional id of CPU on platform */
   267            String  rtsName;        /*! optional run time support package name */
   268            any     cpuArgs;        /*! optional register settings */
   269            String  sharedCfg;
   270            String  cfgScript;      /*! optional name of config script */
   271            String  cfgHome;        /*! optional home package of config model */
   272            String  cfgArgs;        /*! optional arguments passed to cfgScript */
   273            Bool    cfgArgsEncoded; /*! if true, cfgArgs is encoded via escape() */
   274            Bool    exportExe;      /*! export executable's exe file? */
   275            Bool    exportCfg;      /*! export executable's config script? */
   276            Bool    exportSrc;      /*! if true, export exe sources to releases */
   277            Release.Instance releases[]; /*! releases that this exe is a part of */
   278            Test.Attrs  test;       /*! test attrs for tests added to this exe */
   279            String  linkTemplate;   /*! linker command file template for this exe*/
   280        };
   281    
   282    instance:
   283        /*!
   284         *  ======== create ========
   285         *  @_nodoc
   286         *  Instances should only be created via PackageContents.addExecutable()
   287         */
   288        create();
   289    
   290        /*!
   291         *  ======== name ========
   292         *  Base name of the executable.
   293         *
   294         *  This name is used to construct the final executable file name as
   295         *  follows:
   296         *  @p(code)
   297         *      <name>.x<target_suffix>
   298         *  @p
   299         *  where `<name>` is name and `<target_suffix>` is the suffix defined 
   300         *  by each target that the file is built for. See NOTE in 
   301         * `{@link xdc.bld}` for filename rules.
   302         *
   303         *  Note: if the same executable is to be built for different platforms
   304         *  (having the same target), then name must "encode" the platform's
   305         *  name.
   306         */
   307        config String name;
   308    
   309        /*!
   310         *  ======== platform ========
   311         *  The name of the platform that will run this executable.
   312         *
   313         *  Platforms are modeled as packages that have a module called
   314         *  "Platform"; thus the platform name is really a package name.
   315         */
   316        config String platform;
   317    
   318        /*!
   319         *  ======== target ========
   320         *  The target (on a platform) that executable should be built for.
   321         *
   322         *  This parameter is used to determine the target to use for any
   323         *  objects added to the executable.
   324         *
   325         *  During configuration, the executable's platform package can
   326         *  validate that the target is compatible with the configuration of
   327         *  the platform; the target object is accessible via the expression
   328         *  `Program.build.target`.
   329         */
   330        config ITarget.Module target;
   331    
   332        /*!
   333         *  ======== attrs ========
   334         *  This executable's optional attributes.
   335         *
   336         *  These attributes are "inherited" by all objects added to this
   337         *  executable; i.e., any object attribute that is undefined but is
   338         *  defined here will be assigned the value from these attributes.
   339         *
   340         *  Similarly, any unspecified attributes that also appear in
   341         *  `{@link xdc.bld.PackageContents#Attrs}` are inherited from
   342         *  `{@link xdc.bld.PackageContents#attrs}`.
   343         *
   344         *  @see xdc.bld.PackageContents#Attrs
   345         */
   346        config Executable.Attrs attrs;
   347    
   348        /*!
   349         *  ======== addObjects ========
   350         *  Add specified object to be built and linked into this executable.
   351         *
   352         *  All objects added to the executable are built with the symbol
   353         *  `xdc_cfg__header__` defined to be the name of the executable-specific
   354         *  C header generated by the program configuration tool.  This symbol
   355         *  is used by the `xdc/cfg/global.h` header to include the generated
   356         *  header file; see `{@link xdc.cfg.Program#global}`.  Thus, it is
   357         *  possible to portably include configuration specific definitions in a
   358         *  source file that is used in many different configurations.
   359         *
   360         *  For example, a portable `main.c` might be structured as follows:
   361         *  @p(code)
   362         *      #include <xdc/std.h>
   363         *      #include <ti/bios/include/log.h>
   364         *
   365         *      #include <xdc/cfg/global.h>    // include declaration of trace
   366         *      
   367         *      int main(int argc, char *argv[])
   368         *      {
   369         *          LOG_printf(trace, "hello world");
   370         *              :
   371         *      }
   372         *  @p
   373         *
   374         *  @a(Examples)
   375         *
   376         *      1. Locate a source file whose name starts with "hello" with
   377         *      an extension supported by the executable's target, compile it
   378         *      and link it into the executable `myExe`:
   379         *      @p(code)
   380         *          myExe.addObjects(["hello"]);
   381         *      @p
   382         *      If hello.c exists, compile and add to `myExe`, if hello.asm exists
   383         *      assemble and add to `myExe`, etc.  If no such file is located,
   384         *      a warning is emitted.
   385         *
   386         *      2. Compile hello.c and add to the executable `myExe`:
   387         *      @p(code)
   388         *          myExe.addObjects(["hello.c"]);
   389         *      @p
   390         *      3. Names may include sub-directory prefixes.  In this case, the
   391         *      source will be located in a sub-directory of the current
   392         *      package.  The following statement declares that the file
   393         *      "`foo/hello.c`" should be compiled and linked into the executable
   394         *      `myExe`:
   395         *      @p(code)
   396         *          myExe.addObjects(["foo/hello.c"]);
   397         *      @p
   398         *      As in the previous examples, the extension ".c" is optional. 
   399         *      In case an extension is not supplied, each extension
   400         *      understood by the target will be tried until a source file
   401         *      is located.
   402         *
   403         *      4. It is also possible to supply file specific compilation
   404         *      options.
   405         *      @p(code)
   406         *          myExe.addObjects(["fir.c", "iir.c"], {defs: "-D_DEBUG"});
   407         *      @p
   408         *      In this case, both files fir.c and iir.c will be compiled
   409         *      with the "`-D_DEBUG`" flag.  Any setting of `attrs.defs` in the
   410         *      executable or package is overridden by this definition.
   411         *
   412         *  @param(names)       array of base names of the sources of object files
   413         *                      to be created and linked into the executable.
   414         *                      See NOTE in `{@link xdc.bld}` for filename rules.
   415         *  @param(objAttrs)    optional `{@link xdc.bld.Object#Attrs}` for the
   416         *                      array of objects added; all objects named by names
   417         *                      will be given the attributes `objAttrs`.
   418         *  @a(returns)         `void`
   419         *
   420         *  @a(throws)          `Error` exceptions are thrown for fatal errors
   421         *
   422         *  @see xdc.cfg.Program#global
   423         */
   424        Void addObjects(String names[], Object.Attrs objAttrs = {});
   425    
   426        /*!
   427         *  ======== addTest ========
   428         *  Add specified test to executable.
   429         *
   430         *  A test encapsulates an executable and a set of arguments passed to
   431         *  the executable when it is run.
   432         *
   433         *  Tests are run by naming the goal "`<test_name>.test`" on the xdc
   434         *  command line; `<test_name>` is the test's name.
   435         *
   436         *  Multiple tests may have the same name; in this case, it is possible
   437         *  to run all tests using the single goal "`<test_name>.test`" 
   438         *
   439         *  @param(testAttrs)   test attrs object (`{@link xdc.bld.Test#Attrs}`)
   440         *
   441         *  @a(returns)         the `{@link xdc.bld.Test}` instance object created
   442         *
   443         *  @a(throws)          `Error` exceptions are thrown for fatal errors
   444         */
   445        Test.Instance addTest(Test.Attrs testAttrs);
   446    }
   447    /*
   448     *  @(#) xdc.bld; 1, 0, 2,0; 2-20-2019 10:21:42; /db/ztree/library/trees/xdc/xdc-F09/src/packages/
   449     */
   450