metaonly interface xdc.bld.ITarget

The interface between code generation tool-chains and the XDC Build Engine

This interface defines an abstract interface that must be supported by a compiler tool-chain in order to be used in an XDC build environment. This interface allows the XDC Build engine to treat all compiler tool chains uniformly; thus, it is possible to add support for a new compiler without making *any* changes to the build engine.
XDCspec summary sourced in xdc/bld/ITarget.xdc
metaonly interface ITarget {  ...
XDCspec declarations sourced in xdc/bld/ITarget.xdc
package xdc.bld;
 
metaonly interface ITarget {
module-wide constants & types
    typedef String StringArray// [];
 
        String files// String of files to archive;
        String profile// index into profiles map;
        String opts// goal specific archiver options;
    };
 
    };
 
        String profile// index into profiles map;
    };
 
        String aopts// goal specific ASM options;
    };
 
    metaonly struct DebugGen// Debugger integration support {
        String execPattern// exec file name pattern;
    };
 
    };
 
        String files// string of files to link with;
        String profile// index into profiles map;
        String opts// goal specific linker options;
        Bool isRom// reflects the isRom attribute;
    };
 
    metaonly struct Model// Target runtime model {
        String endian// endian-ness of this target;
        String codeModel// target-specific code model;
        String dataModel// target-specific data model;
    };
 
        String linkOpts// profile-specific linker opts;
    };
 
        ITarget.TypeInfo t_IArg;
        ITarget.TypeInfo t_Char;
        ITarget.TypeInfo t_Double;
        ITarget.TypeInfo t_Float;
        ITarget.TypeInfo t_Fxn;
        ITarget.TypeInfo t_Int;
        ITarget.TypeInfo t_Int8;
        ITarget.TypeInfo t_Int16;
        ITarget.TypeInfo t_Int32;
        ITarget.TypeInfo t_Int40;
        ITarget.TypeInfo t_Int64;
        ITarget.TypeInfo t_Long;
        ITarget.TypeInfo t_LDouble;
        ITarget.TypeInfo t_LLong;
        ITarget.TypeInfo t_Ptr;
        ITarget.TypeInfo t_Short;
        ITarget.TypeInfo t_Size;
    };
module-wide config parameters
    readonly config String isa// CPU Instruction Set Architecture (ISA);
    readonly config ITarget.Model model// Run-time model;
    readonly config String name// Nickname for this target;
    readonly config String rts// Name of a run-time support package to include;
    readonly config String sectMap// Output section name to segment type mapping[string];
    readonly config String stdInclude// Standard C/C++ types header;
        t_IArg: {
            size: 0,
            align: 0
        },
        t_Char: {
            size: 0,
            align: 0
        },
        t_Double: {
            size: 0,
            align: 0
        },
        t_Float: {
            size: 0,
            align: 0
        },
        t_Fxn: {
            size: 0,
            align: 0
        },
        t_Int: {
            size: 0,
            align: 0
        },
        t_Int8: {
            size: 0,
            align: 0
        },
        t_Int16: {
            size: 0,
            align: 0
        },
        t_Int32: {
            size: 0,
            align: 0
        },
        t_Int40: {
            size: 0,
            align: 0
        },
        t_Int64: {
            size: 0,
            align: 0
        },
        t_Long: {
            size: 0,
            align: 0
        },
        t_LDouble: {
            size: 0,
            align: 0
        },
        t_LLong: {
            size: 0,
            align: 0
        },
        t_Ptr: {
            size: 0,
            align: 0
        },
        t_Short: {
            size: 0,
            align: 0
        },
        t_Size: {
            size: 0,
            align: 0
        }
    };
 
    config String execExt// Extension for executables;
        [
            ".asm",
            {
                suf: ".asm",
                typ: "asm"
            }
        ],
        [
            ".c",
            {
                suf: ".c",
                typ: "c"
            }
        ],
        [
            ".cpp",
            {
                suf: ".cpp",
                typ: "cpp"
            }
        ],
        [
            ".cxx",
            {
                suf: ".cxx",
                typ: "cpp"
            }
        ],
        [
            ".C",
            {
                suf: ".C",
                typ: "cpp"
            }
        ],
        [
            ".cc",
            {
                suf: ".cc",
                typ: "cpp"
            }
        ]
    ];
        [
            "release",
            { }
        ],
        [
            "debug",
            { }
        ]
    ];
module-wide functions
}
 
typedef ITarget.StringArray
XDCspec declarations sourced in xdc/bld/ITarget.xdc
typedef String StringArray[];
 
 
struct ITarget.ArchiveGoal

The goal specification passed to the archive function

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct ArchiveGoal {
    String base;
    // base name of the source and destination
    String dstPrefix;
    // directory prefix of destination file
    String dstSuffix;
    // suffix of destination file; e.g., ".a62"
    String files;
    // String of files to archive
    String profile;
    // index into profiles map
    String opts;
    // goal specific archiver options
};
 
SEE
 
struct ITarget.CommandSet

The commands necessary to create a specified goal

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct CommandSet {
    String msg;
    // brief message describing subsequent commands
    String cmds;
    // commands necessary to generate goal
    String path[];
    // host-independent representation of PATH
    String envs[];
    // environment variable settings for the cmds
};
 
FIELDS
msg — a brief synopsis of the commands specified by cmds; this string is output in lieu of cmds when building in "non-verbose" mode.
cmds — a single string of commands that must be executed to complete the specified operation. Multiple commands may be specified by separating each command with the '\n' character.
To facilitate the creation of "portable" makefiles and to simplify the implementation of targets, certain distinguished "macros" may be embedded in this string. The build engine replaces these macros with the values described below.
$(rootDir)
the target's rootDir configuration parameter
$(packageBase)
the target package's xdc.IPackage.packageBase property
$(XDCINCS)
a set of "-I" options that names each repository in the package path
envs — an array of "name=value" strings that represent environment variables that are defined prior to the execution of the commands specified by cmds
path — an array of directory names that are used to compose the PATH environment variable that is in effect when the commands specified by cmds are run.
DETAILS
This structure is the return value of the compile, link and archive functions. This value is then used to generate a makefile or any other files necessary to generate a specified goal.
SEE
 
struct ITarget.CompileGoal

The goal specification passed to the compile function

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct CompileGoal {
    String base;
    // base name of the source and destination
    String dstPrefix;
    // directory prefix of destination file
    String dstSuffix;
    // suffix of destination file; e.g., ".o62"
    String srcSuffix;
    // optional suffix of source file; e.g., ".c"
    String srcPrefix;
    // optional directory prefix of source file
    String profile;
    // index into profiles map
    ITarget.CompileOptions opts;
    // goal specific compiler options
    Bool configOpts;
    // true if compiling the generated C config file
};
 
SEE
 
struct ITarget.CompileOptions

Options passed to the compiler/assembler

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct CompileOptions {
    String aopts;
    // goal specific ASM options
    String copts;
    // goal specific C compiler options
    String cfgcopts;
    // goal specific C config file options
    String defs;
    // goal specific C/ASM definition options
    String incs;
    // goal specific C/ASM include options
};
 
FIELDS
aopts — a string of target-specific assembler options
copts — a string of target-specific C/C++ compiler options
cfgcopts — a string of C/C++ compiler options for C config file
defs — a string of macro definitions each of the form "-Dname=value" separated by white space
incs — a string of include directories each of the form "-Idir" separated by white space
PREDEFINED MACROS
The XDC Build Engine automatically adds several predefined macros via -D definitions that enable conditional compilation of source files based on build-specific attributes.
xdc_bld__profile_{profile_name}
this symbol is always defined and {profile_name} is the compile goal's (see CompileGoal) profile name.
In addition, each target defines a set of macros that enable clients to portably support big/little endian targets, for example. These macros are indirectly included by sources that include xdc/std.h; see xdc.
SEE
 
struct ITarget.DebugGen

Debugger integration support

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct DebugGen {
    String execTemplate;
    // debugger template for executable
    String execPattern;
    // exec file name pattern
    String packageTemplate;
    // debugger template for package
    String packagePattern;
    // package file name pattern
};
 
DETAILS
This structure specifies additional files that are generated in order to support integration with a debugger. For example, the default setting for TI targets specifies the generation of CCS project files that allow one to easily debug executables that have been constructed from multiple packages.
There are two "types" of debug support files that are generated; one for the package as a whole, and one for each executable. Since packages may contain portable sources that are built for more than one target, a "package-level" file is generated for each target used in the package. A separate file is generated for each executable built within the package.
The execTemplate and packageTemplate fields name a template that is expanded in the context of the config model and the build model, respectively. These fields should be set to a file name string which is relative to the package path; e.g., the string "ti/targets/cc_exec.xdt" refers to the file "cc_exec.xdt" in the ti.targets package located along the package path.
Preconditions for the execTemplate:
this
the configured program object (xdc.cfg.Program); i.e., the program object *after* the program's configuration script completes.
$args
array of arguments passed to the template
$args[1]
the name of the executable being produced for this configuration.
environment
hash table of XDC global parameters; e.g., "xdc.path", "xdc.root", ...
Preconditions for the packageTemplate:
this
the "package contents" object (i.e., xdc.bld.PackageContents) *after* the package's build script (package.bld) completes.
$args
array of arguments passed to the template
$args[0]
the target (a module implementing the xdc.bld.ITarget interface)
$args[1]
hash-table of all package sources
environment
hash table of XDC global parameters; e.g., "xdc.path", "xdc.root", ...
The execPattern and packagePattern fields are expressions that are expanded prior to template expansion to determine the name of the output file. Expressions of the form "$(name)" within the pattern string are expanded if "name" is one of the built-in variables listed below.
Built-in variables for execPattern:
cfgName
the name of the generated configuration file (without any directory prefix);
cfgDir
the name of the directory containing the config file;
exeName
the name of the executable file (without any directory prefix);
exeDir
the directory containing the executable file.
Both the exeDir and cfgDir are relative to the directory containing the package.bld script.
Built-in variables for packagePattern:
pkgName
the package's name (e.g., "ti.targets");
trgName
the target's name property;
trgSuffix
the target's suffix property.
SEE
 
struct ITarget.Extension

File extension to file type association

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct Extension {
    String suf;
    // file extension (including any '.')
    String typ;
    // type of this file; e.g., "c", "asm", ..
};
 
FIELDS
suf — the file extension including any '.' characters
typ — the type of the file having this extension. Allowable file type identifiers include:
"c"
C language source file
"asm"
assembly language source file
"cpp"
C++ language source file
DETAILS
This structure is used by the Build Engine to determine whether a file should be treated as C++, C, or assembly language source.
SEE
 
struct ITarget.LinkGoal

The goal specification passed to the link function

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct LinkGoal {
    String base;
    // base name of the source and destination
    String dstPrefix;
    // directory prefix of destination file
    String dstSuffix;
    // suffix of destination file; e.g., ".x62"
    String files;
    // string of files to link with
    String profile;
    // index into profiles map
    String opts;
    // goal specific linker options
    Bool dllMode;
    // true if we're linking an assembly
    Bool isRom;
    // reflects the isRom attribute
};
 
SEE
 
struct ITarget.Model

Target runtime model

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct Model {
    String endian;
    // endian-ness of this target
    String codeModel;
    // target-specific code model
    String dataModel;
    // target-specific data model
    Bool shortEnums;
    // if true, enums are packed into smallest integral type
};
 
FIELDS
— (endian) this string specifies the endianess of the generated code. Valid values include:
"big"
big endian
"little"
little endian
null
unspecified
(codeModel) this string specifies a target-specific code size model. Valid values include:
"near"
C54 near mode
"far"
C54 far mode
undefined
unspecified
(dataModel) this string specifies a target-specific data size model. Valid values include:
"large"
C55, C28 large model
undefined
unspecified
(shortEnums) this flag specifies if a target fits the values of an enumeration into the smallest integer type that can accept all values. If that is the case, this flag must be set to true. If all values are the size of an Int, this flag can be either set to false or left unspecified.
SEE
 
struct ITarget.OptionSet

Collection of tool-chain options

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct OptionSet {
    ITarget.CompileOptions compileOpts;
    // profile-specific compiler opts
    String linkOpts;
    // profile-specific linker opts
    String archiveOpts;
    // profile-specific archiver opts
    ITargetFilter.InstDesc filters[];
    // ITargetFilter instance descs
};
 
FIELDS
compilerOptions — a set of compiler/assembler options
linkOpts — a string of target-specific linker options
archiveOpts — a string of target-specific archiver options
filters — an array of filters applied (in order) to tool-chain commands
DETAILS
This structure is used to define a collection of tool-chain options that are used as a group to achieve some effect supported by the tool-chain. For example, some compilers require that specific options be passed to the compiler *and* linker in order to generate execution profile information or code coverage statistics.
SEE
 
struct ITarget.StdTypes

Standard base types supported by all targets

XDCspec declarations sourced in xdc/bld/ITarget.xdc
metaonly struct StdTypes {
    ITarget.TypeInfo t_IArg;
    ITarget.TypeInfo t_Char;
    ITarget.TypeInfo t_Double;
    ITarget.TypeInfo t_Float;
    ITarget.TypeInfo t_Fxn;
    ITarget.TypeInfo t_Int;
    ITarget.TypeInfo t_Int8;
    ITarget.TypeInfo t_Int16;
    ITarget.TypeInfo t_Int32;
    ITarget.TypeInfo t_Int40;
    ITarget.TypeInfo t_Int64;
    ITarget.TypeInfo t_Long;
    ITarget.TypeInfo t_LDouble;
    ITarget.TypeInfo t_LLong;
    ITarget.TypeInfo t_Ptr;
    ITarget.TypeInfo t_Short;
    ITarget.TypeInfo t_Size;
};
 
SEE
 
config ITarget.alignDirectiveSupported  // module-wide

The compiler supports an align directive

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config Bool alignDirectiveSupported = false;
 
 
config ITarget.base  // module-wide

A target that this target is based upon

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config ITarget.Module base;
 
DETAILS
If non-null, this target shares the same tool-chain of the specified base target. This parameter is used to determine various default values for target configuration parameters. For example, the default setting of rootDir is the value of the base's rootDir setting.
 
config ITarget.bitsPerChar  // module-wide

The number of bits in a variable of type char

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config Int bitsPerChar = 8;
 
DETAILS
This constant allows one to determine the precise number of bits in each of the types specified in the stdTypes map. For example, the number of bits in the target t's int type is
      t.stdTypes.t_Int.size * t.bitsPerChar
 
config ITarget.isa  // module-wide

CPU Instruction Set Architecture (ISA)

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config String isa;
 
DETAILS
This parameter is used to identify a set of targets that produce code for a common ISA. This is used by build scripts that need to build for all targets that support a particular device.
For example, the build script for a package that is designed for the TMS32064xx (and no other CPU) can easily specify that it should be built for all targets that generate code for the TMS320C64xx without having to specify a specific target. This allows the user to add new targets (big endian, little endian, different compilers, etc.) that build for the TMS320C64xx without having to modify the package's build script.
Note that this field should not be confused with platform ISA names; this field is defined by target tool-chains and may differ from the names given by a CPU device.
SEE
 
config ITarget.model  // module-wide

Run-time model

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config ITarget.Model model;
 
DETAILS
This structure identifies a particular run-time model used by the compiler to generate instructions.
 
config ITarget.name  // module-wide

Nickname for this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config String name;
 
DETAILS
This name is typically the name of the module without the package name prefix. Thus, it is not necessarily globally unique.
Use the $name property of the module to get a globally unique name for the target.
 
config ITarget.os  // module-wide

Name of OS required to run programs built for this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config String os;
 
DETAILS
Native executables are run by the host OS. This OS often defines runtime interfaces that all executables (implicitly or explicitly) use.
If os is undefined, then no OS is required.
 
config ITarget.rts  // module-wide

Name of a run-time support package to include

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config String rts;
 
DETAILS
Development environments often provide a set of common run-time support functions that all other code can easily utilize; e.g., some means for performing a "printf", normal program termination with "exit status", etc. If the rts parameter is non-null, it is the name of a package that is implicitly imported when building any executable that is built using this target. If rts is undefined, no rts package is imported.
This parameter makes it possible for the target producer to name a package that provides a target-specific implementation of a runtime support interface. Clients of a target do not need to explicitly name a target specific rts implementation; thus, it is not possible for the client to inadvertently name the wrong (or an incompatible) rts implementation.
Note: this package is *NOT* included if the executable's xdc.bld.Executable.attrs.rtsName attribute is set to null; see xdc.bld.Executable.Attrs. It is also not included if the executable is a legacy DSP/BIOS program.
 
config ITarget.sectMap  // module-wide

Output section name to segment type mapping

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config String sectMap[string];
 
DETAILS
This hash table is used to determine whether a particular object file output section (".text", ".stack", etc.) requires 'data', 'code' or 'stack' memory segment.
This sectMap is referenced by linker command file templates during generation to create linker command files. The Platform defines the default memory segments for code and data, and based on this map and the default segments, the linker command file template places an output section into a physical memory segment.
Note that the xdc.cfg.Program object and the xdc.platform.IPlatform instance have a sectMap parameter. Both the Program's and IPlatform's sectMap can augment and/or override the placement for a section, but xdc.cfg.Program.sectMap takes precedence. Therefore, this sectMap and the default segments from the platform define an initial section map which is then augmented by the Program's and IPlatform's section map.
 
config ITarget.stdInclude  // module-wide

Standard C/C++ types header

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config String stdInclude;
 
DETAILS
This string identifies a header containing the C/C++ definitions required to enable use of xdc/std.h in C/C++ sources; see xdc.
The value of this string is used by xdc/std.h to include target-specific definitions of the types Int8, Int16, etc. In addition, this header supplies target-specific definitions of the predefined xdc_target__* macros required by xdc/std.h.
Since this header must supply target-specific values for target-independent names the structure of this header is usually of the form:
      // if target macros are not already defined, 
      #if !defined(xdc_target_macros_include__)
          // include target-specific definitions
          #if defined(TARGET1)
              #include "target1.h"
          #elif defined(TARGET2)
              #include "target2.h"
          #elif ...
              :
          #else
              #error unsupported target
          #endif
      #endif
      // include common definitions
          :
The check of the symbol xdc_target_macros_include__ exists to allow others that define new targets to include this header to get common definitions for a family of related targets.
To simplify the creation of the target-specific header files, the template file stddefs.xdt in this package can be used to automatically generate the required definitions from each target's .xdc specification.
 
config ITarget.stdTypes  // module-wide

Size and alignment for standard base types

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config ITarget.StdTypes stdTypes = {
    t_IArg: {
        size: 0,
        align: 0
    },
    t_Char: {
        size: 0,
        align: 0
    },
    t_Double: {
        size: 0,
        align: 0
    },
    t_Float: {
        size: 0,
        align: 0
    },
    t_Fxn: {
        size: 0,
        align: 0
    },
    t_Int: {
        size: 0,
        align: 0
    },
    t_Int8: {
        size: 0,
        align: 0
    },
    t_Int16: {
        size: 0,
        align: 0
    },
    t_Int32: {
        size: 0,
        align: 0
    },
    t_Int40: {
        size: 0,
        align: 0
    },
    t_Int64: {
        size: 0,
        align: 0
    },
    t_Long: {
        size: 0,
        align: 0
    },
    t_LDouble: {
        size: 0,
        align: 0
    },
    t_LLong: {
        size: 0,
        align: 0
    },
    t_Ptr: {
        size: 0,
        align: 0
    },
    t_Short: {
        size: 0,
        align: 0
    },
    t_Size: {
        size: 0,
        align: 0
    }
};
 
DETAILS
The values of size are the values returned by the target-specific sizeof() operator applied to the specified type (as defined by the C language). The align value is the number of chars used in the alignment of the specified type.
 
config ITarget.suffix  // module-wide

Suffix appended to all objs, libraries, and executable

XDCspec declarations sourced in xdc/bld/ITarget.xdc
readonly config String suffix;
 
DETAILS
All files generated by this target (object files, archives, executables, etc.) have file names whose extensions end with suffix. In particular, targets create files with the following extensions:
".a<suffix>"
archive files (i.e., libraries)
".o<suffix>"
object files
".s<suffix>"
assembly language source (see scompile())
".x<suffix>"
executable files This suffix should be chosen to globally and uniquely identify the EABI (Embedded Application Binary Interface) of the objects produced by this target. Targets with the same suffix should should produce 100% EABI compatible objects and, targets with different suffixes should produce objects with incompatible EABIs.
SEE
 
config ITarget.compatibleSuffixes  // module-wide

Array of suffixes used by targets compatible with this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config String compatibleSuffixes[];
 
DETAILS
This array is used to identify a set of targets that produce code that can be linked with code produced by this target, where the order of suffixes defines the order of preferrence. This parameter is used by findSuffixes().
For example, an Arm target which builds for v6 architecture might have the following values in its compatibleSuffix: ["v5T", "MV470"]. This means that code produced by targets with suffixes "v5T' and "MV470" can be linked with code produced by that target, and that "v5T" code is more preferred than "MV470" code.
 
config ITarget.debugGen  // module-wide

Debugger/IDE file generation support

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config ITarget.DebugGen debugGen;
 
DETAILS
This parameter allows one to automatically generate files that can be used by an IDE to more easily debug (and possibly rebuild) specified goals.
To avoid unnecessary build time overhead, these files are not always generated; by default, they are only generated for "debug" profiles. The generation of these files is controlled by the xdc.cfg.Program.gen configuration parameter. To force these files to be generated for a particular executable, add the following line to the executable's program configuration script:
	    Program.gen.debuggerFiles = true;
It is also possible to disable the generation of selected files by setting the appropriate fields of DebugGen to null in your config.bld script.
 
config ITarget.execExt  // module-wide

Extension for executables

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config String execExt;
 
DETAILS
Operating systems and tools often have a strong preference for a specific extension for executables; e.g., Windows expects executables to have the extension ".exe". If this parameter is set, executables will be given the specified extension instead of the default ".x<suffix>", where <suffix> is the target's suffix parameter.
The execExt is an expression that is expanded prior to use. Expressions of the form "$(name)" within the pattern string are expanded if "name" is one of the built-in variables listed below.
Built-in variables for execExt:
trgName
the target's name property
trgSuffix
the target's suffix property
platPName
the executable's platform package name
platIName
the executable's platform instance name
EXAMPLE
If you want to build a portable executable for multiple targets side-by-side and you want (or need) to use a fixed extension such as ".out" for all executables, setting execExt to "_$(trgSuffix).out" for all targets ensures that all generated executables will have unique names and yet share a common extension of ".out".
 
config ITarget.extensions  // module-wide

File extensions recognized by this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config ITarget.Extension extensions[string] = [
    [
        ".asm",
        {
            suf: ".asm",
            typ: "asm"
        }
    ],
    [
        ".c",
        {
            suf: ".c",
            typ: "c"
        }
    ],
    [
        ".cpp",
        {
            suf: ".cpp",
            typ: "cpp"
        }
    ],
    [
        ".cxx",
        {
            suf: ".cxx",
            typ: "cpp"
        }
    ],
    [
        ".C",
        {
            suf: ".C",
            typ: "cpp"
        }
    ],
    [
        ".cc",
        {
            suf: ".cc",
            typ: "cpp"
        }
    ]
];
 
DETAILS
This is a user modifiable table used to customize file extensions recognized by each target.
For example, to add a new assembly language extension, say ".s64", to the target ti.targets.C64P, add the following lines to the build model startup script:
      var C64P = xdc.module('ti.targets.C64P');
      C64P.extensions[".s64"] = {
          suf: ".s64", typ: "asm"
      };

  Note that individual targets may add additional language types.

  It is also possible to remove default extensions.  For example, to
  remove the "`.asm`" extension from the target `ti.targets.C64P`, add
  the following lines to the build model startup script:
      var C64P = xdc.module('ti.targets.C64P');
      delete C64P.extensions[".asm"];
 
config ITarget.platform  // module-wide

The default platform name for this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config String platform;
 
DETAILS
Build scripts often build for just one platform per target. This parameter allows one to establish a default platform for each target in a build.
If this parameter is null or undefined and platforms array is non-empty, it is initialized to be the first element of the platforms array (i.e., platforms[0]).
 
config ITarget.platforms  // module-wide

A set of platforms that can support this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config String platforms[] = [ ];
 
DETAILS
Some build scripts build executables for "all" platforms; e.g., regression test suites. This parameter allows one to establish a set of platforms that build scripts can legitimately use to create executables, for example.
If this array is empty (i.e., has length 0) and platform is non-null, platforms is initialized to an array of one element equal to platform.
 
config ITarget.profiles  // module-wide

Profiles supported by this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config ITarget.OptionSet profiles[string] = [
    [
        "release",
        { }
    ],
    [
        "debug",
        { }
    ]
];
 
DETAILS
A profile is a collection of tool options used to create a library or executable that supports a certain "flavor" of library or executable; e.g., "debug" or "release".
Some profile names are supported by all targets even though the targets use different compilers (and therefore different options). These profile names makes it possible for a package to build libraries or executables in a "debug" (or "release") profile independent of the target, for example.
All targets are required to support "debug" and "release" profile names.
Profile options are added to beginning of any goal specific options specified by the user before being passed to the target.
 
config ITarget.rootDir  // module-wide

Installation directory for this target's code generation tools

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config String rootDir;
 
DETAILS
Since each target potentially "wraps" a different compiler tool-chain and each tool-chain will, in general, assume a different physical design for the installation of the compiler and its associated libraries and headers, one must consult each specific target to know how to set this parameter.
If the base parameter is null, this parameter *must* be set by the user; otherwise, rootDir defaults to the value base.rootDir.
 
config ITarget.version  // module-wide

The Compatibility Key associated with this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config String version;
 
READONLY
This value is automatically computed by the XDC Build Engine by executing the getVersion() function after package.bld completes but prior to generating package.mak.
 
config ITarget.versionMap  // module-wide

Map of compiler version numbers to compatibility keys

XDCspec declarations sourced in xdc/bld/ITarget.xdc
config String versionMap[string] = [ ];
 
DETAILS
versionMap is a user modifiable table used to map tool-chain version numbers to Compatibility Keys.
Each target defines the format of the tool-chain version obtained from the tool-chain. The user can then map new tool-chain version strings to an appropriate compatibility key.
Each target must respect the mapping defined by this table; i.e., if the user supplies a compatibility key in this map, it must be returned when getVersion() is called.
Thus, it is possible for the user to assert that any two compiler tool chains should be treated as equivalent (or incompatible) by mapping their version numbers to identical (incompatible) compatibility keys.
SEE
 
ITarget.archive( )  // module-wide

Create an archive

XDCspec declarations sourced in xdc/bld/ITarget.xdc
 
ARGUMENTS
goal — the ArchiveGoal defining the archive to build.
DETAILS
This function is called during makefile generation to convert build goals into specific commands that generate the specified goal.
RETURNS
This function returns a CommandSet. If non-null, this object defines the commands that must be executed to create the specified object file. If null, then goal can not be achieved.
THROWS
Error exceptions are thrown for fatal errors.
 
ITarget.compile( )  // module-wide

Compile a source file into an object file

XDCspec declarations sourced in xdc/bld/ITarget.xdc
 
ARGUMENTS
goal — a CompileGoal that specifies what file to compile, the output file name, and any goal-specific options to use
DETAILS
This function is called during makefile generation to convert build goals into specific commands that generate the specified object file goal.
RETURNS
This function retuns a CommandSet. If non-null, this object defines the commands that must be executed to create the specified object file. If null, then goal can not be achieved.
THROWS
Error exceptions are thrown for fatal errors.
 
ITarget.findSuffix( )  // module-wide

Find the suffix that is compatible with this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
function findSuffix( pkg );
 
ARGUMENTS
pkg — a package object or an array of target suffix strings (see suffix).
DETAILS
This function determines the list of targets supported by the package given as the argument. From that list, this function returns the suffix of a target that is compatible with this target. Compatibility in this case means that object files created by a target having the suffix returned by this function can be linked into an executable produced using this target. In the case where more than one suffix is compatible, this function returns a suffix in the following order of preference:
  1. if this target's suffix is in the list, that suffix is returned.
  2. suffixes from compatibleSuffixes are matched against the list from the first to the last, and the first one with the match is returned.
RETURNS
This function returns the suffix string of a target compatible with this target or null if pkg does not support any target compatible with this target.
 
ITarget.getISAChain( )  // module-wide

Get this target's ISA "is compatible with" relation

XDCspec declarations sourced in xdc/bld/ITarget.xdc
function getISAChain( isa );
 
ARGUMENTS
isa — the ISA identifier string for the ISA to lookup; if null then the target's ISA is used (ITarget.isa).
DETAILS
Returns an array of ISA names (including this target's ISA) that represents the "is a" relation between ISA's. The array starts with the most general ISA and ends with this target's ISA or with the optionally specified argument. This relation is used to:
  1. pre-define macro definitions that enable code to be conditionally compiled based on compatible versions of a target's ISA.
  2. locate appropriate source files during makefile generation; each ISA named in a chain causes the extensions ".s"isa to be added to the ITarget.extensions table (in the reverse order that they appear in the chain). For example, if a target's ISA is "64P" and the returned chain is ["62", "64", "64P"], the following assembly language suffixes are added to the target's extensions table: ".s64P", ".s64", ".s62".
  3. determine the assembly language suffix used during legacy BIOS configuration; the first element of the target's ISA chain defines the suffix. For example, if a target's ISA is "64P" and the returned chain is ["62", "64", "64P"], the assembly suffix is ".s62".
This relation may also be used in the future to help validate combinations of targets and platforms; a target's CPU ISA must appear on the chain specified by the platform's CPU ISA.
RETURNS
This function returns an array of ISA strings where the last string is the optionally specified ISA string or this target's ISA, and the first string is the "base" ISA in the is source compatible" relationship. If the specified ISA string is not in this target's chain of compatible targets, null is returned.
THROWS
Error exceptions are thrown for fatal errors.
 
ITarget.getVersion( )  // module-wide

Get a target-specific Compatibility Key string

XDCspec declarations sourced in xdc/bld/ITarget.xdc
String getVersion( );
 
DETAILS
This function is called during makefile generation to obtain a target-specific Compatibility Key string. This string is of the form:
      "<pkg>.<mod>{<d0>,<d1>,<d2>,<d3>"
where, <pkg>.<mod> is the name of the target, and <d0>, <d1>, etc. forms a Compatibility Key.
RETURNS
This function returns a string that encodes the name of the target and its Compatibility Key.
THROWS
Error exceptions are thrown for fatal errors.
 
ITarget.link( )  // module-wide

Link object files to produce an executable

XDCspec declarations sourced in xdc/bld/ITarget.xdc
 
ARGUMENTS
goal — a LinkGoal that specifies the output file name, a list of files to link with, and any goal-specific options to use
DETAILS
This function is called during makefile generation to convert build goals into specific commands that generate the specified goal.
RETURNS
This function returns a CommandSet. If non-null, this object defines the commands that must be executed to create the specified object file. If null, then goal can not be achieved.
THROWS
Error exceptions are thrown for fatal errors.
 
ITarget.scompile( )  // module-wide

Compile a source file into an assembly language file

XDCspec declarations sourced in xdc/bld/ITarget.xdc
ITarget.CommandSet *scompile( ITarget.CompileGoal *goal );
 
ARGUMENTS
goal — a CompileGoal that specifies what file to compile, the output file name, and any goal-specific options to use
DETAILS
This function is called during makefile generation to convert build goals into specific commands that generate the specified assembly language source goal.
RETURNS
This function returns a CommandSet. If non-null, this object defines the commands that must be executed to create the specified assembly language file. If null, then goal can not be achieved or is unnecessary (e.g., because the source file is already an asm file).
THROWS
Error exceptions are thrown for fatal errors.
 
ITarget.selectSuffix( )  // module-wide

Select the suffix that is compatible with this target

XDCspec declarations sourced in xdc/bld/ITarget.xdc
String selectSuffix( ITarget.StringArray suffixList );
 
ARGUMENTS
suffixList — an array of target suffix strings (see suffix).
DETAILS
From a list of suffixes supplied as an argument, this function returns the suffix compatible with this target. Compatibility in this case means that object files created by a target having the suffix returned by this function can be linked into an executable produced using this target. In the case where more than one suffix is compatible, this function returns a suffix in the following order of preference:
  1. if this target's suffix is in the list, that suffix is returned.
  2. suffixes from compatibleSuffixes are matched against the list from the first to the last, and the first one with the match is returned.
RETURNS
This function returns the suffix string of a target compatible with this target or null if no such suffix is found in the list of suffixes specified by the first argument.
generated on Wed, 06 Jan 2010 18:40:27 GMT