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     *  ======== PackageContents.xdc ========
    14     */
    15    package xdc.bld;
    16    
    17    /*!
    18     *  ======== PackageContents ========
    19     *  Package container populated by a build script.
    20     *
    21     *  This module defines the `PackageContents` object (aliased as `Pkg` in 
    22     *  build scripts) which represents the contents of a package.  Build scripts
    23     *  add to this package using the add* methods defined below.
    24     *
    25     *  In addition to the items added by the build script, every package has at
    26     *  least one release, the default release.  If the {@link #defaultRelease}
    27     *  configuration parameter is not set, a default release will be
    28     *  implicitly created.
    29     *
    30     *  Every library, executable, and repository added to the package is
    31     *  automatically added to the default release.
    32     *
    33     */
    34    metaonly module PackageContents {
    35        /*!
    36         *  ======== Attrs ========
    37         *  Package-level attributes.
    38         *
    39         *  These attributes provide package-level defaults for attributes that
    40         *  provide control over the code generation tools, the configuration
    41         *  tool, and release options.
    42         *
    43         *  @field(profile)  This string names a profile defined by the
    44         *          executable's target.  A profile specifies a set of compiler,
    45         *          linker, and archiver options that are to be used when 
    46         *          compiling and linking code.  Note that these tool options are
    47         *          in addition to any options specified via `aopts`, `copts`,
    48         *          etc.
    49         *
    50         *          If this field is not specified or set to `null`, the
    51         *          `"release"` profile will be used.
    52         *
    53         *  @field(incs)  This string contains include path options used by
    54         *          the compiler (or assembler) to locate include files; e.g.,
    55         *          "`-I ../../include -I ../c55xx`".  Note that the syntax of 
    56         *          this string may be target dependent.
    57         *
    58         *  @field(defs)  This string contains options used by the
    59         *          compiler (or assembler) to define macros; e.g.,
    60         *          "`-D_C6xxx -DDEBUG=1`".  Note that the syntax of 
    61         *          this string may be target dependent.
    62         *
    63         *  @field(aopts)  This string contains options used by the assembler
    64         *          to produce object files; e.g., "`-mP1`".  Note that the syntax
    65         *          of this string may be target dependent.
    66         *
    67         *  @field(copts)  This string contains options used by the C/C++
    68         *          compiler to produce object files; e.g., "`-o3 -mi1`".  Note
    69         *          that the syntax of this string may be target dependent.
    70         *
    71         *  @field(cfgcopts)  This string contains options used by the C/C++
    72         *          compiler to compile the generated C config file. If `cfgopts`
    73         *          is not specified, the options specified in `copts` are
    74         *          used instead. 
    75         *
    76         *  @field(lopts)  This string contains options used by the linker
    77         *          produce object files; e.g., "`-l mylib.lib`".  Note
    78         *          that the syntax of this string may be target dependent.
    79         *
    80         *  @field(tcopts)  This string contains options passed to `tconf`
    81         *          Deprecated, use `xsopts` instead.
    82         *
    83         *  @field(xsopts)  This string contains options passed to `xs`
    84         *          when running configuration scripts; e.g., to turn on the
    85         *          reporting of warnings this string can be set to "`-js -w`",
    86         *          or to define the name-value pair "`FOO=bar`" available via
    87         *          the environment hash-table `xsopts` should be set to
    88         *          "`-DFOO=bar`".
    89         *
    90         *  @field(exportCfg)  If this field is set to `true`,  configuration
    91         *          scripts will, by default, be part of the releases created
    92         *          by this package.  
    93         *
    94         *  @field(exportDoc)  If this field is set to `true`,  generated
    95         *          documentation will, by default, be part of the releases 
    96         *          created by this package.  
    97         *
    98         *  @field(exportSrc)  If this field is set to `true`, the sources
    99         *          used to build this package will, by default, be part of the
   100         *          releases created by this package.
   101         *
   102         *  @field(exportExe)  If this field is set to `true`, the executables
   103         *          created in this package will, by default, be part of the
   104         *          releases created by this package.
   105         *
   106         *  @field(exportAll)  If this field is set to true, all files
   107         *          in this package that are not known to be generated are in
   108         *          the release.  If it is unspecified (or set to `null`) these
   109         *          files will not be added to this release. See
   110         *          `{@link xdc.bld.Release#Attrs}` for more information about
   111         *          this option.
   112         *
   113         *  @field(relScript)  If this field is non-`null`, the string names a
   114         *          "release script" that is run to post-process the
   115         *          files that are part of a release.  Like configuration scripts,
   116         *          the string names a script file that is searched for first in
   117         *          the in package's base directory, and then along the package
   118         *          path.
   119         *
   120         *  @field(relScriptArgs)  If this field is non-`null`, the string is
   121         *          used to initialize the `arguments[]` array which is
   122         *          accessible to the release script named by `relScript`.  The
   123         *          elements of the `argumants[]` array are formed from the white
   124         *          space separated elements of `relScriptArgs`.  If this string
   125         *          is `null` or empty, the `arguments[]` array has length `0`.
   126         *
   127         *  @field(compress) If this field is set to `true`, the package release
   128         *          archive files will be, by default, compressed; otherwise, the
   129         *          archives will not be compressed
   130         *
   131         *  @field(archiver) This field names the archiver to use when creating a
   132         *          release.  Two archivers are currently supported:
   133         *          "tar" and "zip".  If the archiver is set to "zip"
   134         *          the `{@link #Attrs.compress}` field is implicitly set to
   135         *          `true`.
   136         *
   137         *  @see #attrs
   138         */
   139        struct Attrs {
   140            String  profile;    /*! select appropriate `ITarget.OptionSet` */
   141            String  aopts;      /*! assembly language options */
   142            String  copts;      /*! C/C++ compiler options */
   143            String  cfgcopts;   /*! C/C++ compiler options for the C config file */
   144            String  defs;       /*! -D options common to C/C++/asm */
   145            String  incs;       /*! -I options common to C/C++/asm */
   146            String  tcopts;     /*! tconf options, deprecated */
   147            String  xsopts;     /*! xs options */
   148            String  lopts;      /*! linker options */
   149            Bool    exportDoc;  /*! if `true`, export generated docs */
   150            Bool    exportExe;  /*! if `true`, export executables */
   151            Bool    exportCfg;  /*! if `true`, export program cfg scripts */
   152            Bool    exportSrc;  /*! if `true`, export all package sources */
   153            Bool    exportAll;  /*! if `true`, export all non-gen'd files */
   154            String  relScript;  /*! release files post-processing script */
   155            String  relScriptArgs;  /*! optional arguments to relScript */
   156            Bool    compress;   /*! if `true`, compress package release archives */
   157            String  archiver;   /*! "tar" or "zip"; defaults to "tar" */
   158        };
   159        
   160        /*!
   161         *  ======== attrs ========
   162         *  Package attributes.
   163         *
   164         *  These attributes are "inherited" by all executables and libraries
   165         *  added to this package set.
   166         *
   167         *  @see xdc.bld.Executable#attrs
   168         *  @see xdc.bld.Library#attrs
   169         */
   170        config PackageContents.Attrs attrs; 
   171    
   172        /*!
   173         *  ======== cfgDir ========
   174         *  The directory where all intermediate program files are placed.
   175         *
   176         *  During configuration, several files are generated (a C++ source file,
   177         *  a linker command file, etc.)  these generated files are placed in
   178         *  the directory specified by this parameter.
   179         */
   180        config String cfgDir = "package/cfg/";
   181    
   182        /*!
   183         *  ======== docDir ========
   184         *  The directory where generated docs are placed.
   185         *
   186         *  If set to a non-`null` value, package documentation will be
   187         *  automatically generated and placed in this directory.  If
   188         *  it is not set or set to `null`, no docs will be generated for
   189         *  this package.
   190         *
   191         *  If you set `{@link #Attrs exportDoc}` or `{@link #Attrs exportAll}`
   192         *  to `true` the generated docs will be included in the appropriate
   193         *  releases of the package.
   194         */
   195        config String docDir;
   196        
   197        /*!
   198         *  ======== imports ========
   199         *  An array of required packages (and their version) for this package
   200         *
   201         *  @a(readonly) This parameter is an array of all prerequisite packages
   202         *  required by this package.  Each string is of the form:
   203         *      @p(code)
   204         *          <packageName>{<packageCompatibilityKey>
   205         *      @p
   206         *  where `<packageName>` is the name of the required package and
   207         *  `<packageCompatibilityKey>` is the compatibility key specified in the
   208         *  `requires` statement of this package.  If no compatibility key is
   209         *  specified in `package.xdc`, `<packageCompatibilityKey>` is "".
   210         *
   211         *  If the package specifies that a requirement is "internal", the
   212         *  package name is prefixed with a '*' character.  In other words, the
   213         *  string is of the form:
   214         *      @p(code)
   215         *          *<packageName>{<packageCompatibilityKey>
   216         *      @p
   217         */
   218        config String imports[];
   219    
   220        /*!
   221         *  ======== libDir ========
   222         *  The directory where all intermediate library directories are placed.
   223         *
   224         *  Each object file for a library is placed in a sub-directory of this
   225         *  directory that has a name that matches the name specified in the
   226         *  `{@link #addLibrary()}` function.
   227         */
   228        config String libDir = "package/lib/";
   229    
   230        /*!
   231         *  ======== libTemplate ========
   232         *  Template of a common C-file archived into every library
   233         *
   234         *  This template can be used to embed package-specific meta-information
   235         *  into each library produced by the package.  For example, it can be
   236         *  used to add package version infomation to each library.
   237         *
   238         *  This template is expanded just once in the Build model during
   239         *  makefile generation.  Thus, the contents of the resulting C-file can
   240         *  not be library specific.
   241         *
   242         *  The template is found using `xdc.findFile()` and, as a result,
   243         *  `libTemplate` may refer to a template in either the current package
   244         *  or even in another package.
   245         *
   246         *  During expansion of the template, the `this` pointer is the
   247         *  `PackageContents` module object; i.e., the object that the global
   248         *  variable `Pkg` references.
   249         *
   250         *  The expanded template may refer to the following pre-defined macros:
   251         *  @p(dlist)
   252         *      - `__xdc_PKGVERS`
   253         *          the package compatibility key declared in package.xdc; e.g.
   254         *          "`1, 2, 3`"
   255         *      - `__xdc_PKGNAME`
   256         *          the package's name; e.g., `xdc.bld`
   257         *      - `__xdc_PKGPREFIX`
   258         *          the package's prefix; e.g., for the package `xdc.bld` the
   259         *          prefix would be `xdc_bld_`
   260         *  @p
   261         */
   262        config String libTemplate = null;
   263    
   264        /*!
   265         *  ======== relDir ========
   266         *  The directory where all intermediate release files are placed.
   267         *
   268         *  Release specific files for a release are placed in a sub-directory of
   269         *  this directory that has a name that matches the name specified in the
   270         *  `{@link #addRelease()}` function.
   271         */
   272        config String relDir = "package/rel/";
   273    
   274        /*!
   275         *  ======== producerId ========
   276         *  Producer ID string
   277         *
   278         *  The value of this string is embedded in every release of this
   279         *  package and can serve as a way to "map" this package to a unique ID
   280         *  that the producer uses to locate, within their SCM system, the
   281         *  original sources required to create and maintain this package.
   282         *
   283         *  This string is retained and may by displayed by various tools, but 
   284         *  it is uninterpreted by the XDCtools.
   285         */
   286        config String producerId;
   287    
   288        /*!
   289         *  ======== version ========
   290         *  The package version string.
   291         *
   292         *  @a(readonly) This parameter is a version string that comes from the
   293         *  `package.xdc` specification.
   294         */
   295        config String version;
   296    
   297        /*!
   298         *  ======== interfaces ========
   299         *  An array of interface names provided by this package.
   300         *
   301         *  @a(readonly) This parameter is an array of all interface names
   302         *  defined by this package.
   303         */
   304        config String interfaces[];
   305    
   306        /*!
   307         *  ======== makePrologue ========
   308         *  String to add to the beginning of the generated makefile.
   309         *
   310         *  This string is placed at the very beginning of the package's
   311         *  generated makefile.  This allows one to extend the build
   312         *  environment using any facility available to GNU make.
   313         */
   314        config String makePrologue = "";
   315    
   316        /*!
   317         *  ======== makeEpilogue ========
   318         *  String to add to the end of the generated makefile.
   319         *
   320         *  Similar to makePrologue except that this string is placed at
   321         *  the very end of the generated makefile.
   322         */
   323        config String makeEpilogue = "";
   324    
   325        /*!
   326         *  ======== defaultRelease ========
   327         *  The default release for this package.
   328         *
   329         *  If this configuration parameter is defined, it is taken to be the
   330         *  default release instance; otherwise a default instance is created
   331         *  with the appropriate defaults.
   332         *
   333         *  If this release's `label` attribute is `undefined` or `null`, it is
   334         *  set to `"default"` before the release is generated; otherwise the
   335         *  label attribute is unchanged from what the user specified for this
   336         *  instance.
   337         *
   338         *  The implicitly created default release is created as follows:
   339         *  @p(code)
   340         *      PackageContents.addRelease(name, {label: "default"})
   341         *  @p
   342         *  where `name` is the package's name with all '.'s replaced with '_'.
   343         */
   344        config Release.Instance defaultRelease;
   345    
   346        /*!
   347         *  ======== releasePrefix ========
   348         *  A prefix appended to the name of each release archive.
   349         *
   350         *  This configuration parameter allows one to generate release archives
   351         *  somewhere other than inside the package being built.  `releasePrefix`
   352         *  is prepended to the name of the release name to form the name of the
   353         *  release archive.
   354         *
   355         *  For example, setting `releasePrefix` to `"../"` implies that a 
   356         *  release named `"exports/foo"` generates an archive file named
   357         *  `foo.tar` in the directory `"../exports"`.
   358         *
   359         * `releasePrefix` must either begin with the '^' character or be a
   360         *  relative path that is relative to the package's "base" directory;
   361         *  i.e., the directory containing the package's specification file
   362         *  `package.xdc`.
   363         *
   364         *  If `releasePrefix` begins with the '^' character, the remainder of
   365         *  the string is treated as though it is relative to the package's
   366         *  repository.  In effect, the '^' character is replaced with an
   367         *  appropriate number of '../' sequences to sufficient to navigate to
   368         *  the package's repository.
   369         *
   370         *  For example, suppose your packages are in a repository named `"src"`.
   371         *  Setting `releasePrefix` to `"^/../exports"` implies that a release
   372         *  named `"foo"` generates an archive file named `foo.tar` in the
   373         *  directory named `"exports"` which is a sibiling of `"src"` - the
   374         *  package's repository.
   375         *
   376         *  This prefix can be overridden on a per release basis; see
   377         *  `{@link xdc.bld.Release#Attrs}`.
   378         *
   379         *  @a(note) If this parameter starts with `".."` or `"^"`, the resulting
   380         *  archive file will not be removed as part of a package clean.
   381         */
   382        config String releasePrefix = "";
   383        
   384        /*!
   385         *  ======== modules ========
   386         *  An array of module names provided by this package.
   387         *
   388         *  @a(readonly) This parameter is an array of all module names
   389         *  implemented in this package.
   390         */
   391        config String modules[];
   392    
   393        /*!
   394         *  ======== name ========
   395         *  Name of this package
   396         *
   397         *  @a(readonly) This parameter is the name of this package as
   398         *  specified by the `package.xdc` package specification file
   399         */
   400        config String name;
   401    
   402        /*!
   403         *  ======== otherFiles ========
   404         *  Array of files to include this package.
   405         *
   406         *  This is an array of arbitrary file names that are to be included
   407         *  in the package.
   408         *
   409         *  Only those files that are not already directly (or indirectly)
   410         *  named by adding executables or libraries to this package set need
   411         *  to appear in this array.
   412         *
   413         *  @see #excludeDirs
   414         */
   415        config String otherFiles[];
   416    
   417        /*!
   418         *  ======== excludeDirs ========
   419         *  List of directory base names to exclude
   420         *
   421         *  This is an array of arbitrary directory "base names" that should
   422         *  be excluded in this release of the package.  This list only
   423         *  excludes directories that would otherwise be added due to the
   424         *  recursive include of a parent directory.
   425         *
   426         *  For example, if a directory is specified in `{@link #otherFiles}`
   427         *  all of its sub-directories will be added unless those sub-directories
   428         *  are named in the `excludeDirs` list.
   429         *
   430         *  This list is often used to exclude "hidden" directories added by
   431         *  change control systems and IDEs (`.svn`, `.git`, `.settings`, ...).
   432         *
   433         *  @see #otherFiles
   434         *  @see Release#excludeDirs
   435         */
   436        config String excludeDirs[];
   437    
   438        /*!
   439         *  ======== generatedFiles ========
   440         *  Array of generated files
   441         *
   442         *  This is an array of arbitrary file names that are to be removed
   443         *  during a clean of this package.  File names that end with the `'/'`
   444         *  character are assumed to be directories; in this case, the directory
   445         *  and all of its contents are removed during the clean.
   446         *
   447         *  Only those files that are not already directly (or indirectly)
   448         *  named by adding executables or libraries to this package set need
   449         *  to appear in this array.
   450         */
   451        config String generatedFiles[];
   452    
   453        /*!
   454         *  ======== otherSrcs ========
   455         *  Array of source files to include this package.
   456         *
   457         *  Like otherFiles except that the file names listed here are to be
   458         *  post-processed by the xdc document preparation tools.  This array
   459         *  only needs to specify files that are not implicitly specified via
   460         *  any of the addObjects function; e.g., script files, hand-creafted
   461         *  headers, etc.  
   462         */
   463        config String otherSrcs[];
   464        
   465        /*!
   466         *  ======== packagePath ========
   467         *  This configuration parameter allows one to set the package
   468         *  path from within the build script.  This setting overrides
   469         *  the setting of `XDCPATH` either in the environment or on the
   470         *  command line.
   471         *
   472         *  @b(deprecated)  `XDCPATH` should be set on the command line or in
   473         *  the environment.  This avoids the confusion that will result from
   474         *  different package paths being used to generate the makefiles from
   475         *  the package path used to build other package contents.
   476         *
   477         *  @_nodoc this parameter should not be used!!!!!!
   478         */
   479        config String packagePath = null;
   480    
   481        /*!
   482         *  ======== uses ========
   483         *  Array of directory suffixes used to locate files.
   484         *
   485         *  This array of directory suffixes is used to locate package files 
   486         *  that are referenced (e.g., via #include) without the package name.
   487         *
   488         *  This array names package directory suffixes (found along the
   489         *  package path) that:
   490         *  @p(nlist)
   491         *      -  contain headers included by this package's sources which
   492         *         are included *without* using the package name, or
   493         *      -  contain JavaScript "import" files which are included (via
   494         *         `utils.importFile()`) *without* using the package name.
   495         *  @p
   496         *  This mechanism is used to support legacy code that does not
   497         *  explicitly name the package in the #include statements, and *only*
   498         *  affects the compiler's -I options (not the package path) and the
   499         *  configuration tool's import path (`config.importPath`).
   500         *
   501         *  Strings in the Pkg.uses array must not be absolute paths.  Each string
   502         *  in the Pkg.uses array must point to an existing directory that can be
   503         *  located along the package path.  The generated makefiles create an
   504         *  absolute path by simply appending the string from `uses[]` to each
   505         *  directory name in the package path until an existing directory is
   506         *  found.  The resulting absolute path is then passed to the compiler in
   507         *  a -I option, for example.
   508         *
   509         *  The directories named in this array may include sub-directories of
   510         *  any package in the package path.
   511         *
   512         *  The strings in this array should use '/' to separate directories;
   513         *  even on Windows systems.  Since Windows supports '/' as a directory
   514         *  separator, the use of '/' ensures host platform independence.
   515         *
   516         *  @a(Example)
   517         *      The following example allows sources in the current package to
   518         *      "`#include <tsk.h>`" and have the compiler find `tsk.h` in the
   519         *      sub-directory ti/bios/include which is contained in some repository
   520         *      named in the package path (`XDCPATH`):
   521         *      @p(code)
   522         *          var Pkg = xdc.useModule('xdc.bld.PackageContents');
   523         *          Pkg.uses = ["ti/bios/include", "ti/xdais/legacy"];
   524         *      @p
   525         */
   526        config String uses[];
   527    
   528        /*!
   529         *  ======== addLibrary ========
   530         *  Add specified library to this package
   531         *
   532         *  The name of the library archive file is `<name>.a<target_suffix>`,
   533         *  where `<name>` is the name parameter (which may contain a directory
   534         *  prefix) and `<target_suffix>` is the suffix specified by the target
   535         *  parameter (`{@link xdc.bld.ITarget#suffix}`).
   536         *
   537         *  The individual objects of each library are located in the directory
   538         *  `<libDir>/<name>`, where `<name>` is the name parameter and `<libDir>`
   539         *  is the configurable parameter `{@link xdc.bld.PackageContents#libDir}`.
   540         *  Thus, the name parameter names *both* an archive file and a
   541         *  sub-directory (in `PackageContents.libDir`) that contains the objects
   542         *  in the archive.
   543         *
   544         *  @param(name)     library base name; this name is used to create
   545         *                   *both* an archive and a sub-directory in the
   546         *                   package's "libDir" directory which
   547         *                   will contain the target-specific object files.
   548         *                   See NOTE in `{@link xdc.bld}` for filename rules.
   549         *
   550         *  @param(target)   target (a module implementing the
   551         *                   `{@link xdc.bld.ITarget}` interface) for each built 
   552         *                   object in the library
   553         *
   554         *  @param(libAttrs) optional `library` attributes object
   555         *                   (`{@link xdc.bld.Library#Attrs}`)
   556         *
   557         *  @a(returns)      Returns the `{@link xdc.bld.Library}` instance
   558         *                   object created.
   559         *  @a(throws)       `XDCException` exceptions are thrown for fatal
   560         *                    errors. The following error codes are
   561         *                    reported in the exception message:
   562         *                    @p(dlist)
   563         *                    -  `xdc.bld.INVALID_TARGET`
   564         *                       This error is reported when a package is being
   565         *                       built for an unknown target. Ensure that the
   566         *                       correct targets are mentioned in the package's
   567         *                       build script.
   568         *                    -  `xdc.bld.LIBRARY_EXISTS`               
   569         *                        This error is reported when a package's build
   570         *                        script specifies multiple libraries with the
   571         *                        same name. Ensure that the names of the
   572         *                        libraries to be built are unique.
   573         *                    -  `xdc.bld.PARAMETER_MISMATCH`
   574         *                        This error is reported whenever parameters with
   575         *                        the wrong type  are passed to the method. Ensure
   576         *                        that the parameters passed have the right type.
   577         *
   578         *  @see xdc.bld.PackageContents#libDir
   579         *  @see xdc.bld.ITarget#suffix
   580         */
   581        Library.Instance addLibrary(String name, ITarget.Module target,
   582                                    Library.Attrs libAttrs = {});
   583    
   584        /*!
   585         *  ======== addExecutable ========
   586         *  Add specified executable to this package.
   587         *
   588         *  The name of the executable file is `<name>.x<target_suffix>`,
   589         *  where `<name>` is the name parameter (which may contain a directory
   590         *  prefix) and `<target_suffix>` is the suffix specified by the target
   591         *  parameter (`{@link xdc.bld.ITarget#suffix}`).
   592         *
   593         *  This name is also used to create a sub-directory in the package's
   594         *  "cfgDir" directory (`{@link xdc.bld.PackageContents#cfgDir}`) to
   595         *  contain files generated for the benefit of creating the executable.
   596         *  Thus, the name parameter names *both* an executable file and a
   597         *  sub-directory (in `PackageContents.cfgDir`) that contains the objects
   598         *  linked into the executable.
   599         *
   600         *  When the executable is added to the package, a `{@link xdc.bld.Test}`
   601         *  is implicitly added to the executable; thus, every executable has at
   602         *  least one `Test`.  Attributes for this test can be specified via
   603         *  `exeAttrs`.
   604         *
   605         *  @param(name)     executable base name; this name is used to create
   606         *                   the file name of the output executable and has the
   607         *                   form:
   608         *                   @p(code)
   609         *                       <name>.x<suffix>
   610         *                   @p
   611         *                   where `<suffix>` is the suffix specified by
   612         *                   the target argument below.  
   613         *                   See NOTE in `{@link xdc.bld}` for filename rules.
   614         *
   615         *  @param(target)   target (`{@link xdc.bld.ITarget}`) for each built
   616         *                   object linked into the executable.
   617         *
   618         *  @param(platform) string name of the platform; this is the name of a
   619         *                   platform package
   620         *
   621         *  @param(exeAttrs) optional executable attrs object
   622         *                   (`{@link xdc.bld.Executable#Attrs}`)
   623         *
   624         *  @a(returns)      Returns the `{@link xdc.bld.Executable}` instance 
   625         *                   object created.
   626         *
   627         *  @a(throws)       `XDCException` exceptions are thrown for fatal
   628         *                    errors. The following error codes are
   629         *                    reported in the exception message:
   630         *                    @p(dlist)
   631         *                    -  `xdc.bld.INVALID_TARGET`
   632         *                       This error is reported when a package is being
   633         *                       built for an unknown target. Ensure that the
   634         *                       correct targets are mentioned in the package's
   635         *                       build script.
   636         *                    -  `xdc.bld.EXECUTABLE_EXISTS`               
   637         *                       This error is reported when a package's build
   638         *                       script specifies multiple executables with the
   639         *                       same name. Ensure that the names of the
   640         *                       executables to be built are unique. 
   641         *                    -  `xdc.bld.PARAMETER_MISMATCH`
   642         *                       This error is reported whenever parameters with
   643         *                       the wrong type  are passed to the method. Ensure
   644         *                       that the parameters passed have the right type.
   645         *           
   646         */
   647        Executable.Instance addExecutable(String name, ITarget.Module target,
   648                            String platform, Executable.Attrs exeAttrs = {});
   649    
   650        /*!
   651         *  ======== addRepository ========
   652         *  Add a repository to this package
   653         *
   654         *  A repository is a directory that contains packages.  Repositories are
   655         *  typically named in the user's XDCPATH environment variable and contain
   656         *  a set of packages that are managed as a group.
   657         *
   658         *  This method allows one to bundle several packages together into a
   659         *  single release (of the package that contains this repository).
   660         *
   661         *  @param(repositoryName)  name of a directory (relative to this
   662         *                          package's base) that will contain the packages
   663         *                          added via
   664         *                          `{@link xdc.bld.Repository#addPackages()}`
   665         *                          See NOTE in `{@link xdc.bld}` for filename
   666         *                          rules.
   667         *
   668         *  @param(repAttrs)        optional `Repository` attributes associated 
   669         *                          with this repository (see
   670         *                          `{@link xdc.bld.Repository#Attrs}`)
   671         *
   672         *  @a(returns)             Returns the `{@link xdc.bld.Repository}` 
   673         *                          instance object created.
   674         *
   675         *  @a(throws)       `XDCException` exceptions are thrown for fatal
   676         *                    errors. The following error codes are
   677         *                    reported in the exception message:
   678         *                    @p(dlist)
   679         *                    - `xdc.bld.REPOSITORY_EXISTS`
   680         *                      This error is reported whenever a package's build
   681         *                      script specifies multiple repositories with the
   682         *                      same name.  Ensure that the names of the
   683         *                      repositories specified in the build script are
   684         *                      unique.
   685         */
   686        Repository.Instance addRepository(String repositoryName,
   687                                          Repository.Attrs repAttrs = {});
   688         
   689        /*!
   690         *  ======== addRelease ========
   691         *  Add specified release to this package
   692         *
   693         *  @param(name)    release base name; this name is used to create
   694         *                  the file name of the output file and has the
   695         *                  form:
   696         *                      <name>.tar
   697         *                  See NOTE in `{@link xdc.bld}` for filename rules.
   698         *
   699         *  @param(relAttrs) optional release attributes object
   700         *                   (`{@link xdc.bld.Release#Attrs}`)
   701         *
   702         *  @a(returns)     Returns the `{@link xdc.bld.Release}` instance object
   703         *                  created.
   704         *
   705         *  @a(throws)       `XDCException` exceptions are thrown for fatal
   706         *                    errors. The following error codes are
   707         *                    reported in the exception message:
   708         *                    @p(dlist)
   709         *                    - `xdc.bld.RELEASE_EXISTS`
   710         *                      This error is reported whenever a package's build
   711         *                      script specifies multiple releases with the same
   712         *                      name.  Ensure that the names of the releases
   713         *                      specified in the build script are unique.
   714         *                    - `xdc.bld.INVALID_RELEASE_PREFIX`
   715         *                      This error is reported whenever a release prefix
   716         *                      is specified by its absolute path in the package's
   717         *                      build script.  The release prefix has to be
   718         *                      relative to the package's base directory.
   719         *                    - `xdc.bld.INVALID_RELEASE_NAME`
   720         *                      This error is reported whenever a release name is
   721         *                      specified by its absolute path in the package's
   722         *                      build script. The release name has to be relative
   723         *                      to the package's base directory.
   724         */
   725        Release.Instance addRelease(String name, Release.Attrs relAttrs = {});
   726    
   727        /*!
   728         *  ======== addScript ========
   729         *  Add a script to this package
   730         *
   731         *  Both XDCscript and Korn shell scripts can be added to package.  This
   732         *  not only allows one to add script utilities to a package, it
   733         *  also makes it easy to create scripted regression tests.  As with
   734         *  `Executable`s, it is possible to add `{@link xdc.bld.Test}`s to a
   735         *  `{@link xdc.bld.Script Script}`; see `{@link xdc.bld.Script#addTest}`.
   736         *
   737         *  @param(name)    name of the script to add to this package.  Script
   738         *                  names are simply the script's filename relative to
   739         *                  the package's base directory.  Scripts can have any
   740         *                  extension, but if the extension is "`.sh`" or "`.ksh`"
   741         *                  a Korn shell compatible shell is used to run the
   742         *                  script's tests; otherwise it is assumed to be an
   743         *                  XDCscript file and any tests will be run by the
   744         *                  XDCscript interpreter `xs`.
   745         *
   746         *  @param(scriptAttrs) optional script attributes object
   747         *                   (`{@link xdc.bld.Script#Attrs}`)
   748         *
   749         *  @a(returns)      Returns the `{@link xdc.bld.Script}` instance
   750         *                   object created.
   751         *
   752         *  @a(throws)       `XDCException` exceptions are thrown for fatal
   753         *                    errors. The following error codes are
   754         *                    reported in the exception message:
   755         *                      @p(dlist)
   756         *                      - `xdc.bld.SCRIPT_EXISTS`
   757         *                        This error is reported whenever a package's build
   758         *                        script specifies multiple user scripts with the
   759         *                        same name. Ensure that the names of the user
   760         *                        scripts are unique.
   761         */
   762        Script.Instance addScript(String name, Script.Attrs scriptAttrs = {});
   763        
   764        /*!
   765         *  ======== addAssembly ========
   766         *  @_nodoc assemblies are experimental not fully qualified/tested
   767         *          entities
   768         *  @a(returns)      Returns the `{@link xdc.bld.Assembly}` instance
   769         *                   object created.
   770         *
   771         *  @a(throws)       `XDCException` exceptions are thrown for fatal
   772         *                    errors. The following error codes are
   773         *                    reported in the exception message:
   774         *                    @p(dlist)
   775         *                    - `xdc.bld.INVALID_TARGET`
   776         *                      This error is reported when a package is being
   777         *                      built for an unknown target. Ensure that the
   778         *                      correct targets are mentioned in the package's
   779         *                      build script.
   780         */
   781        Assembly.Instance addAssembly(String name, ITarget.Module target,
   782            String platform, Executable.Attrs exeAttrs = {});
   783    
   784        /*!
   785         *  ======== addConfiguration ========
   786         *  @_nodoc
   787         */
   788        Configuration.Instance addConfiguration(String name, ITarget.Module target,
   789            String platform, Configuration.Attrs cfgAttrs = {});
   790    
   791        /*!
   792         *  ======== onInit ========
   793         *  @_nodoc this function is called from the bld package's 
   794         *          initialization function to initialize this module.
   795         *
   796         *  @a(throws)       `XDCException` exceptions are thrown for fatal
   797         *                    errors. The following error codes are
   798         *                    reported in the exception message:
   799         *                    @p(dlist)
   800         *                    - `xdc.bld.INCORRECT_PACKAGE_NAME`
   801         *                      This error is reported whenever package name does
   802         *                      not match the directory name. Package names should
   803         *                      match the directory layout. For example the
   804         *                      package `ti.sdo.ce.osal` should be created in the
   805         *                      directory `ti\sdo\ce\osal`. 
   806         *                    - `xdc.bld.CREATE_DIR_ERROR`
   807         *                      This error is reported whenever there is an error
   808         *                      in creating package directories. This maybe
   809         *                      related with issues with the host filesystem.
   810         *                      Check whether directories
   811         *                      can be created manually in the `package`
   812         *                      sub-directory.
   813         */
   814        function onInit();
   815    }
   816    /*
   817     *  @(#) xdc.bld; 1, 0, 2,389; 9-20-2012 15:01:53; /db/ztree/library/trees/xdc/xdc-y36x/src/packages/
   818     */
   819