/* --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--*/
/*!
 *  ======== ITargetFilter ========
 *  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.
 *
 *  Filters can:
 *  @p(nlist)
 *      - modify or augment the commands returned by a target's compile,
 *        link and archive methods via `{@link #compile}`, `{@link #link}`,
 *        and `{@link #archive}`;
 *      - add new definitions to the generated makefiles usable by the
 *        command added above via `{@link #getDefs}`; and
 *      - specify new files to be generated during the configuration process
 *        that may be used during or after the link process via
 *        `{@link #getGenTab}`.
 *  @p
 *  Filters are created implicitly when a target's profile
 *  (`{@link xdc.bld.ITarget#profiles}`) that references the filter is used.
 *  To use a filter, one must configure a profile's option set
 *  (`{@link 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 `{@link xdc.bld.Library#Attrs}`.
 */
metaonly interface ITargetFilter
{
    /*!
     *  ======== InstDesc ========
     *  `ITargetFilter` Instance descriptor
     *
     *  This structure provides the information necessary to create an
     *  instance of an `ITargetFilter`.
     *
     *  @see xdc.bld.ITarget#OptionSet
     */
    struct InstDesc {
        String  moduleName; /*! name of a module implementing `ITargetFilter`*/
        Any     params;     /*! params passed to ITargetFilter.create() */
    };
    
    /*!
     *  ======== GenDesc ========
     *  Configuration file generation descriptor
     *
     *  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 `{@link 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 GenDesc {
        String template;    /*! name of the template to expand */
        String file;        /*! the name of the file to generate */
    };

    /*!
     *  ======== MacroDesc ========
     *  Macro definition descriptor
     *
     *  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 `{@link #archive()}`,
     *  `{@link #compile()}`, or `{@link #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
     */
    struct MacroDesc {
        String name;    /*! name of the macro */
        String value;   /*! the name value of the macro name */
    };
    
instance:

    /*!
     *  ======== archive ========
     *  Archive command filter
     *
     *  This method is called for every archive created by the package's
     *  build script (via `{@link xdc.bld.PackageContents#addLibrary()}`).
     *
     *  @param(container)   String
     *  @param(lib)         `{@link xdc.bld.Library}`
     *  @param(objList)     String
     *  @param(archArgs)    `{@link xdc.bld.ITarget#ArchiveGoal}`
     *  @param(result)      `{@link xdc.bld.ITarget#CommandSet}`
     */
    function archive(container, lib, objList, archArgs, result);

    /*!
     *  ======== compile ========
     *  Compile command filter
     *
     *  This method is called for every object created by the package's
     *  build script (via `{@link xdc.bld.Executable#addObjects()}`,
     *  `{@link xdc.bld.Library#addObjects()}`, ...).
     *
     *  @param(container)   String
     *  @param(target)      `{@link xdc.bld.ITarget}.Module`
     *  @param(goal)        String goal file
     *  @param(compArgs)    `{@link xdc.bld.ITarget#CompileGoal}` the file to
     *                      compile
     *  @param(result)      `{@link xdc.bld.ITarget#CommandSet}`
     */
    function compile(container, target, goal, compArgs, result);

    /*!
     *  ======== getGenTab ========
     *  Get table of files to be generated during configuration
     *
     *  This method is called during makefile generation to obtain
     *  a list of additional files to be generated during configuration.
     *
     *  @param(acfg)        `{@link xdc.bld.Configuration}` or Assembly
     *  @param(cfgDir)      String directory name where generated config files
     *                      are placed
     *  @param(configName)  String base name of the configuration
     *  @a(RETURNS)         array of `{@link #GenDesc}`
     */
    function getGenTab(acfg, cfgDir, configName);

    /*!
     *  ======== getDefs ========
     *  Get table of macro definitions
     *
     *  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 (`{@link #archive()}`,
     *  `{@link #compile()}` or `{@link #link()}`).
     *
     *  @a(RETURNS)         array of `{@link #MacroDesc}`
     */
    function getDefs();

    /*!
     *  ======== link ========
     *  Link command filter
     *
     *  This method is called for every executable created by the package's
     *  build script (via `{@link xdc.bld.PackageContents#addExecutable()}`,
     *  ...).
     *
     *  @param(container)   String
     *  @param(cfgbase)     String
     *  @param(prog)        Executable or Assembly
     *  @param(objList)     String
     *  @param(linkArgs)    `{@link xdc.bld.ITarget#LinkGoal}`
     *  @param(result)      `{@link xdc.bld.ITarget#CommandSet}`
     */
    function link(container, cfgBase, prog, objList, linkArgs, result);
}