metaonly interface xdc.bld.ITargetFilter
index URL

User-supplied filter of a target's command set

This interface defines a set of user-supplied methods that are invoked during the Build Model's makefile generation process. These methods can augment or modify the commands that are placed in the generated makefiles. For example, an ITargetFilter module can add pre or post build steps for virtually any generated file. [ more ... ]
XDCspec summary sourced in xdc/bld/ITargetFilter.xdc
metaonly interface ITargetFilter {  ...
instance:  ...
XDCspec declarations sourced in xdc/bld/ITargetFilter.xdc
package xdc.bld;
 
metaonly interface ITargetFilter {
module-wide constants & types
    metaonly struct GenDesc// Configuration file generation descriptor {
        String template// name of the template to expand;
        String file// the name of the file to generate;
    };
 
    metaonly struct InstDesc// ITargetFilter Instance descriptor {
        String moduleName// name of a module implementing ITargetFilter;
        Any params// params passed to ITargetFilter.create();
    };
 
    metaonly struct MacroDesc// Macro definition descriptor {
        String name// name of the macro;
        String value// the name value of the macro name;
    };
 
 
instance:
per-instance functions
    function archive// Archive command filter( container, lib, objList, archArgs, result );
    function compile// Compile command filter( container, target, goal, compArgs, result );
    function getDefs// Get table of macro definitions( );
    function getGenTab// Get table of files to be generated during configuration( prog, cfgDir, configName );
    function link// Link command filter( container, cfgBase, prog, objList, linkArgs, result );
}
DETAILS
This interface defines a set of user-supplied methods that are invoked during the Build Model's makefile generation process. These methods can augment or modify the commands that are placed in the generated makefiles. For example, an ITargetFilter module can add pre or post build steps for virtually any generated file.
Filters can:
  1. modify or augment the commands returned by a target's compile, link and archive methods via compile, link, and archive;
  2. add new definitions to the generated makefiles usable by the command added above via getDefs; and
  3. specify new files to be generated during the configuration process that may be used during or after the link process via getGenTab.
Filters are created implicitly when a target's profile (xdc.bld.ITarget.profiles) that references the filter is used. To use a filter, one must configure a profile's option set (xdc.bld.ITarget.OptionSet) in the build configuration script config.bld. It is possible to add filters to existing profiles (such as "debug" and "release") or to create entirely new profiles that utilize the filters.
When modifying existing profiles, no changes to individual packages using these profiles is required; one simply has to clean and rebuild these packages for the filters to have an effect.
By adding new profiles, one can ensure that existing build artifacts are unchanged and only those packages that want to take advantage of a filter can do so easily by adding a new build artifact that uses the new profile; for example, see xdc.bld.Library.Attrs.
 
struct ITargetFilter.GenDesc
index URL

Configuration file generation descriptor

XDCspec declarations sourced in xdc/bld/ITargetFilter.xdc
metaonly struct GenDesc {
    String template;
    // name of the template to expand
    String file;
    // the name of the file to generate
};
 
DETAILS
This structure is used to specify a new file to be generated during the configuration process.
Templates are expanded in the context of the Configuration domain; as a result, the contents of the generated file can be a function of an executable's xdc.cfg.Program object. Template names are interpreted using the xdc.findFile() method to locate the template file name. Templates can, therefore, be contained in any package located along the package path.
Names of files to be generated are always interpreted relative to the base directory of the package for which makefiles are being generated.
SEE
getGenTab
 
struct ITargetFilter.InstDesc
index URL

ITargetFilter Instance descriptor

XDCspec declarations sourced in xdc/bld/ITargetFilter.xdc
metaonly struct InstDesc {
    String moduleName;
    // name of a module implementing ITargetFilter
    Any params;
    // params passed to ITargetFilter.create()
};
 
DETAILS
This structure provides the information necessary to create an instance of an ITargetFilter.
SEE
xdc.bld.ITarget.OptionSet
 
struct ITargetFilter.MacroDesc
index URL

Macro definition descriptor

XDCspec declarations sourced in xdc/bld/ITargetFilter.xdc
metaonly struct MacroDesc {
    String name;
    // name of the macro
    String value;
    // the name value of the macro name
};
 
DETAILS
This structure is used to specify macro name-value pairs that are added to the generated makefiles. These names can be used by commands added via the filter's archive(), compile(), or link() methods.
Using symbolic values in lieu of embeddeding explicit paths or values enables the end-user to re-define these values without requiring regeneration of makefiles.
SEE
getDefs
 
per-instance config parameters
index URL

XDCscript usage meta-domain
var params = new ITargetFilter.Params;
// Instance config-params object
 
ITargetFilter.archive( )  // per-instance
index URL

Archive command filter

XDCspec declarations sourced in xdc/bld/ITargetFilter.xdc
function archive( container, lib, objList, archArgs, result );
 
ARGUMENTS
container — String
lib — xdc.bld.Library
archArgs — xdc.bld.ITarget.ArchiveGoal
result — xdc.bld.ITarget.CommandSet
DETAILS
This method is called for every archive created by the package's build script (via xdc.bld.PackageContents.addLibrary()).
 
ITargetFilter.compile( )  // per-instance
index URL

Compile command filter

XDCspec declarations sourced in xdc/bld/ITargetFilter.xdc
function compile( container, target, goal, compArgs, result );
 
ARGUMENTS
container — String
target — xdc.bld.ITarget.Module
goal — String goal file
compArgs — xdc.bld.ITarget.CompileGoal the file to compile
result — xdc.bld.ITarget.CommandSet
DETAILS
This method is called for every object created by the package's build script (via xdc.bld.Executable.addObjects(), xdc.bld.Library.addObjects(), ...).
 
ITargetFilter.getDefs( )  // per-instance
index URL

Get table of macro definitions

XDCspec declarations sourced in xdc/bld/ITargetFilter.xdc
function getDefs( );
 
DETAILS
This method is called during makefile generation to obtain a list of macro definitions that are to be added to the generated makefile. These macros can then be referenced by commands added via a filter function (archive(), compile() or link()).
RETURNS
array of MacroDesc
 
ITargetFilter.getGenTab( )  // per-instance
index URL

Get table of files to be generated during configuration

XDCspec declarations sourced in xdc/bld/ITargetFilter.xdc
function getGenTab( prog, cfgDir, configName );
 
ARGUMENTS
prog — xdc.bld.Executable or Assembly
cfgDir — String directory where generated config files are placed
configName — String base name of the configuration
DETAILS
This method is called during makefile generation to obtain a list of additional files to be generated during configuration.
RETURNS
array of GenDesc
 
ITargetFilter.link( )  // per-instance
index URL

Link command filter

XDCspec declarations sourced in xdc/bld/ITargetFilter.xdc
function link( container, cfgBase, prog, objList, linkArgs, result );
 
ARGUMENTS
container — String
cfgbase — String
prog — Executable or Assembly
objList — String
linkArgs — xdc.bld.ITarget.LinkGoal
result — xdc.bld.ITarget.CommandSet
DETAILS
This method is called for every executable created by the package's build script (via xdc.bld.PackageContents.addExecutable(), ...).
generated on Wed, 06 Jan 2010 18:40:27 GMT