interface xdc.IPackage

Packages must implement IPackage functions in the package's package.xs file. This file simply defines a function with the same name as that declared in the the this specification. For example, to implement the getLibs() function the following must appear in the package's package.xs file:

      function getLibs(prog)
      {
           ...
      }

NOTE

Since most IPackage functions can be called in any model, any access to global variables specific to a particular object model should happen only if the function is called in the context of that model. For example, the variable Program is a global variable in the Configuration Model (xdc.cfg.Program). Any access to it should happen after a check that the current model is the Configuration Model:

      if (xdc.om.$name == "cfg") {
          print(Program.build.target.name);
      }

For additional information about xdc.om, see xdc.om in the XDCscript Language Reference.

struct IPackage.BuildAttrs

index URL

Package-level attributes from the Build Object Model (BOM)

XDCspec declarations sourced in xdc/IPackage.xdc

metaonly struct BuildAttrs {

String libraries[];

// array of archive names produced by this pkg

IPackage.LibDesc libDesc[string];

// desriptors for elements in libraries

Any getLibs;

// getLibs function defined by build script

};

FIELDS

getLibs — the JavaScript function that should be used when the package participates in a program configuration script. This field contains the function specified by a package's build script

libraries — an array of archive names created by this package. Each name is a package-relative file name of an archive within the package.

libDesc — a map of library descriptors. This map is indexed by names that appear in the libraries array.

DETAILS

This structure defines a set of package-level attributes that are carried forward from the Build Model into the Configuration Model.

struct IPackage.LibDesc

index URL

Library properties from the Build Object Model (BOM)

XDCspec declarations sourced in xdc/IPackage.xdc

metaonly struct LibDesc {

String target;

// target name

String suffix;

// suffix property of the named target

};

FIELDS

target — target for which the library was built.

suffix — the suffix associated with the named target.

DETAILS

This structure defines library properties that are carried forward from the Build Model into the Configuration Model.

config IPackage.build // module-wide

index URL

The package information from the Build Object Model (BOM)

XDCspec declarations sourced in xdc/IPackage.xdc

config IPackage.BuildAttrs build;

READONLY

This parameter is set when the package is first loaded and should not be modified by any other script.

config IPackage.packageBase // module-wide

index URL

The absolute path to the package's "base" directory

XDCspec declarations sourced in xdc/IPackage.xdc

config String packageBase;

DETAILS

This parameter contains an absolute path to the directory containing the package's build script (package.bld). For example, if the package ti.bios is located in c:/packages/ti/bios, then packageBase equals c:/packages/ti/bios/.

To be robust, clients should not assume that this string ends with a directory separator.

READONLY

This parameter is set when the package is first loaded and should not be modified by any other script.

config IPackage.packageRepository // module-wide

index URL

The absolute path to the repository containing the package

XDCspec declarations sourced in xdc/IPackage.xdc

config String packageRepository;

DETAILS

This parameter contains an absolute path to the directory containing the full directory namespace of the package. For example, if the package ti.bios is located in c:/packages/ti/bios, then packageRepository equals c:/packages/.

To be robust, clients should not assume that this string ends with a directory separator.

READONLY

This parameter is set when the package is first loaded and should not be modified by any other script.

config IPackage.profile // module-wide

index URL

The profile requested by a configuration script

XDCspec declarations sourced in xdc/IPackage.xdc

config String profile;

DETAILS

This parameter is set by configuration scripts to convey additional information to the package about the libraries being requested from this package; in particular, it names a specific profile supported by this package (see xdc.bld.ITarget.profiles).

Package getLibs() functions should refer to this parameter in lieu of the program's build.profile. This allows configuration scripts to selectively request debug or release libraries on a per package basis, for example.

  function getLibs(prog)
  {
      if (this.profile == "debug") {
          ...
      }
  }

If this parameter is not set by the configuration script, it is initialized to xdc.cfg.Program.build.profile prior to generating and configuration files; i.e., the package's getLibs() function can assume that this field is always set and defaults to the profile used to build the executable.

IPackage.close() // module-wide

index URL

Close this package after user scripts complete

XDCspec declarations sourced in xdc/IPackage.xdc

function close();

DETAILS

This function is called to allow the package to modify its state based on the results of the user's script. It can optionally redefine configuration parameters or even throw exceptions to prevent the configuration step from completing, for example.

Other packages and modules, including the modules in the package, can change the configuration parameters of any module in the package, after this function was called. Therefore, this function cannot be used to validate state of the package and of the whole configuration. Validation should be done in validate().

For all packages A and B, if A requires B, then package A is closed before package B.

The default implementation of this function is a nop.

CONTEXT

this: The current package's xdc.IPackage.Module object immediately after the program's configuration script has completed and before validation is started.

RETURNS

Returns nothing.

THROWS

Error exceptions are thrown for fatal errors.

NOTE

This function can be called in any model, so any access to global variables specific to a particular object model should happen only if the function is called in the context of that model. For example, the variable Program is a global variable in the Configuration Model (xdc.cfg.Program). Any access to it should happen after a check that the current model is the Configuration Model:

      if (xdc.om.$name == "cfg") {
          print(Program.build.target.name);
      }

For additional information about xdc.om, see xdc.om in the XDCscript Language Reference.

IPackage.exit() // module-wide

index URL

Exit this package after the model has been successfully validated

XDCspec declarations sourced in xdc/IPackage.xdc

function exit();

DETAILS

The default implementation of this function is a nop.

CONTEXT

this: The current package's xdc.IPackage.Module object immediately after the program's configuration script has completed and after generation has completed.

RETURNS

Returns nothing.

THROWS

Error exceptions are thrown for fatal errors.

NOTE

      if (xdc.om.$name == "cfg") {
          print(Program.build.target.name);
      }

For additional information about xdc.om, see xdc.om in the XDCscript Language Reference.

IPackage.getLibs() // module-wide

index URL

Get the libraries necessary to use this package

XDCspec declarations sourced in xdc/IPackage.xdc

function getLibs(prog);

ARGUMENTS

prog — the configuration model program object (xdc.cfg.Program) after the program's configuration script has completed.

DETAILS

This function is called during the configuration model's generation phase (after a program's configuration script completes and all imported packages are closed) and is responsible for returning a list of libraries (or object files) that are needed to link the program being configured.

If the package produces one (or no) library for the target for which the executable is being built, the default implementation of this function simply returns the name of this library (or null).

If the package produces more than one library for the given target, the default implementation of this function returns the following library name:

          lib/<package_name>.a<target_suffix>

where <package_name> is the name of the package (e.g., "ti.bios") and <target_suffix> is the xdc.bld.ITarget.suffix property of the target used to build the executable.

CONTEXT

this: The current package's xdc.IPackage.Module object after the program's configuration script has completed.
Program: The Configuration model program object (xdc.cfg.Program) after the program's configuration script has completed.

RETURNS

Returns a string of ';' delimited object (or library) file names that are added to the list of things to link to create the program. The file names are absolute or relative to the package's base. All white space is treated as part of the file name. If the files named do not exist, a fatal error occurs and configuration terminates.

If null or empty (""), then no libraries or objects are required for this package.

THROWS

Error exceptions are thrown for fatal errors.

IPackage.getSects() // module-wide

index URL

Get package-specific linker section data

XDCspec declarations sourced in xdc/IPackage.xdc

function getSects();

DETAILS

This function is called during the configuration model's generation phase (after a program's configuration script completes) and is responsible for returning a template file name that is used to generate package-specific linker command file statements.

CONTEXT

this: The current package's xdc.IPackage.Module object after the program's configuration script has completed.
Program: The Configuration model program object (xdc.cfg.Program) after program's configuration script has completed and all packages have validated the correctness of the configuration.

RETURNS

Returns the path name of template file. The path name must relative to the package path or an absolute path.

If null is returned, no data is generated.

The template is evaluated in a context where the this pointer is the package object.

THROWS

Error exceptions are thrown for fatal errors.

IPackage.init() // module-wide

index URL

Initialize this package when first imported

XDCspec declarations sourced in xdc/IPackage.xdc

function init();

DETAILS

This function is called to initialize the package within any model. It is called just once (when the package is first imported) so there is no need to explicitly check for prior invocation.

The default implementation of this function is a nop.

CONTEXT

this: The current package's xdc.IPackage.Module object before any model-specific user script runs (e.g. a program's configuration script), after the package's package.xs script is run and all the package's modules are created, and before the package is added to xdc.om.$packages (the Object Model's package array)

RETURNS

Returns nothing.

THROWS

Error exceptions are thrown for fatal errors.

NOTE

      if (xdc.om.$name == "cfg") {
          print(Program.build.target.name);
      }

For additional information about xdc.om, see xdc.om in the XDCscript Language Reference.

IPackage.validate() // module-wide

index URL

Validate this package after the model's state is "sealed"

XDCspec declarations sourced in xdc/IPackage.xdc

function validate();

DETAILS

This function is called to validate the package's state in the curent model. It can verify semantic constraints and optionally throw exceptions to prevent the configuration step from completing.

For example, a package that needs to assert incompatibility with certain versions of prerequisite packages can check the versions in this function and throw an exception if they are known to be incompatible with the current package.

This method must not modify the model.

The default implementation of this function is a nop.

CONTEXT

this: The current package's xdc.IPackage.Module object immediately after the program's configuration script has completed and before generation started.

RETURNS

Returns nothing.

THROWS

Error exceptions are thrown for fatal errors.

NOTE

      if (xdc.om.$name == "cfg") {
          print(Program.build.target.name);
      }

For additional information about xdc.om, see xdc.om in the XDCscript Language Reference.

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