[guide] <add-artifactdefs>

The <add-artifactdefs> task lets you install a single artifact definition catalog into the current build-iteration. You would typically declare your <add-artifactdefs>s inside a standard antlib or a SAM <run-configuration>.

The artifactdef catalog installer task differs from a standalone artifact definition catalog declaration in that it installs its catalog at the build-iteration level where it becomes accessible to the current project and any sub or child projects created thereafter. A standalone catalog is visible, by default, only to its parent project; you must explicitly pass it through to child projects from your scripts.

You can declare the artifact definitions to be installed(<artifactdef>) directly inside the <add-artifactdefs> element. However, to aid the maintainability of artifact definitions, an <add-artifactdefs> task can also read a catalog definition stored in an independent file (or at any accessible URL). The external artifact definitions must be uniquely named because they are added to the definitions declared directly inside the installer. If you try to overwrite an existing artifact definition, the installer will signal a build script error. If you would like to layer artifact definitions, you should use multiple installer tasks, run in your usage preference order; definitions loaded later will take precedence over those loaded before.

Because each artifact definition catalog has its own ALMS instance, you can configure each catalog’s ALMS instance independent of all others in the current build-iteration. To define an artifactdef catalog’s ALMS instance you must include an <almsconfig> element.

An <add-artifactdefs> task is a single-use task; once an instance has installed its catalog, it becomes useless— you should never assign ids or otherwise retain long-lived references to these installers. Use the iterationid parameter to give each unique <add-artifactdefs> an iteration identifier; this identifier will prevent any re-run installer tasks from reinstalling the same set of artifact definitions.

Parameters

Nested Element: <artifactdef>^[1..*]

The <artifactdef> element lets you insert a new artifact definition into this installer’s catalog. Because this is a core SAM element, it is described in detail in its own user guide; read the <artifactdef> guide for a full description. You can define any number of artifact definitions in a single installer; these declarations are added to any definitions loaded from an external source.

Nested Element: <almsconfig>^[0..1]

The <almsconfig> element lets you configure the ALMS instance associated with this artifactdef catalog. The <almsconfig> element is just the element-specific name for SAM ALMS definition data object; read the <almsdef> guide for a full element description.

Nested Element: <fixturecheck>^[0..*]

The <fixturecheck> element lets you insert a fixture verification assertion into this definition so you can verify that all required environment settings have been defined. The format of this element is exactly the same as the standalone AntX <fixturecheck> element; if the check fails, <add-artifactdefs> will signal a build error.

Examples

The following snippet adds to artifact definitions (“varconfs” and “javasources”) to the current build-iteration. The full definition is declared inline, inside the installer task’s body. Because the installer also has an iteration id “MyArtifacts”, if the surrounding context (like a target) is re-executed by during a single build-iteration, the artifact definitions will not be reinstalled.

    <add-artifactdefs iterationId="MyArtifacts">
      <fixturecheck allset="etc,src" msg="Properties 'etc' and 'src' set"/>

      <artifactdef name="varconfs">
          <defaults>
             <method use="mksandbox"/>
             <setup>
                <directory-varconfs/>
             </setup>
             <parameter name="module" value="ant.varconfs"/>
             <parameter name="todir" value="@{varconfs.loc}"/>
          </defaults>
          <version name="java">
             <parameter name="file" value="java.vars"/>
          </version>
          <version name="java-stable" inherit="java">
             <parameter name="tag" value="r1-1build16"/>
             <parameter name="todir" value="@{varconfs.loc}/snapshots/r1-1build16"/>
          </version>
          <version name="sql">
             <parameter name="file" value="sql.vars"/>
          </version>
          <version name="xsl">
             <parameter name="file" value="xsl.vars"/>
          </version>
          <version name="xsl-stable" inherit="xsl">
             <parameter name="tag" value="r1-0build23"/>
             <parameter name="todir" value="@{varconfs.loc}/snapshots/r1-0build23"/>
          </version>
      </artifactdef>

      <artifactdef name="javasources">
          <defaults>
             <method use="macro:prepare-javasources"/>
             <version use="latest"/>
             <parameter name="packages" value="ui,uimobile,web,ejbs"/>
             <parameter name="todir" value="@{src}"/>
          </defaults>
          <version name="latest">
             <setup>
                <varconfs-java/>
             </setup>
             <parameter name="varconfs" value="@{varconfs-java.loc}"/>
          </version>
          <version name="stable">
             <setup>
                <varconfs-java-stable/>
             </setup>
             <parameter name="varconfs" value="@{varconfs-java-stable.loc}"/>
          </version>
      </artifactdef>
      ...
</add-artifactdefs>

The following snippet declares an installer task that loads its artifact definitions from an external file “catalog.xml”. The installer also configures its ALMS instance to use an existing local repository (directory) of ARM files.

    <add-artifactdefs file="${BUILD_TOOLS}/artifactdefs/catalog.xml">
       <almsconfig>
          <storagepolicy uploadsDir="${BUILD_TOOLS}/arms"/>
       </almsconfig>
    </add-artifactdefs>

Related Topics

• The ArtifactDefCatalogInstallerTask Java class implements <add-artifactdefs>.
• The <fixturedef> task lets you load and apply an <add-artifactdefs>.