[guide] <fixturedef>

The <fixturedef> task lets you load a <run-configuration> or a plain antlib into your project. And unlike the standard Ant <import> task, you can load these scripts from within Ant targets; you are not limited to a project’s anonymous top-level target. While it is common for you to load a SAM run configuration from your driver project’s initialization target, you can use run configurations in a variety of situations. <fixturedef> is implemented to be flexible so it can support as many of these scenarios as is feasible.

The <fixturedef> task is not meant to be a replacement of the <import> task; it does not load Ant project script files. With SAM’s run configurations, you cannot use Ant’s standard antlib loading mechanism(s) because Ant will not recognize our <run-configuration> root antlib element; you must use a <fixturedef> task. As a convenience, <fixturedef> can also load regular antlib scripts, provided the script’s name ends with a .antlib or you set the plain parameter to “yes” (if not, <fixturedef> assumes it is a run configuration script).

If you inherit fixture definition from a shared, readonly source (like a deployed build system), you can decorate the application of that definition provided the original author allows it. You will need to attach your reaction callback to the “fixturedef” operations category and specifically to the name of the targeted run configuration (plain antlibs have no name attribute so you must use the script’s location instead). See the Examples section for an example of how to do this kind of local tweaking.

Parameters

Attribute	General Description	Required
file	File system path to a run configuration, plain antlib script, or properties file.	Yes; one of these must be specified.
resource	Resource name of a run configuration, plain antlib script, or properties file.
url	URL to a run configuration, plain antlib script, or properties file.
mustexist	Set to “no” if the named configuration does not have to exist.	No; defaults “yes”.
plain	Set to “yes” if the named script is a plain antlib script instead of a run configuration.	No; defaults “no” unless file has .antlib extension.
allowoverrides	Set to “yes” to allow matching reaction callback methods to be run.	No; defaults “no” †.

^†Controlled by the jware.antx.defaults.fixturedef.overrides property.

Nested Elements

The <fixturedef> task does not support any nested elements.

Examples

The following snippet loads a SAM run configuration root.rcf into the project from its initialization target lib:init.

    <project name="Build Library" default="lib:help">
        <taskdef resource="com/idaremedia/sams/install/antlib.xml"/>
        …
        <target name="lib:init">
            <fixturedef file="root.rcf"/>
        </target>
        …
    </project>

The following snippet loads and installs two plain antlib scripts. The first install relies on the script file’s extension, the second install tells SAM explicitly that the file is a plain antlib.

    <target name="checkout" depends="init,…">
        <fixturedef file="checkout.antlib"/>
        …
    </target>

    <target name="deploy" depends="init,…">
        <fixturedef file="deploy.xml" plain="yes"/>
        …
    </target>

The following snippet shows part of a build driver script cornerstone that manages most of its fixture configuration in separate run configuration files and uses <fixturedef> to load and apply them when appropriate.

    [In /ci/tools/cornerstone.xml]
    <project name="cornerstone" default="help" xmlns:c="antlib:com.idaremedia.sams.install">
        <tstamp/>
        <dirname property="cornerstone.dir" file="${ant.file.cornerstone}"/>
        <c:managesams/>
        …
        <target name="init">
            <c:fixturedef file="${cornerstone.dir}/root.rcf"/>
            <mkdir.../>
            …
        </target>

        <target name="help">
            <c:fixturedef file="${cornerstone.dir}/help.rcf"/>
            <c:show msgid="help.syntax" msgarg1="${TSTAMP}"/>
        </target>

        <target name="deploy" depends="init,…">
            <c:fixturedef file="${cornerstone.dir}/deploy.rcf" allowoverrides="yes"/>
            <scp.../>
            …
        </target>
        …
    </project>

The following snippet shows a local build script that reuses the previously shown build driver with one local tweak: whenever the deploy target is called, the local tweakdeploy macro is automatically called as if it were part of the common target. Note that the local tweak is attached to the application of the deploy.rcf configuration— not the deploy target per se. The macro gets executed after the common deploy configuration has been applied but before the <scp> is started.

    [In a local build.xml]
    <project name="localbuild" ...>
        <import file="/ci/tools/cornerstone.xml"/>

        <c:add-reactiondefs>
            <reactionfor fixturedef="deploy" call="macro:tweakdeploy"/>
        </c:add-reactiondefs>

        <macrodef name="tweakdeploy" uri="jware.sams.reaction">
          …[do local additions here]
        </macrodef>
    </project>

Related Topics

• The FixtureDefTask Java class implements <fixturedef>.
• The <issue> task lets you create hooks within your scripts to which others can attach callbacks.
• The <add-reactiondefs> task lets you decorate <fixturedef> with your own setup.