metaonly module xdc.bld.PackageContents

Package container populated by a build script

This module defines the PackageContents object (aliased as Pkg in build scripts) which represents the contents of a package. Build scripts add to this package using the add* methods defined below. [ more ... ]
XDCscript usage meta-domain sourced in xdc/bld/PackageContents.xdc
var PackageContents = xdc.useModule('xdc.bld.PackageContents');
module-wide constants & types
        obj.profile// select appropriate ITarget.OptionSet = String  ...
        obj.aopts// assembly language options = String  ...
        obj.copts// C/C++ compiler options = String  ...
        obj.cfgcopts// C/C++ compiler options for the C config file = String  ...
        obj.defs// -D options common to C/C++/asm = String  ...
        obj.incs// -I options common to C/C++/asm = String  ...
        obj.tcopts// tconf options, deprecated = String  ...
        obj.xsopts// xs options = String  ...
        obj.lopts// linker options = String  ...
        obj.exportDoc// if true, export generated docs = Bool  ...
        obj.exportExe// if true, export executables = Bool  ...
        obj.exportCfg// if true, export program cfg scripts = Bool  ...
        obj.exportSrc// if true, export all package sources = Bool  ...
        obj.exportAll// if true, export all non-gen'd files = Bool  ...
        obj.relScript// release files post-processing script = String  ...
        obj.relScriptArgs// optional arguments to relScript = String  ...
        obj.compress// if true, compress package release archives = Bool  ...
        obj.archiver// "tar" or "zip"; defaults to "tar" = String  ...
module-wide config parameters
    PackageContents.name// Name of this package = String undefined;
module-wide functions
 
DETAILS
This module defines the PackageContents object (aliased as Pkg in build scripts) which represents the contents of a package. Build scripts add to this package using the add* methods defined below.
In addition to the items added by the build script, every package has at least one release, the default release. If the defaultRelease configuration parameter is not set, a default release will be implicitly created.
Every library, executable, and repository added to the package is automatically added to the default release.
struct PackageContents.Attrs

Package-level attributes

XDCscript usage meta-domain
var obj = new PackageContents.Attrs;
 
    obj.profile = String  ...
    // select appropriate ITarget.OptionSet
    obj.aopts = String  ...
    // assembly language options
    obj.copts = String  ...
    // C/C++ compiler options
    obj.cfgcopts = String  ...
    // C/C++ compiler options for the C config file
    obj.defs = String  ...
    // -D options common to C/C++/asm
    obj.incs = String  ...
    // -I options common to C/C++/asm
    obj.tcopts = String  ...
    // tconf options, deprecated
    obj.xsopts = String  ...
    // xs options
    obj.lopts = String  ...
    // linker options
    obj.exportDoc = Bool  ...
    // if true, export generated docs
    obj.exportExe = Bool  ...
    // if true, export executables
    obj.exportCfg = Bool  ...
    // if true, export program cfg scripts
    obj.exportSrc = Bool  ...
    // if true, export all package sources
    obj.exportAll = Bool  ...
    // if true, export all non-gen'd files
    obj.relScript = String  ...
    // release files post-processing script
    obj.relScriptArgs = String  ...
    // optional arguments to relScript
    obj.compress = Bool  ...
    // if true, compress package release archives
    obj.archiver = String  ...
    // "tar" or "zip"; defaults to "tar"
FIELDS
profile — This string names a profile defined by the executable's target. A profile specifies a set of compiler, linker, and archiver options that are to be used when compiling and linking code. Note that these tool options are in addition to any options specified via aopts, copts, etc.
If this field is not specified or set to null, the "release" profile will be used.
incs — This string contains include path options used by the compiler (or assembler) to locate include files; e.g., "-I ../../include -I ../c55xx". Note that the syntax of this string may be target dependent.
defs — This string contains options used by the compiler (or assembler) to define macros; e.g., "-D_C6xxx -DDEBUG=1". Note that the syntax of this string may be target dependent.
aopts — This string contains options used by the assembler to produce object files; e.g., "-mP1". Note that the syntax of this string may be target dependent.
copts — This string contains options used by the C/C++ compiler to produce object files; e.g., "-o3 -mi1". Note that the syntax of this string may be target dependent.
cfgcopts — This string contains options used by the C/C++ compiler to compile the generated C config file. If cfgopts is not specified, the options specified in copts are used instead.
lopts — This string contains options used by the linker produce object files; e.g., "-l mylib.lib". Note that the syntax of this string may be target dependent.
tcopts — This string contains options passed to tconf Deprecated, use xsopts instead.
xsopts — This string contains options passed to xs when running configuration scripts; e.g., to turn on the reporting of warnings this string can be set to "-js -w", or to define the name-value pair "FOO=bar" available via the environment hash-table xsopts should be set to "-DFOO=bar".
exportCfg — If this field is set to true, configuration scripts will, by default, be part of the releases created by this package.
exportDoc — If this field is set to true, generated documentation will, by default, be part of the releases created by this package.
exportSrc — If this field is set to true, the sources used to build this package will, by default, be part of the releases created by this package.
exportExe — If this field is set to true, the executables created in this package will, by default, be part of the releases created by this package.
exportAll — If this field is set to true, all files in this package that are not known to be generated are in the release. If it is unspecified (or set to null) these files will not be added to this release. See xdc.bld.Release.Attrs for more information about this option.
relScript — If this field is non-null, the string names a "release script" that is run to post-process the files that are part of a release. Like configuration scripts, the string names a script file that is searched for first in the in package's base directory, and then along the package path.
relScriptArgs — If this field is non-null, the string is used to initialize the arguments[] array which is accessible to the release script named by relScript. The elements of the argumants[] array are formed from the white space separated elements of relScriptArgs. If this string is null or empty, the arguments[] array has length 0.
compress — If this field is set to true, the package release archive files will be, by default, compressed; otherwise, the archives will not be compressed
archiver — This field names the archiver to use when creating a release. Two archivers are currently supported: "tar" and "zip". If the archiver is set to "zip" the Attrs.compress field is implicitly set to true.
DETAILS
These attributes provide package-level defaults for attributes that provide control over the code generation tools, the configuration tool, and release options.
SEE
config PackageContents.attrs  // module-wide

Package attributes

XDCscript usage meta-domain
PackageContents.attrs = PackageContents.Attrs undefined;
DETAILS
These attributes are "inherited" by all executables and libraries added to this package set.
SEE
config PackageContents.cfgDir  // module-wide

The directory where all intermediate program files are placed

XDCscript usage meta-domain
PackageContents.cfgDir = String "package/cfg/";
DETAILS
During configuration, several files are generated (a C++ source file, a linker command file, etc.) these generated files are placed in the directory specified by this parameter.
config PackageContents.defaultRelease  // module-wide

The default release for this package

XDCscript usage meta-domain
PackageContents.defaultRelease = Release.Instance undefined;
DETAILS
If this configuration parameter is defined, it is taken to be the default release instance; otherwise a default instance is created with the appropriate defaults.
If this release's label attribute is undefined or null, it is set to "default" before the release is generated; otherwise the label attribute is unchanged from what the user specified for this instance.
The implicitly created default release is created as follows:
	    PackageContents.addRelease(name, {label: "default"})
where name is the package's name with all '.'s replaced with '_'.
config PackageContents.docDir  // module-wide

The directory where generated docs are placed

XDCscript usage meta-domain
PackageContents.docDir = String undefined;
DETAILS
If set to a non-null value, package documentation will be automatically generated and placed in this directory. If it is not set or set to null, no docs will be generated for this package.
If you set exportDoc or exportAll to true the generated docs will be included in the appropriate releases of the package.
config PackageContents.excludeDirs  // module-wide

List of directory base names to exclude

XDCscript usage meta-domain
PackageContents.excludeDirs = String[] undefined;
DETAILS
This is an array of arbitrary directory "base names" that should be excluded in this release of the package. This list only excludes directories that would otherwise be added due to the recursive include of a parent directory.
For example, if a directory is specified in otherFiles all of its sub-directories will be added unless those sub-directories are named in the excludeDirs list.
This list is often used to exclude "hidden" directories added by change control systems and IDEs (.svn, .git, .settings, ...).
SEE
config PackageContents.generatedFiles  // module-wide

Array of generated files

XDCscript usage meta-domain
PackageContents.generatedFiles = String[] undefined;
DETAILS
This is an array of arbitrary file names that are to be removed during a clean of this package. File names that end with the '/' character are assumed to be directories; in this case, the directory and all of its contents are removed during the clean.
Only those files that are not already directly (or indirectly) named by adding executables or libraries to this package set need to appear in this array.
config PackageContents.imports  // module-wide

An array of required packages (and their version) for this package

XDCscript usage meta-domain
PackageContents.imports = String[] undefined;
READONLY
This parameter is an array of all prerequisite packages required by this package. Each string is of the form:
		<packageName>{<packageCompatibilityKey>
where <packageName> is the name of the required package and <packageCompatibilityKey> is the compatibility key specified in the requires statement of this package. If no compatibility key is specified in package.xdc, <packageCompatibilityKey> is "".
If the package specifies that a requirement is "internal", the package name is prefixed with a '*' character. In other words, the string is of the form:
		*<packageName>{<packageCompatibilityKey>
config PackageContents.interfaces  // module-wide

An array of interface names provided by this package

XDCscript usage meta-domain
PackageContents.interfaces = String[] undefined;
READONLY
This parameter is an array of all interface names defined by this package.
config PackageContents.libDir  // module-wide

The directory where all intermediate library directories are placed

XDCscript usage meta-domain
PackageContents.libDir = String "package/lib/";
DETAILS
Each object file for a library is placed in a sub-directory of this directory that has a name that matches the name specified in the addLibrary() function.
config PackageContents.libTemplate  // module-wide

Template of a common C-file archived into every library

XDCscript usage meta-domain
PackageContents.libTemplate = String null;
DETAILS
This template can be used to embed package-specific meta-information into each library produced by the package. For example, it can be used to add package version infomation to each library.
This template is expanded just once in the Build model during makefile generation. Thus, the contents of the resulting C-file can not be library specific.
The template is found using xdc.findFile() and, as a result, libTemplate may refer to a template in either the current package or even in another package.
During expansion of the template, the this pointer is the PackageContents module object; i.e., the object that the global variable Pkg references.
The expanded template may refer to the following pre-defined macros:
__xdc_PKGVERS
the package compatibility key declared in package.xdc; e.g. "1, 2, 3"
__xdc_PKGNAME
the package's name; e.g., xdc.bld
__xdc_PKGPREFIX
the package's prefix; e.g., for the package xdc.bld the prefix would be xdc_bld_
config PackageContents.makeEpilogue  // module-wide

String to add to the end of the generated makefile

XDCscript usage meta-domain
PackageContents.makeEpilogue = String "";
DETAILS
Similar to makePrologue except that this string is placed at the very end of the generated makefile.
config PackageContents.makePrologue  // module-wide

String to add to the beginning of the generated makefile

XDCscript usage meta-domain
PackageContents.makePrologue = String "";
DETAILS
This string is placed at the very beginning of the package's generated makefile. This allows one to extend the build environment using any facility available to GNU make.
config PackageContents.modules  // module-wide

An array of module names provided by this package

XDCscript usage meta-domain
PackageContents.modules = String[] undefined;
READONLY
This parameter is an array of all module names implemented in this package.
config PackageContents.name  // module-wide

Name of this package

XDCscript usage meta-domain
PackageContents.name = String undefined;
READONLY
This parameter is the name of this package as specified by the package.xdc package specification file
config PackageContents.otherFiles  // module-wide

Array of files to include this package

XDCscript usage meta-domain
PackageContents.otherFiles = String[] undefined;
DETAILS
This is an array of arbitrary file names that are to be included in the package.
Only those files that are not already directly (or indirectly) named by adding executables or libraries to this package set need to appear in this array.
SEE
config PackageContents.otherSrcs  // module-wide

Array of source files to include this package

XDCscript usage meta-domain
PackageContents.otherSrcs = String[] undefined;
DETAILS
Like otherFiles except that the file names listed here are to be post-processed by the xdc document preparation tools. This array only needs to specify files that are not implicitly specidied via any of the addObjects function; e.g., script files, hand-creafted headers, etc.
config PackageContents.producerId  // module-wide

Producer ID string

XDCscript usage meta-domain
PackageContents.producerId = String undefined;
DETAILS
The value of this string is embedded in every release of this package and can serve as a way to "map" this package to a unique ID that the producer uses to locate, within their SCM system, the original sources required to create and maintain this package.
This string is retained and may by displayed by various tools, but it is uninterpreted by the XDCtools.
config PackageContents.relDir  // module-wide

The directory where all intermediate release files are placed

XDCscript usage meta-domain
PackageContents.relDir = String "package/rel/";
DETAILS
Release specific files for a release are placed in a sub-directory of this directory that has a name that matches the name specified in the addRelease() function.
config PackageContents.releasePrefix  // module-wide

A prefix appended to the name of each release archive

XDCscript usage meta-domain
PackageContents.releasePrefix = String "";
DETAILS
This configuration parameter allows one to generate release archives somewhere other than inside the package being built. releasePrefix is prepended to the name of the release name to form the name of the release archive.
For example, setting releasePrefix to "../" implies that a release named "exports/foo" generates an archive file named foo.tar in the directory "../exports".
releasePrefix must either begin with the '^' character or be a relative path that is relative to the package's "base" directory; i.e., the directory containing the package's specification file package.xdc.
If releasePrefix begins with the '^' character, the remainder of the string is treated as though it is relative to the package's repository. In effect, the '^' character is replaced with an appropriate number of '../' sequences to sufficient to navigate to the package's repository.
For example, suppose your packages are in a repository named "src". Setting releasePrefix to "^/../exports" implies that a release named "foo" generates an archive file named foo.tar in the directory named "exports" which is a sibiling of "src" - the package's repository.
This prefix can be overridden on a per release basis; see xdc.bld.Release.Attrs.
NOTE
If this parameter starts with ".." or "^", the resulting archive file will not be removed as part of a package clean.
config PackageContents.uses  // module-wide

Array of directory suffixes used to locate files

XDCscript usage meta-domain
PackageContents.uses = String[] undefined;
DETAILS
This array of directory suffixes is used to locate package files that are referenced (e.g., via #include) without the package name.
This array names package directory suffixes (found along the package path) that:
  1. contain headers included by this package's sources which are included *without* using the package name, or
  2. contain JavaScript "import" files which are included (via utils.importFile()) *without* using the package name.
This mechanism is used to support legacy code that does not explicitly name the package in the #include statements, and *only* affects the compiler's -I options (not the package path) and the configuration tool's import path (config.importPath).
Strings in the Pkg.uses array must not be absolute paths. Each string in the Pkg.uses array must point to an existing directory that can be located along the package path. The generated makefiles create an absolute path by simply appending the string from uses[] to each directory name in the package path until an existing directory is found. The resulting absolute path is then passed to the compiler in a -I option, for example.
The directories named in this array may include sub-directories of any package in the package path.
The strings in this array should use '/' to separate directories; even on Windows systems. Since Windows supports '/' as a directory separator, the use of '/' ensures host platform independence.
EXAMPLE
The following example allows sources in the current package to "#include <tsk.h>" and have the compiler find tsk.h in the sub-directory ti/bios/include which is contained in some repository named in the package path (XDCPATH):
          var Pkg = xdc.useModule('xdc.bld.PackageContents');
          Pkg.uses = ["ti/bios/include", "ti/xdais/legacy"];
config PackageContents.version  // module-wide

The package version string

XDCscript usage meta-domain
PackageContents.version = String undefined;
READONLY
This parameter is a version string that comes from the package.xdc specification.
PackageContents.addExecutable()  // module-wide

Add specified executable to this package

XDCscript usage meta-domain
PackageContents.addExecutable(String name, ITarget.Module target, String platform, Executable.Attrs exeAttrs) returns Executable.Instance
ARGUMENTS
name — executable base name; this name is used to create the file name of the output executable and has the form:
                       <name>.x<suffix>
where <suffix> is the suffix specified by the target argument below. See NOTE in xdc.bld for filename rules.
target — target (xdc.bld.ITarget) for each built object linked into the executable.
platform — string name of the platform; this is the name of a platform package
exeAttrs — optional executable attrs object (xdc.bld.Executable.Attrs)
DETAILS
The name of the executable file is <name>.x<target_suffix>, where <name> is the name parameter (which may contain a directory prefix) and <target_suffix> is the suffix specified by the target parameter (xdc.bld.ITarget.suffix).
This name is also used to create a sub-directory in the package's "cfgDir" directory (xdc.bld.PackageContents.cfgDir) to contain files generated for the benefit of creating the executable. Thus, the name parameter names *both* an executable file and a sub-directory (in PackageContents.cfgDir) that contains the objects linked into the executable.
When the executable is added to the package, a xdc.bld.Test is implicitly added to the executable; thus, every executable has at least one Test. Attributes for this test can be specified via exeAttrs.
RETURNS
Returns the xdc.bld.Executable instance object created.
THROWS
XDCException exceptions are thrown for fatal errors. The following error codes are reported in the exception message:
xdc.bld.INVALID_TARGET
This error is reported when a package is being built for an unknown target. Ensure that the correct targets are mentioned in the package's build script.
xdc.bld.EXECUTABLE_EXISTS
This error is reported when a package's build script specifies multiple executables with the same name. Ensure that the names of the executables to be built are unique.
xdc.bld.PARAMETER_MISMATCH
This error is reported whenever parameters with the wrong type are passed to the method. Ensure that the parameters passed have the right type.
PackageContents.addLibrary()  // module-wide

Add specified library to this package

XDCscript usage meta-domain
PackageContents.addLibrary(String name, ITarget.Module target, Library.Attrs libAttrs) returns Library.Instance
ARGUMENTS
name — library base name; this name is used to create *both* an archive and a sub-directory in the package's "libDir" directory which will contain the target-specific object files. See NOTE in xdc.bld for filename rules.
target — target (a module implementing the xdc.bld.ITarget interface) for each built object in the library
libAttrs — optional library attributes object (xdc.bld.Library.Attrs)
DETAILS
The name of the library archive file is <name>.a<target_suffix>, where <name> is the name parameter (which may contain a directory prefix) and <target_suffix> is the suffix specified by the target parameter (xdc.bld.ITarget.suffix).
The individual objects of each library are located in the directory <libDir>/<name>, where <name> is the name parameter and <libDir> is the configurable parameter xdc.bld.PackageContents.libDir. Thus, the name parameter names *both* an archive file and a sub-directory (in PackageContents.libDir) that contains the objects in the archive.
RETURNS
Returns the xdc.bld.Library instance object created.
THROWS
XDCException exceptions are thrown for fatal errors. The following error codes are reported in the exception message:
xdc.bld.INVALID_TARGET
This error is reported when a package is being built for an unknown target. Ensure that the correct targets are mentioned in the package's build script.
xdc.bld.LIBRARY_EXISTS
This error is reported when a package's build script specifies multiple libraries with the same name. Ensure that the names of the libraries to be built are unique.
xdc.bld.PARAMETER_MISMATCH
This error is reported whenever parameters with the wrong type are passed to the method. Ensure that the parameters passed have the right type.
SEE
PackageContents.addRelease()  // module-wide

Add specified release to this package

XDCscript usage meta-domain
PackageContents.addRelease(String name, Release.Attrs relAttrs) returns Release.Instance
ARGUMENTS
name — release base name; this name is used to create the file name of the output file and has the form: <name>.tar See NOTE in xdc.bld for filename rules.
relAttrs — optional release attributes object (xdc.bld.Release.Attrs)
RETURNS
Returns the xdc.bld.Release instance object created.
THROWS
XDCException exceptions are thrown for fatal errors. The following error codes are reported in the exception message:
xdc.bld.RELEASE_EXISTS
This error is reported whenever a package's build script specifies multiple releases with the same name. Ensure that the names of the releases specified in the build script are unique.
xdc.bld.INVALID_RELEASE_PREFIX
This error is reported whenever a release prefix is specified by its absolute path in the package's build script. The release prefix has to be relative to the package's base directory.
xdc.bld.INVALID_RELEASE_NAME
This error is reported whenever a release name is specified by its absolute path in the package's build script. The release name has to be relative to the package's base directory.
PackageContents.addRepository()  // module-wide

Add a repository to this package

XDCscript usage meta-domain
PackageContents.addRepository(String repositoryName, Repository.Attrs repAttrs) returns Repository.Instance
ARGUMENTS
repositoryName — name of a directory (relative to this package's base) that will contain the packages added via xdc.bld.Repository.addPackages() See NOTE in xdc.bld for filename rules.
repAttrs — optional Repository attributes associated with this repository (see xdc.bld.Repository.Attrs)
DETAILS
A repository is a directory that contains packages. Repositories are typically named in the user's XDCPATH environment variable and contain a set of packages that are managed as a group.
This method allows one to bundle several packages together into a single release (of the package that contains this repository).
RETURNS
Returns the xdc.bld.Repository instance object created.
THROWS
XDCException exceptions are thrown for fatal errors. The following error codes are reported in the exception message:
xdc.bld.REPOSITORY_EXISTS
This error is reported whenever a package's build script specifies multiple repositories with the same name. Ensure that the names of the repositories specified in the build script are unique.
PackageContents.addScript()  // module-wide

Add a script to this package

XDCscript usage meta-domain
PackageContents.addScript(String name, Script.Attrs scriptAttrs) returns Script.Instance
ARGUMENTS
name — name of the script to add to this package. Script names are simply the script's filename relative to the package's base directory. Scripts can have any extension, but if the extension is ".sh" or ".ksh" a Korn shell compatible shell is used to run the script's tests; otherwise it is assumed to be an XDCscript file and any tests will be run by the XDCscript interpreter xs.
scriptAttrs — optional script attributes object (xdc.bld.Script.Attrs)
DETAILS
Both XDCscript and Korn shell scripts can be added to package. This not only allows one to add script utilities to a package, it also makes it easy to create scripted regression tests. As with Executables, it is possible to add xdc.bld.Tests to a Script; see xdc.bld.Script.addTest.
RETURNS
Returns the xdc.bld.Script instance object created.
THROWS
XDCException exceptions are thrown for fatal errors. The following error codes are reported in the exception message:
xdc.bld.SCRIPT_EXISTS
This error is reported whenever a package's build script specifies multiple user scripts with the same name. Ensure that the names of the user scripts are unique.
generated on Tue, 24 Aug 2010 15:39:30 GMT