/* --COPYRIGHT--,EPL
 *  Copyright (c) 2008 Texas Instruments and others.
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  which accompanies this distribution, and is available at
 *  http://www.eclipse.org/legal/epl-v10.html
 *
 *  Contributors:
 *      Texas Instruments - initial implementation
 *
 * --/COPYRIGHT--*/
/*
 *  ======== ITarget.xdc ========
 */
package 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.
 */
metaonly interface ITarget {

    /*!
     *  ======== Model ========
     *  Target runtime model.
     *
     *  @field(`endian`)    this string specifies the endianess of the
     *                      generated code.  Valid values include:
     *                      @p(dlist)
     *                          - `"big"`
     *                              big endian
     *                          - `"little"`
     *                              little endian
     *                          - `null`
     *                              unspecified
     *                      @p
     *
     *  @field(`codeModel`) this string specifies a target-specific code size
     *                      model.  Valid values include:
     *                      @p(dlist)
     *                          - `"near"`
     *                              C54 near mode
     *                          - `"far"`
     *                              C54 far mode
     *                          - `undefined`
     *                              unspecified
     *                      @p
     *
     *  @field(`dataModel`) this string specifies a target-specific data size
     *                      model.  Valid values include:
     *                      @p(dlist)
     *                          - `"large"`
     *                              C55, C28 large model
     *                          - `undefined`
     *                              unspecified
     *                      @p
     *
     *  @field(`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 #model
     */
    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 */
    }

    /*!
     *  ======== name ========
     *  Nickname for this target.
     *
     *  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.
     */
    readonly config String name;

    /*!
     *  ======== suffix ========
     *  Suffix appended to all objs, libraries, and executable.
     *
     *  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:
     *  @p(dlist)
     *      - `".a<suffix>"`
     *              archive files (i.e., libraries)
     *      - `".o<suffix>"`
     *              object files
     *      - `".s<suffix>"`
     *              assembly language source (see `{@link #scompile()}`)
     *      - `".x<suffix>"`
     *              executable files
     *  @p
     *  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 produce 100% EABI
     *  compatible objects and, targets with different suffixes should produce
     *  objects with incompatible EABIs.
     *
     *  @see #scompile()
     */
    readonly config String suffix;

    /*!
     *  ======== compatibleSuffixes ========
     *  Array of suffixes used by targets compatible with this target
     *
     *  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 String compatibleSuffixes[];

    /*!
     *  ======== isa ========
     *  CPU Instruction Set Architecture (ISA)
     *
     *  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 xdc.platform.ICpuDataSheet
     */
    readonly config String isa;

    /*!
     *  ======== model ========
     *  Run-time model
     *
     *  This structure identifies a particular run-time model
     *  used by the compiler to generate instructions.
     */
    readonly config Model model;

    /*!
     *  ======== os ========
     *  Name of OS required to run programs built for this target.
     *
     *  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.
     */
    readonly config String os;

    /*!
     *  ======== rts ========
     *  Name of a run-time support package to include
     *
     *  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
     *  `{@link xdc.bld.Executable#attrs}.rtsName` attribute is set to `null`;
     *  see {@link xdc.bld.Executable#Attrs}.
     */
    readonly config String rts;

    /*!
     *  ======== base ========
     *  A target that this target is based upon.
     *
     *  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 `{@link #rootDir}` is the value of the base's
     *  `{@link #rootDir}` setting.
     */
    readonly config ITarget.Module base;

    /*!
     *  ======== dllExt ========
     *  @_nodoc dlls are not yet fully supported
     */
    config String dllExt;

    /*!
     *  ======== execExt ========
     *  Extension for executables.
     *
     *  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`:
     *  @p(dlist)
     *      - `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
     *  @p
     *
     *  @a(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 String execExt;

    /*!
     *  ======== platform ========
     *  The default platform name for this target
     *
     *  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 `{@link #platforms}`
     *  array is non-empty, it is initialized to be the first element of the
     *  platforms array (i.e., `{@link #platforms[0]}`).
     */
    config String platform;

    /*!
     *  ======== platforms ========
     *  A set of platforms that can support this target
     *
     *  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 `{@link #platform}`
     *  is non-`null`, platforms is initialized to an array of one element
     *  equal to `{@link #platform}`.
     */
    config String platforms[] = [];

    /*!
     *  ======== binaryParser ========
     *  The name of a object file parser
     *
     *  The value of this configuration parameter is the name of a
     *  module or Java class that implements the `xdc.rta.IOFReader` interface.
     *  This interface is used to extract information from the object files
     *  produced by this target.
     *
     *  @_nodoc object file readers are not yet fully supported
     */
    config String binaryParser;

    /*!
     *  ======== version ========
     *  The Compatibility Key associated with this target.
     *
     *  @a(Readonly) This value is automatically computed by the XDC Build
     *  Engine by executing the `{@link #getVersion()}` function after
     *  `package.bld` completes but prior to generating `package.mak`.
     */
    config String version;

    /*!
     *  ======== versionRaw ========
     *  The unmodified version string associated with this target.
     *
     *  @a(Readonly) This value is automatically computed by the XDC Build
     *  Engine by executing the `{@link #getVersion()}` function after
     *  `package.bld` completes but prior to generating `package.mak`.
     *
     *  @_nodoc
     */
    config String versionRaw;

    /*!
     *  ======== DebugGen ========
     *  Debugger integration support.
     *
     *  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`:
     *  @p(dlist)
     *      - `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"`, ...
     *  @p
     *  Preconditions for the `packageTemplate`:
     *  @p(dlist)
     *      - `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
     *              `{@link 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"`, ...
     *  @p
     *  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`:
     *  @p(dlist)
     *      - `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.
     *  @p
     *  Both the `exeDir` and `cfgDir` are relative to the directory
     *  containing the `package.bld` script.
     *
     *  Built-in variables for `packagePattern`:
     *  @p(dlist)
     *      - `pkgName`
     *              the package's name (e.g., `"ti.targets"`);
     *      - `trgName`
     *              the target's `name` property;
     *      - `trgSuffix`
     *              the target's `suffix` property.
     *  @p
     *
     *  @see #debugGen
     */
    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 */
    }

    /*!
     *  ======== debugGen ========
     *  Debugger/IDE file generation support.
     *
     *  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
     *  `{@link 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:
     *  @p(code)
     *	    Program.gen.debuggerFiles = true;
     *  @p
     *
     *  It is also possible to disable the generation of selected files by
     *  setting the appropriate fields of `{@link #DebugGen}` to `null` in
     *  your `config.bld` script.
     */
    config DebugGen debugGen;

    /*!
     *  ======== Extension ========
     *  File extension to file type association.
     *
     *  This structure is used by the Build Engine to determine whether a
     *  file should be treated as C++, C, or assembly language source.
     *
     *  @field(suf) the file extension including any '.' characters
     *
     *  @field(typ) the type of the file having this extension.
     *              Allowable file type identifiers include:
     *              @p(dlist)
     *                 - `"c"`
     *                      C language source file
     *                 - `"asm"`
     *                      assembly language source file
     *                 - `"cpp"`
     *                      C++ language source file
     *              @p
     *  @see #extensions
     */
    struct Extension {
        String suf;     /*! file extension (including any '.') */
        String typ;     /*! type of this file; e.g., `"c"`, `"asm"`, ... */
    };

    /*!
     *  ======== extensions ========
     *  File extensions recognized by this target.
     *
     *  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:
     *  @p(code)
     *      var C64P = xdc.module('ti.targets.C64P');
     *      C64P.extensions[".s64"] = {
     *          suf: ".s64", typ: "asm"
     *      };
     *  @p
     *  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:
     *  @p(code)
     *      var C64P = xdc.module('ti.targets.C64P');
     *      delete C64P.extensions[".asm"];
     *  @p
     */
    config 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"}],
    ];

    /*!
     *  ======== versionMap ========
     *  Map of compiler version numbers to compatibility keys.
     *
     *  `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 `{@link #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 ti.targets.ITarget#versionMap
     */
    config String versionMap[string] = [
    ];

    /*!
     *  ======== alignDirectiveSupported ========
     *  The compiler supports an align directive.
     */
    readonly config Bool alignDirectiveSupported = false;

    /*!
     *  ======== rootDir ========
     *  Installation directory for this target's code generation tools.
     *
     *  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 `{@link #base}` parameter is `null`, this parameter *must* be
     *  set by the user; otherwise, `rootDir` defaults to the value
     *  `base.rootDir`.
     */
    config String rootDir;

    /*!
     *  ======== CompileOptions ========
     *  Options passed to the compiler/assembler.
     *
     *  @field(aopts)   a string of target-specific assembler options
     *  @field(copts)   a string of target-specific C/C++ compiler options
     *  @field(cfgcopts)   a string of C/C++ compiler options for C config file,
     *                  includes 'copts' in addition to the value passed
     *  @field(defs)    a string of macro definitions each of the form
     *                  "`-Dname=value`" separated by white space
     *  @field(incs)    a string of include directories each of the form
     *                  "`-Idir`" separated by white space
     *
     *  @a(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.
     *  @p(dlist)
     *      - `xdc_bld__profile_`{profile_name}
     *          this symbol is always defined and {profile_name} is the
     *          compile goal's (see `{@link #CompileGoal}`) profile name.
     *  @p
     *
     *  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 `{@link xdc}`.
     *
     *  @see #OptionSet
     *  @see #CompileGoal
     *  @see xdc
     */
    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 */
    };

    /*!
     *  ======== OptionSet ========
     *  Collection of tool-chain options.
     *
     *  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.
     *
     *  @field(compilerOptions) a set of compiler/assembler options
     *  @field(linkOpts)        a string of target-specific linker options
     *  @field(archiveOpts)     a string of target-specific archiver options
     *  @field(filters)         an array of filters applied (in order) to
     *                          tool-chain commands
     *
     *  @see #profiles
     */
    struct OptionSet {
        CompileOptions  compileOpts;    /*! profile-specific compiler opts */
        String          linkOpts;       /*! profile-specific linker opts */
        String          archiveOpts;    /*! profile-specific archiver opts */

        ITargetFilter.InstDesc  filters[]; /*! ITargetFilter instance descs */
    };

    /*!
     *  ======== profiles ========
     *  Profiles supported by this target.
     *
     *  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 OptionSet profiles[string] = [
        ["release", {}],
        ["debug", {}],
    ];

    /*!
     *  ======== CompileGoal ========
     *  The goal specification passed to the `{@link #compile}`
     *  function.
     *
     *  @see #compile
     *  @see #scompile
     */
    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 */
        CompileOptions opts;/*! goal specific compiler options */
        Bool configOpts;    /*! true if compiling the generated C config file */
    };

    /*!
     *  ======== LinkGoal ========
     *  The goal specification passed to the `{@link #link}` function.
     *
     *  @see #link
     */
    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 */
    };

    /*!
     *  ======== ArchiveGoal ========
     *  The goal specification passed to the `{@link #archive}`
     *  function.
     *
     *  @see #archive
     */
    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 */
    };

    /*!
     *  ======== CommandSet ========
     *  The commands necessary to create a specified goal.
     *
     *  This structure is the return value of the `{@link #compile}`,
     *  `{@link #link}` and `{@link #archive}` functions.  This value is then
     *  used to generate a makefile or any other files necessary to generate
     *  a specified goal.
     *
     *  @field(msg)     a brief synopsis of the commands specified by `cmds`;
     *                  this string is output in lieu of `cmds` when building
     *                  in "non-verbose" mode.
     *
     *  @field(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.
     *                  @p(dlist)
     *                      - `$(rootDir)`
     *                          the target's `{@link #rootDir}` configuration
     *                          parameter
     *                      - `$(packageBase)`
     *                          the target package's
     *                          `{@link xdc.IPackage#packageBase}` property
     *                      - `$(XDCINCS)`
     *                          a set of "-I" options that names each
     *                          repository in the package path
     *                  @p
     *
     *  @field(envs)    an array of "name=value" strings that represent
     *                  environment variables that are defined prior to the
     *                  execution of the commands specified by `cmds`
     *
     *  @field(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.
     *
     *  @see #archive
     *  @see #compile
     *  @see #scompile
     *  @see #link
     */
    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 */
    };

    /*!
     *  ======== archive ========
     *  Create an archive.
     *
     *  This function is called during makefile generation to convert build
     *  goals into specific commands that generate the specified goal.
     *
     *  @param(goal) the `{@link #ArchiveGoal}` defining the archive to build.
     *
     *  @a(returns)
     *  This function returns a `{@link #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.
     *
     *  @a(throws)  `Error` exceptions are thrown for fatal errors.
     */
    CommandSet* archive(ArchiveGoal *goal);

    /*!
     *  ======== compile ========
     *  Compile a source file into an object file.
     *
     *  This function is called during makefile generation to convert build
     *  goals into specific commands that generate the specified object
     *  file goal.
     *
     *  @param(goal) a `{@link #CompileGoal}` that specifies what file to
     *               compile, the output file name, and any goal-specific
     *               options to use
     *
     *  @a(returns)
     *  This function retuns a `{@link #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.
     *
     *  @a(throws)  `Error` exceptions are thrown for fatal errors.
     */
    CommandSet* compile(CompileGoal *goal);

    /*!
     *  ======== scompile ========
     *  Compile a source file into an assembly language file.
     *
     *  This function is called during makefile generation to convert build
     *  goals into specific commands that generate the specified assembly
     *  language source goal.
     *
     *  @param(goal) a `{@link #CompileGoal}` that specifies what file to
     *               compile, the output file name, and any goal-specific
     *               options to use
     *
     *  @a(returns)
     * This function returns a `{@link #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).
     *
     *  @a(throws)  `Error` exceptions are thrown for fatal errors.
     */
    CommandSet* scompile(CompileGoal *goal);

    /*!
     *  ======== link ========
     *  Link object files to produce an executable.
     *
     *  This function is called during makefile generation to convert build
     *  goals into specific commands that generate the specified goal.
     *
     *  @param(goal) a `{@link #LinkGoal}` that specifies the output file
     *               name, a list of files to link with, and any goal-specific
     *               options to use
     *
     *  @a(returns)
     *  This function returns a `{@link #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.
     *
     *  @a(throws)  `Error` exceptions are thrown for fatal errors.
     */
    CommandSet* link(LinkGoal *goal);

    /*!
     *  ======== getVersion ========
     *  Get a target-specific Compatibility Key string
     *
     *  This function is called during makefile generation to obtain a
     *  target-specific Compatibility Key string.  This string is of the
     *  form:
     *  @p(code)
     *      "<pkg>.<mod>{<d0>,<d1>,<d2>,<d3>"
     *  @p
     *  where, `<pkg>.<mod>` is the name of the target, and `<d0>`, `<d1>`,
     *  etc. forms a Compatibility Key.
     *
     *  @a(returns)
     *  This function returns a string that encodes the name of the target
     *  and its Compatibility Key.
     *
     *  @a(throws)  `Error` exceptions are thrown for fatal errors.
     */
    String getVersion();

    typedef String StringArray[];

    /*!
     *  ======== getISAChain ========
     *  Get this target's ISA "is compatible with" relation.
     *
     *  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:
     *  @p(nlist)
     *      - pre-define macro definitions that enable code to be
     *        conditionally compiled based on compatible versions of a
     *        target's ISA.
     *
     *      - 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".
     *  @p
     *
     *  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.
     *
     *  @param(isa) the ISA identifier string for the ISA to lookup; if null
     *              then the target's ISA is used (ITarget.isa).
     *
     *  @a(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.
     *
     *  @a(throws)  `Error` exceptions are thrown for fatal errors.
     *
     */
    function getISAChain(isa);

    /*!
     *  ======== findSuffix ========
     *  Find the suffix that is compatible with this target.
     *
     *  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:
     *  @p(nlist)
     *      - if this target's suffix is in the list, that suffix is returned.
     *
     *      - suffixes from `compatibleSuffixes` are matched against the list
     *        in the order they appear in `compatibleSuffixes`, and the first one
     *        found in the list is returned.
     *  @p
     *
     *  @param(pkg) a package object or an array of target suffix strings
     *              (see `{@link #suffix}`).
     *
     *  @a(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.
     *
     */
    function findSuffix(pkg);

    /*!
     *  ======== selectSuffix ========
     *  Select the suffix that is compatible with this target.
     *
     *  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:
     *  @p(nlist)
     *      - if this target's suffix is in the list, that suffix is returned.
     *
     *      - suffixes from `compatibleSuffixes` are matched against the list
     *        in the order they appear in `compatibleSuffixes`, and the first one
     *        found in the list is returned.
     *  @p
     *
     *  @param(suffixList)	an array of target suffix strings
     *                          (see `{@link #suffix}`).
     *
     *  @a(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.
     *
     */
    String selectSuffix(StringArray suffixList);

    /*!
     *  ======== sectMap ========
     *  Output section name to segment type mapping
     *
     *  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 `{@link xdc.cfg.Program}` object and the
     *  `{@link 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
     *  `{@link 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.
     */
    readonly config String sectMap[string];

    /*!
     *  ======== TypeInfo ========
     *  @_nodoc
     *
     *  @see #StdTypes
     */
    struct TypeInfo {
        int size;
        int align;
    }

    /*!
     *  ======== StdTypes ========
     *  Standard base types supported by all targets
     *
     *  @see #stdTypes
     */
    struct StdTypes {
        TypeInfo t_IArg;
        TypeInfo t_Char;
        TypeInfo t_Double;
        TypeInfo t_Float;
        TypeInfo t_Fxn;
        TypeInfo t_Int;
        TypeInfo t_Int8;
        TypeInfo t_Int16;
        TypeInfo t_Int32;
        TypeInfo t_Int40;
        TypeInfo t_Int64;
        TypeInfo t_Long;
        TypeInfo t_LDouble;
        TypeInfo t_LLong;
        TypeInfo t_Ptr;
        TypeInfo t_Short;
        TypeInfo t_Size;
    }

    /*!
     *  ======== stdInclude ========
     *  Standard C/C++ types header
     *
     *  This string identifies a header containing the C/C++ definitions
     *  required to enable use of `xdc/std.h` in C/C++ sources; see
     *  `{@link 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 `{@link xdc 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:
     *  @p(code)
     *      // 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
     *          :
     *  @p
     *  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.
     */
    readonly config String stdInclude;

    /*!
     *  ======== stdTypes ========
     *  Size and alignment for standard base types
     *
     *  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.
     */
    readonly config 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 },
    };

    /*!
     *  ======== bitsPerChar ========
     *  The number of bits in a variable of type `char`
     *
     *  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
     *  @p(code)
     *      T.stdTypes.t_Int.size * T.bitsPerChar
     *  @p
     */
    readonly config Int bitsPerChar = 8;
}