A target is a container of tasks that cooperate to reach a + desired state during the build process.
+ +Targets can depend on other targets and Ant ensures that these + other targets have been executed before the current target. For + example you might have a target for compiling, for example, and a + target for creating a distributable. You can only build a + distributable when you have compiled first, so the distribute + target depends on the compile target.
+ +Ant tries to execute the targets in the depends
+ attribute in the order they appear (from left to right). Keep in
+ mind that it is possible that a target can get executed earlier
+ when an earlier target depends on it:
++ +<target name="A"/> +<target name="B" depends="A"/> +<target name="C" depends="B"/> +<target name="D" depends="C,B,A"/>+
Suppose we want to execute target D. From its
+ depends attribute, you might think that first target
+ C, then B and then A is executed. Wrong! C depends on B, and B
+ depends on A, so first A is executed, then B, then C, and finally
+ D.
In a chain of dependencies stretching back from a given target + such as D above, each target gets executed only once, even when + more than one target depends on it. Thus, executing the D target + will first result in C being called, which in turn will first call + B, which in turn will first call A. After A, then B, then C have + executed, execution returns to the dependency list of D, which + will not call B and A, since they were already called in + process of dependency resolution for C and B respectively as + dependencies of D. Had no such dependencies been discovered in + processing C and B, B and A would have been executed after C in + processing D's dependency list.
+ +A target also has the ability to perform its execution if (or
+ unless) a property has been set. This allows, for example, better
+ control on the building process depending on the state of the
+ system (java version, OS, command-line property defines, etc.).
+ To make a target sense this property, you should add
+ the if (or unless) attribute with the
+ name of the property that the target should react
+ to. Note: In the most simple case Ant will only
+ check whether the property has been set, the value doesn't matter,
+ but using property expansions you can build more complex
+ conditions. See
+ the properties page for
+ more details. For example:
++ +<target name="build-module-A" if="module-A-present"/>+<target name="build-own-fake-module-A" unless="module-A-present"/>+
In the first example, if the module-A-present
+ property is set (to any value, e.g. false), the target will
+ be run. In the second example, if
+ the module-A-present property is set (again, to any
+ value), the target will not be run.
Only one propertyname can be specified in the if/unless + clause. If you want to check multiple conditions, you can use a + dependend target for computing the result for the check:
+ ++ ++<target name="myTarget" depends="myTarget.check" if="myTarget.run"> + <echo>Files foo.txt and bar.txt are present.</echo> +</target> + +<target name="myTarget.check"> + <condition property="myTarget.run"> + <and> + <available file="foo.txt"/> + <available file="bar.txt"/> + </and> + </condition> +</target> +
If no if and no unless attribute is
+ present, the target will always be executed.
Important: the if and unless
+ attributes only enable or disable the target to which they are
+ attached. They do not control whether or not targets that a
+ conditional target depends upon get executed. In fact, they do
+ not even get evaluated until the target is about to be executed,
+ and all its predecessors have already run.
+
+
The optional description attribute can be used to
+ provide a one-line description of this target, which is printed by
+ the -projecthelp command-line option. Targets without
+ such a description are deemed internal and will not be listed,
+ unless either the -verbose or -debug
+ option is used.
It is a good practice to place
+ your tstamp tasks in a
+ so-called initialization target, on which all other targets
+ depend. Make sure that target is always the first one in the
+ depends list of the other targets. In this manual, most
+ initialization targets have the
+ name "init".
If the depends attribute and the if/unless attribute are set, the + depends attribute is executed first.
+ +A target has the following attributes:
+ +| Attribute | +Description | +Required | +
| name | +the name of the target. | +Yes | +
| depends | +a comma-separated list of names of targets on + which this target depends. | +No | +
| if | +the name of the property that must be set in + order for this target to execute, + or something evaluating to + true. | +No | +
| unless | +the name of the property that must not be set + in order for this target to execute, + or something evaluating to + false. | +No | +
| description | +a short description of this target's function. | +No | +
| group | +Adds the current target to the depends list of + the named target-group. + since Ant 1.8.0. | +No | +
A target name can be any alphanumeric string valid in the + encoding of the XML file. The empty string "" is in this + set, as is comma "," and space " ". Please + avoid using these, as they will not be supported in future Ant + versions because of all the confusion they cause. IDE support of + unusual target names, or any target name containing spaces, varies + with the IDE.
+ +Targets beginning with a hyphen such
+ as "-restart" are valid, and can be used to
+ name targets that should not be called directly from the command
+ line.
since Ant 1.8.0.
+ +Target-Groups are similar to targets in that they have a name and + a depends list and can be executed from the command line. Just + like targets they represent a state during the build process.
+ +Unlike targets they don't contain any tasks, their main purpose + is to collect targets that contribute to the desired state in + their depends list.
+ +Targets can add themselves to a target-group's depends list via + their group attribute. The targets that add themselves will be + added after the targets of the explicit depends-attribute of the + target-group, if multiple targets add themselves, their relative + order is not defined.
+ +The main purpose of a target-group is to act as an extension + point for build files designed to + be imported. In the imported + file a target-groups defines a state that must be reached and + targets from other build files can join the depends list of said + target-group in order to contribute to that state.
+ +For example your imported build file may need to compile code, it + might look like:
++ ++<target name="create-directory-layout"> + ... +</target> +<target-group name="ready-to-compile" + depends="create-directory-layout"/> +<target name="compile" depends="ready-to-compile"> + ... +</target> +
And you need to generate some source before compilation, then in + your main build file you may use something like
++ ++<target name="generate-sources" + group="ready-to-compile"> + ... +</target> +
This will ensure that the generate-sources target is + executed before the compile target.
+ +Don't rely on the order of the depends list, + if generate-sources depends + on create-directory-layout then it must explicitly depend + on it via its own depends attribute.
+ + diff --git a/docs/manual/using.html b/docs/manual/using.html index 4cb91feb4..5bd4983de 100644 --- a/docs/manual/using.html +++ b/docs/manual/using.html @@ -85,135 +85,9 @@ only specifies the order in which targets should be executed - it does not affect whether the target that specifies the dependency(s) gets executed if the dependent target(s) did not (need to) run. -Ant tries to execute the targets in the depends
-attribute in the order
-they appear (from left to right). Keep in mind that it is possible that a target
-can get executed earlier when an earlier target depends on it:
--<target name="A"/> -<target name="B" depends="A"/> -<target name="C" depends="B"/> -<target name="D" depends="C,B,A"/>-
Suppose we want to execute target D. From its
-depends attribute, you
-might think that first target C, then B and then A is executed.
-Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.
In a chain of dependencies stretching back from a given target such -as D above, each target gets executed only once, even when more than -one target depends on it. Thus, executing the D target will first -result in C being called, which in turn will first call B, which in -turn will first call A. After A, then B, then C have executed, -execution returns to the dependency list of D, which will not -call B and A, since they were already called in process of dependency -resolution for C and B respectively as dependencies of D. Had no such -dependencies been discovered in processing C and B, B and A would -have been executed after C in processing D's dependency list.
-A target also has the ability to perform its execution if (or
-unless) a property has been set. This allows, for example, better
-control on the building process depending on the state of the system
-(java version, OS, command-line property defines, etc.). To make a target
-sense this property, you should add the if (or
-unless) attribute with the name of the property that the target
-should react to. Note: Ant will only check whether
-the property has been set, the value doesn't matter. A property set
-to the empty string is still an existing property. For example:
--<target name="build-module-A" if="module-A-present"/>-<target name="build-own-fake-module-A" unless="module-A-present"/>-
In the first example, if the module-A-present
-property is set (to any value, e.g. false), the target will be run. In the second
-example, if the module-A-present property is set
-(again, to any value), the target will not be run.
-
Only one propertyname can be specified in the if/unless clause. If you want to check -multiple conditions, you can use a dependend target for computing the result for the check:
---<target name="myTarget" depends="myTarget.check" if="myTarget.run"> - <echo>Files foo.txt and bar.txt are present.</echo> -</target> - -<target name="myTarget.check"> - <condition property="myTarget.run"> - <and> - <available file="foo.txt"/> - <available file="bar.txt"/> - </and> - </condition> -</target> -
If no if and no unless attribute is present,
-the target will always be executed.
-Important: the if and unless attributes only
-enable or disable the target to which they are attached. They do not control
-whether or not targets that a conditional target depends upon get executed.
-In fact, they do not even get evaluated until the target is about to be executed,
-and all its predecessors have already run.
-
-
The optional description attribute can be used to provide a one-line description of this target, which is printed by the
--projecthelp command-line option. Targets
-without such a description are deemed internal and will not be listed,
-unless either the -verbose or
--debug option is used.
-
It is a good practice to place your tstamp tasks in a so-called
-initialization target, on which
-all other targets depend. Make sure that target is always the first one in
-the depends list of the other targets. In this manual, most initialization targets
-have the name "init".
If the depends attribute and the if/unless attribute are set, the depends attribute is -executed first.
-A target has the following attributes:
-| Attribute | -Description | -Required | -
| name | -the name of the target. | -Yes | -
| depends | -a comma-separated list of names of targets on which this - target depends. | -No | -
| if | -the name of the property that must be set in order for this - target to execute, or something evaluating to true. | -No | -
| unless | -the name of the property that must not be set in order - for this target to execute, or something evaluating to false. | -No | -
| description | -a short description of this target's function. | -No | -
A target name can be any alphanumeric string valid in the encoding of the XML -file. The empty string "" is in this set, as is -comma "," and space " ". -Please avoid using these, as they will not be supported in future Ant versions -because of all the confusion they cause. IDE support of unusual target names, -or any target name containing spaces, varies with the IDE.
-Targets beginning with a hyphen such as "-restart"
-are valid, and can be used
-to name targets that should not be called directly from the command line.
More information can be found in the + dedicated manual page.
A task is a piece of code that can be executed.
diff --git a/docs/manual/usinglist.html b/docs/manual/usinglist.html index e2abae99b..a3f1cb81d 100644 --- a/docs/manual/usinglist.html +++ b/docs/manual/usinglist.html @@ -32,7 +32,7 @@