Handles the creation of artificial Ant targets that call out to external Ant build files. This task is primary intended as an integration point between a build's output and other builds' dependencies upon that output (see the article about this).

This task will create artificial targets that many IDEs don't understand, and thus may mark a build file as being invalid even if it really is. To avoid this, you may wish to look at the <run-subproject> task.

Parameters

Attribute Description Required separator Text that will separate the different components of the artificial targets' names. See the details in each embedded element for details, as well as the prefix parameter, on where this gets used. No, defaults to two colons ("::") prefix If set, this parameter's value will be prefixed to the start of all the artificial targets' names. If this value is empty or never set, then the separator will not be prepended to the names. If this value equals the separator, then only the separator will be prepended to the names. If this value is different than the separator, and not empty, then the name will be prepended with: prefix + separator No, defaults to an empty string UseArtifactTarget By default, this parameter is enabled ("true"). Disable ("false") to remove redundant information from the generated target names of artifacts. This is enabled by default for backwards-compatibility. No, defaults to "true"

Nested Elements

artifact A reference to an <artifact>. The generated (artifical) target name will be in the format of: [prefix + separator] + artifact name + separator + artifact target If the subproject prefix is empty (default), then the separator is not prepended to the name. If the artifact does not specify a target (that is, use the default target), then the text [default] is used as the artifact target. If the subproject attribute UseArtifactTarget is turned off, then the generated target name will be in the format of: [prefix + separator] + artifact name Since the artifact always indicates a single target, the artifact target name is redundant information. Parameters Attribute Description Required refid The reference ID of the artifact Yes buildif Allows for setting the conditions for invoking the artifact's builder, by checking the artifact. The possible values include: always Always run the artifact's build. not-exists If the artifact can't be found, then run the artifact's build. out-of-date (default) If the artifact can't be found, or if its date-timestamp is less than any of its sources, then run the artifact's build. If the artifact provides no source list, then it only checks for the existence of the artifact. depends-out-of-date (since Antlion 0.9.0) This is similar to the out-of-date setting, except that it checks both the <src> and <depends> contents for being out-of-date. Note that this does not recursively start dependent artifact builds. It only checks if any of the dependencies have been altered since the last build for the current artifact. No (defaults to "out-of-date") project Declares an external project build file, and all the targets that will be generated into local targets. The names of the generated targets follow the following pattern: [prefix + separator] + name + separator + target name If the subproject prefix is empty (default), then the separator is not prepended to the name. Parameters Attribute Description Required antfile The ant build file to call. This is relative to the basedir parameter, or, if that's not set, then to the basedir of the current build file. If this parameter is not set, then it will default to "build.xml". No basedir The directory to use as a "basedir" for the remote Ant build. If not set, it will use the antfile's owning directory. No if Acts just like an "if" parameter on a target, and will be applied to each generated target. No unless Acts just like an "unless" parameter on a target, and will be applied to each generated target. No targets A list of all targets to generate as local artificial targets, with the if and unless parameters of this project element. The target list is a comma-separated list of target names. Order does not matter. Yes, if target is not specified target A single target name to generate as a local artificial target, with the if and unless parameters of this project element. This differs slightly from targets in that the attribute specifies only a single target name. This and the targets attributes may be safely used together. Yes, if targets is not specified name Used in the generation of the artificial target names. Yes Nested Elements property Allows for passing a property to the underlying Ant task. See the corresponding task in Ant's documentation. PropertySet Allows for passing a PropertySet to the underlying Ant task. See the corresponding type in Ant's documentation.

Examples

<subprojects> <project name="a" antfile="a.xml" targets="all, main, clean" /> <project name="b" antfile="b.xml" targets="all, main, clean" /> <project name="c" antfile="c.xml" targets="main" /> </subprojects> Defines seven new targets: a::all performs an <ant> task on the "all" target of "a.xml" a::main performs an <ant> task on the "main" target of "a.xml" a::clean performs an <ant> task on the "clean" target of "a.xml" b::all performs an <ant> task on the "all" target of "b.xml" b::main performs an <ant> task on the "main" target of "b.xml" b::clean performs an <ant> task on the "clean" target of "b.xml" c::main performs an <ant> task on the "main" target of "c.xml"