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