The <artifact> task defines a file or directory that gets created by a build; usually indicating something that the build produces for publication, rather than a temporary file.

As designed, the <artifact> task should be placed in a file separate from the build.xml file, so that both the local build and other project builds can import the artifact. See the artifacts guide for more detail on this process.

Note that, to support the import design, all file references inside the artifact are relative to the file that contains the artifact, not the directory of the running build.

After an <artifact> has been declared, its ID may be used inside <subprojects> and <library> elements. The artifact's library dependencies may also be referenced from inside a <library> element.

The algorithms for generating the different references and properties are like this:

• property: If the <artifact> attribute "property" is set, then the property with that name will be assigned to the location of the artifact; otherwise the property name will be constructed as follows.
  If the "name" attribute is given, then the property name is artifact.name.
  Otherwise if the "id" attribute is given, then the property name is artifact.id.
  Otherwise the property name is artifact.filename, using the name of the file without the path.
• fileset and patternset: If the <src> attribute "filesetId" is set, then that will be the reference ID for that source's fileset; otherwise the reference ID will be constructed using the below matrix.
  If the <src> attribute "patternsetId" is set, then that will be the reference ID for that source's patternset; otherwise the reference ID will be constructed using the below matrix.

  <artifact>		<src>	ID
  name	id	name	fileset	patternset
  an		sn	fileset.artifact.an.sn	patternset.artifact.an.sn
  	aid	sn	fileset.artifact.aid.sn	patternset.artifact.aid.sn
  an			fileset.artifact.an	patternset.artifact.an
  	aid		fileset.artifact.aid	patternset.artifact.aid

Future note: eventually, this processing, as well as default setup options for artifacts, will be moved into the <library-policy>, at which point the policyRef attribute will be required.

Parameters

Attribute Description Required antfile The build file that creates the artifact. Defaults to "build.xml" in the "current" directory. If a relative filename is given, then the file will be relative to the "current" directory, which is the directory of the file in which the <artifact> element is located. No target The Ant target in the antfile which builds the artifact. If not specified, then the default target of that ant file is used instead. No artifact This is deprecated in favor of the "location" attribute, and will be removed in Antlion 1.0.0 The name of the generated artifact file. If a relative filename is given, then the file will be relative to the "current" directory, which is the directory of the file in which the <artifact> element is located. This is an alias for the file attribute. Yes (if file is not defined) location The name of the generated artifact file. If a relative filename is given, then the file will be relative to the "current" directory, which is the directory of the file in which the <artifact> element is located. Yes (if artifact is not defined) name Used to create the fileset id, patternset id, and property name for the artifact in Ant. If this artifact gets imported in a remote build's <subprojects> task, then this is used to generate the artificial target name. If the name attribute isn't provided, then the artifact's id is used instead. Only if used in a <subprojects> task property The name of the Ant property to be set to the location of the artifact. If not given, then the property name will try to be assembled from, first, the name attribute, and then from the filename itself. No type The file type of the artifact. Just like the Library-Entry, this uses a value of "dir" to indicate that the artifact is a directory, and any other value to mean the artifact is a file. The default value is "jar". No policyRef As of Antlion 0.6.0 Assigns a <library-policy> to this <artifact>. Future versions will begin to push more of the artifact default values into the library policy, so this will become more important in future revisions. No

Nested Elements

src A type of pattern set. You can give it a name to create a fileset and patternset in the Ant references. Parameters Attribute Description Required name The name of the src set, used for generating a fileset or patternset reference in Ant. If no name is given, and there are more than one <src> elements, then only one fileset and patternset will be added (which one is non-determanistic). No dir Since Antlion 0.6.0 Allows for changing the base directory of the generated fileset. The value is relative to the directory containing the build file with this <artifact>. No filesetId The reference ID of the fileset for the src element. If not given, then the ID will try to be assembled from the name attribute. No patternsetId The reference ID of the patternset for the src element. If not given, then the ID will try to be assembled from the name attribute. No depends A collection of library and artifact references which this artifact depends upon for execution. It is primarily used by other projects to import a used artifact's dependencies inside a <library>, with the <dependencies> element. As of Antlion 0.6.0, when the policyRef attribute is set, <depends> now behaves almost identically to the <library> contained within the <libraryDef> task. Any other parameters not mentioned here will be stored as name-attribute pairs for library processing. Many library processors take advantage of the id attribute of a library. For instance, the path processor will use the id to generate an Ant reference to a new path object. The libId attribute, if specified, will be seen by library processors as an id attribute. If a libId is not specified in the depends, but the depends specifies a name, then the libId will be generated as "[artifact id].[depends id]". Parameters Attribute Description Required name Describes the type of dependency, such as "build" or "unittest". If no type is declared, then this dependency group will be included in all references to the artifact's dependencies, regardless of the type specified by the reference. If a type is specified, then it will only be used in dependency references that request that type, or that don't specify a type at all. This attribute will not be accessible for library processing. No type As of Antlion 0.6.0, this has been deprecated in favor of the name attribute. It acts as an alias for name. No libId Since Antlion 0.6.0 When the <depends> is processed like a <library> (i.e. the policyRef is set in the owning <artifact>), this attribute will be referenced as id for purposes of library processing. No Nested Elements artifact A reference to a previously defined artifact. This only adds the artifact itself, and not its dependencies. Parameters Attribute Description Required refid The ID of the dependent artifact No library As of Antlion 0.6.0, the <library> element can be used just like the <library> tag inside <libraryDef>. To do so, the policyRef attribute of the <artifact> must be set. In terms of processing the <depends>, this fully defined inner <library> will act as though it was referenced. If the refid attribute is set, then it references a previously defined attribute with an ID matching the refid value (for backwards compatibility). Parameters Attribute Description Required refid The ID of the dependent library. No dependencies A reference to an artifact's dependency list. Parameters Attribute Description Required artifactRefId The ID of the artifact. No type The dependency type to reference. If this is not specified, then all types are referenced. This is case insensitive. No

Examples

<artifact id="myproject-out" target="assemble" artifact="exports/myproject.jar"> <src> <include name="src/java/**" /> <exclude name="src/java/**/package.html" /> </src> </artifact> Declares an artifact, "exports/myproject.jar" relative to the ant script containing this tag, which is built by the "assemble" target of the build.xml file in the same directory (meaning compiling and jarred). A property will be created named "artifact.myproject-out" which points to the artifact file location. Also, a patternset with refid "patternset.artifact.myproject-out" will be created containing the contents of the <src> element, and a fileset with refid "fileset.artifact.myproject-out" will be created with the above patternset and a base directory of the directory containing the ant script of the artifact element. <artifact id="kool.jar" target="kool" antfile="../all-build.xml" name="project-out" artifact="exports/kool.jar"> <depends> <artifact refid="neat.jar" /> <dependencies artifactrefid="neat.jar" /> <library refid="lib.xerces" /> </depends> </artifact> Defines an artifact which the "../all-build.xml" file creates with the "kool" target. The property "artifact.project-out" points to the artifact file. The artifact also defines dependencies upon the "neat.jar" artifact, its dependences (if any), and the "lib.xerces" library. Those must have been defined before this artifact is defined, and is usually done by <import>ing them at the top of the artifact file. <artifact id="rad.jar" target="jar:all" artifact="exports/rad.jar"> <depends name="build"> <artifact refid="neat.jar" /> <dependencies artifactrefid="neat.jar" /> <library refid="lib.xerces" /> </depends> </artifact> Defines an artifact which the "../all-build.xml" file creates with the "kool" target. The property "artifact.project-out" points to the artifact file. The artifact also defines dependencies upon the "neat.jar" artifact, its dependences (if any), and the "lib.xerces" library. Those must have been defined before this artifact is defined, and is usually done by <import>ing them at the top of the artifact file.