metaonly interface xdc.IPackage

Base interface implemented by all packages

If a package does not specify a function declared in IPackage, the default defined in this package is used. [ more ... ]
XDCspec summary sourced in xdc/IPackage.xdc
metaonly interface IPackage {  ...
XDCspec declarations sourced in xdc/IPackage.xdc
package xdc;
 
metaonly interface IPackage {
module-wide constants & types
    };
 
        String target// target name;
    };
module-wide config parameters
module-wide functions
}
DETAILS
If a package does not specify a function declared in IPackage, the default defined in this package is used.
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

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

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

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

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

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

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

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

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
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.getLibs( )  // module-wide

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

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

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
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.validate( )  // module-wide

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
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.
generated on Wed, 06 Jan 2010 18:40:44 GMT