[guide] <run-configuration>

SAM inherits a collection of fixture configuration utilities from AntX and introduces a small set of its own. To help you leverage these components and provide a simple mechanism to bootstrap SAM from a script, SAM includes a custom antlib called a run configuration(<run-configuration>).

A run configuration provides three essential services that regular Ant imports, basic antlibs, and XML entities do not. First, a run configuration helps you ensure a SAM iteration fixture is defined and properly initialized as early as possible; for example, it makes sure an artifact locations catalog exists for event listeners to monitor and for tasks to use. Second, a run configuration lets you include fixture initialization tasks that are not permitted in regular antlibs without allowing the entire domain of available tasks like an import or XML entity would. This flexibility lets you execute certain primordial configuration when an iteration is first created. Third, a run configuration lets your clients (developers, testers, whoever) supplement your installed (readonly) instructions with simple local instructions by attaching wrapper scriptlets that decorate yours. This feature lets your clients tweak your script for adhoc execution without touching your file.

A SAM run configuration is not intended to be a project or product definition like the required POM in Apache’s Maven (for example); it is a collection of data declarations and fixture-defining Ant tasks. If you use a run configuration to define a set of properties that results in a unique instance of an existing build template, then that is a particular, though common, use of run configurations. However you choose to use them, you must use the SAM <fixturedef> task to load a run configuration. You cannot use Ant’s standard antlib loading mechanism(s) because Ant will not recognize our <run-configuration> root antlib element.

Parameters

Nested Elements

As a convenience, a run configuration will accept automatically several standard Ant fixture-defining components like most data declarations and tasks like <property>, <xmlproperty>, <tstamp>, and <buildnumber>. The complete list of accepted non-antlib elements is defined by the nestables.properties file found in the source distribution. You can supplement this list by setting the nestables parameter on the configuration root element.

Examples

This run configuration snippet declares several default values and loads a fixture-defining properties file based on the value of the audience property (which it defaults to “dev” when undefined). While this limited configuration could be accomplished using Ant’s standard <import> facility, using a run configuration gives you more options when deploying the script without the need to limit your user’s ability to customize when and how the script is used.

    <?xml version="1.0"?>
    <run-configuration name="root" description="Bootstrap build configuration.">
        <-- [required] -->
        <assert isset="product" msg="property 'product' defined"/>

        <-- [defaults] -->
        <tstamp/>
        <property name="audience" value="dev"/>
        <property file="${user.home}/.builds/${product}-${audience}.conf"/>

        <-- [required] -->
        <assert filenotempty="${audience}.conf" msg="File ${audience}.conf exists"/>
        <property file="${audience}.conf"/>

        <-- [features] -->
        <managebundles action="install-root" file="default.strings"/>
        <manageuris action="enable" file="valueuris.xml"/>
        ...
    </run-configuration>

Related Topics

• The RunConfigurationDef Java class implements <run-configuration>.
• The <fixturedef> task lets you load and apply a <run-configuration> to a project.
• The <add-reactiondefs> task lets you decorate inherited run configurations with your own adhoc setup.