module xdc.bld.BuildEnvironment

metaonly module xdc.bld.BuildEnvironment

Global build environment

XDCscript usage
Individual elements

This module defines a global object (aliased as 'Build' in build scripts) which is configured by a build "startup" script and read by package build scripts. [ more ... ]

XDCscript usage meta-domain sourced in xdc/bld/BuildEnvironment.xdc

var BuildEnvironment = xdc.useModule('xdc.bld.BuildEnvironment');

module-wide constants & types

values of type BuildEnvironment.HostOS// An enumeration of all supported development hosts

const BuildEnvironment.WINDOWS// Win32 Intel development host;

const BuildEnvironment.SOLARIS// SUN OS 5.x development host;

const BuildEnvironment.LINUX// Linux development host;

module-wide config parameters

const BuildEnvironment.hostOS// Enumerated constant that identifies the host OS that is executing the build script = BuildEnvironment.HostOS computed value;

const BuildEnvironment.hostOSName// The name of the development host = String computed value;

BuildEnvironment.excludeTargets// A set of targets to exclude from the set specified by useTargets = String undefined;

BuildEnvironment.nativeTarget// A target that defines the "native" target = ITarget.Module null;

BuildEnvironment.platformTable// A map of platform instance names to the parameters used to create them = Any[string] [ ];

BuildEnvironment.targets// Array of all targets that are supported for the current build = ITarget.Module[] undefined;

BuildEnvironment.useTargets// The set of targets to use if the targets array is empty = String undefined;

module-wide functions

BuildEnvironment.getReleaseDescs// Return a description of all releases for the specified package(String pname) returns Release.Desc[]

DETAILS

This module defines a global object (aliased as 'Build' in build scripts) which is configured by a build "startup" script and read by package build scripts.

This module's configuration parameters are initialized by a "startup" script that is run prior to running a package's build script (package.bld). This script (often named "config.bld") is responsible for specifying the the xdc.bld.ITarget.rootDir configuration parameter of all targets that appear in the targets array; the rootDir configuration parameter specifies the absolute path to the installation directory of the compiler used to build for the specified target. Typically one startup script is used to establish an environment for multiple packages.

Note: it does not matter if you do not have tools for all the targets mentioned in the startup script; if you do not build for a target, its setting in the startup script is irrelevant.

The startup script may configure this module as a function of the following global variables that exist before this script runs:

environment: a hash table of environment strings
arguments: an array of string arguments to the config.bld script initialized as follows: arguments[0] - the file name of the config.bld script; arguments[1] - the first argument specified in XDCARGS; ...; arguments[n] - the nth argument in XDCARGS.
Build: an alias for this module (xdc.bld.BuildEnvironment). The following parameters of this object are initialized before the startup script runs: hostOS - HostOS enumeration identifier; hostOSName - "Windows", "Linux", or "Solaris"
Pkg: an alias for this module (xdc.bld.PackageContents). The following parameters of this object are initialized before the startup script runs: PackageContents.name - the name of the current package; PackageContents.modules - array of module names supplied by this package; and PackageContents.interfaces - array of interface names supplied by this package

When you build a package, the xdc command looks for the startup file using the following algorithm:

if XDCBUILDCFG is defined on the xdc command line, its value is used;
if config.bld exists in the current directory, this file is used;
if XDCBUILDCFG is defined as an environment variable, its value is used;
if config.bld exists along the package path (i.e. in $XDCPATH followed by the current package's repository), the first such file is used;
if $XDCROOT/config.bld exists this file is used;
if $XDCROOT/etc/config.bld exists, this file is used; and finally
if no "startup file" can be found above, a fatal error is reported and the xdc command terminates with a non-zero exit status.

enum BuildEnvironment.HostOS

index URL

An enumeration of all supported development hosts

XDCscript usage meta-domain

values of type BuildEnvironment.HostOS

const BuildEnvironment.WINDOWS;

// Win32 Intel development host

const BuildEnvironment.SOLARIS;

// SUN OS 5.x development host

const BuildEnvironment.LINUX;

// Linux development host

SEE

hostOS

config BuildEnvironment.hostOS // module-wide

index URL

Enumerated constant that identifies the host OS that is executing the build script

XDCscript usage meta-domain

const BuildEnvironment.hostOS = BuildEnvironment.HostOS computed value;

DETAILS

Note that host OS at the time the makefiles are created may be different from the host OS at the time sources are compiled!

config BuildEnvironment.hostOSName // module-wide

index URL

The name of the development host

XDCscript usage meta-domain

const BuildEnvironment.hostOSName = String computed value;

DETAILS

One of the strings: "Windows", "Solaris", "Linux". This name is name of the host OS that is executing the package's build script.

config BuildEnvironment.excludeTargets // module-wide

index URL

A set of targets to exclude from the set specified by useTargets

XDCscript usage meta-domain

BuildEnvironment.excludeTargets = String undefined;

DETAILS

This string parameter is a single regular expression used to exclude targets from the set specified by useTargets (or XDCTARGETS).

If targets is initialized by the build model's configuration script (i.e., has length > 0) this parameter is ignored.

If this string is null or undefined, nothing is excluded from list specified by useTargets or the environment variable XDCTARGETS.

SEE

useTargets, nativeTarget

config BuildEnvironment.nativeTarget // module-wide

index URL

A target that defines the "native" target

XDCscript usage meta-domain

BuildEnvironment.nativeTarget = ITarget.Module null;

DETAILS

This parameter allows build scripts to refer to the "native" target without explicitly naming the target.

For example, a package.bld script may add a library via:

      Pkg.addLibrary("lib", Build.nativeTarget);

In addition, it is possible to use "native" in XDCTARGETS or useTargets to specify that nativeTarget be added to the targets array. Thus, it is possible to use the following command on *any* host to build for that host:

      xdc XDCTARGETS=native

If this parameter is not set by the build model's configuration script, it is initialized to an appropriate default native target:

microsoft.targets.Win32 for Windows hosts;
gnu.targets.Sparc for Solaris hosts; and
gnu.targets.Linux86 for Linux hosts.

config BuildEnvironment.platformTable // module-wide

index URL

A map of platform instance names to the parameters used to create them

XDCscript usage meta-domain

BuildEnvironment.platformTable = Any[string] [ ];

DETAILS

This map allows one to define platform instances that require non-default parameter settings. It also provides a way to publish a set of platforms to be shared among multiple build scripts.

EXAMPLES

The following fragment defines a platform instance named "ti.platforms.sim6xxx:big" that corresponds to a platform instance created by the ti.platforms.sim6xxx.Platform module with the parameters {endian: "big"}:

    Build.platformTable["ti.platforms.sim6xxx:big"] = {endian: "big"};

The following fragment redefines the default platform instance for the platform package ti.platforms.sim6xxx by specifying alternative instance creation parameters.

    Build.platformTable["ti.platforms.sim6xxx"] = {
        endian: "little", verbose: false, ftpath: "c:/ftsuite_1_5",
    };

Some platforms are "software abastractions" that can emulate a large number different physical platforms. In the example below, the ti.platforms.sim6xxx platform package is capable of simulating any TMS320C6xxx device. This particular platform package uses the name of the instance to determine the specific device that it should emulate. So, the fragment below specifies a platform instance named "ti.platforms.sim6xxx:TMS320C6416" that emulates the TMS320C6416 device, in little endian mode.

    Build.platformTable["ti.platforms.sim6xxx:TMS320C6416"] = {
        endian: "little"
    };

Software platform packages, such as the ti.platforms.generic, can even go as far as emulating any device from any "catalog" of devices. In this example, we use the ti.platforms.generic platform package to define an instance named ti.platforms.generic:c6416 that corresponds to a platform containing the TMS320C6416 device specified in the ti.catalog.c6000 package of devices.

    Build.platformTable["ti.platforms.generic:c6416"] = {
        deviceName: "TMS320C6416",
        catalogName: "ti.catalog.c6000",
    };

SEE

ti.catalog.c6000, ti.platforms.generic, ti.platforms.sim6xxx

config BuildEnvironment.targets // module-wide

index URL

Array of all targets that are supported for the current build

XDCscript usage meta-domain

BuildEnvironment.targets = ITarget.Module[] undefined;

DETAILS

This array may be explicitly initialized by the build model's initial configuration script (by default, "config.bld"). For example, the following fragment specifies that just the ti.targets.C64 target should be used:

      // get the ti.targets.C64 module
      var C64 = xdc.module('ti.targets.C64');

      // add the ti.target.C64 module to BuildEnvironment.targets array
      Build.targets[Build.targets.length++] = C64;

Alternatively, this array can be implicitly initialized via the XDCTARGETS environment variable or the useTargets and excludeTargets strings. The targets array is implicitly initialized if and only if the length of this array is 0 after the build model's configuration script completes.

All targets that are in this array *must* have their xdc.bld.ITarget.rootDir property set.

SEE

excludeTargets, useTargets

config BuildEnvironment.useTargets // module-wide

index URL

The set of targets to use if the targets array is empty

XDCscript usage meta-domain

BuildEnvironment.useTargets = String undefined;

DETAILS

useTargets is a string of white space separated target names (i.e., names of modules that implement xdc.bld.ITarget) or regular expression patterns matching target names.

If the Build.targets array is empty at the end of the build model's configuration script, targets specified by this string are added to the build model's targets array.

In addition to module names, the distinguished string "native" is interpreted as an alias for the target specified by the nativeTarget configuration parameter.

Special values:

undefined: use the environment variable XDCTARGETS;
null: initialize the targets array to be empty; and
"": use all TI targets (i.e., "ti.targets\..*").

SEE

excludeTargets, nativeTarget

BuildEnvironment.getReleaseDescs() // module-wide

index URL

Return a description of all releases for the specified package

XDCscript usage meta-domain

BuildEnvironment.getReleaseDescs(String pname) returns Release.Desc[]

ARGUMENTS

pname — name of the package to get the release information from

DETAILS

This function allows a "package of packages" to select appropriate releases from another package based on information provided by that package.

RETURNS

array of xdc.bld.Release.Desc structures that describe the releases specified by pname's build script

THROWS

XDCException exceptions are thrown for fatal errors. The following error codes are reported in the exception message:

xdc.bld.PACKAGE_NOT_BUILT: This error is reported when a consumer tries to use a package that has not been built. Ensure that the required package has been built by the xdc tool.
xdc.bld.INVALID_PACKAGE: This error is reported when a consumer tries to use a corrupted package. Try rebuilding the package causing the problem.

SEE

xdc.bld.Release.Desc

generated on Tue, 24 Aug 2010 15:39:30 GMT