From 8da250af7aff87e749da10befee6b3e69a014bcd Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Wed, 29 Oct 2008 16:38:10 +0000 Subject: [PATCH] add some examples git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@708931 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/CoreTasks/local.html | 131 +++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) diff --git a/docs/manual/CoreTasks/local.html b/docs/manual/CoreTasks/local.html index 753b44dec..9c214ca95 100644 --- a/docs/manual/CoreTasks/local.html +++ b/docs/manual/CoreTasks/local.html @@ -36,6 +36,9 @@ level effectively makes the property local to the "anonymous target" in which top-level operations are carried out; it will not be defined for other targets in the buildfile. Since Ant 1.8

+

A property is made local if the <local> task + preceedes its definition. See the examples section.

+

Parameters

@@ -50,6 +53,134 @@ in the buildfile. Since Ant 1.8

+

Examples

+ +

Temporarily shadow a global property's value

+ +
+    <property name="foo" value="foo"/>
+
+    <target name="step1">
+        <echo>Before local: foo is ${foo}</echo>
+        <local name="foo"/>
+        <property name="foo" value="bar"/>
+        <echo>After local: foo is ${foo}</echo>
+    </target>
+
+    <target name="step2" depends="step1">
+        <echo>In step2: foo is ${foo}</echo>
+    </target>
+
+ +

outputs

+ +
+step1:
+     [echo] Before local: foo is foo
+     [echo] After local: foo is bar
+
+step2:
+     [echo] In step2: foo is foo
+
+ +

here the local-task shadowed the global definition + of foo for the remainder of the target step1.

+ +

Creating thread local properties

+ +
+    <property name="foo" value="foo"/>
+
+    <parallel>
+        <echo>global 1: foo is ${foo}</echo>
+        <sequential>
+            <local name="foo"/>
+            <property name="foo" value="bar.1"/>
+            <echo>First sequential: foo is ${foo}</echo>
+        </sequential>
+        <sequential>
+            <sleep seconds="1"/>
+            <echo>global 2: foo is ${foo}</echo>
+        </sequential>
+        <sequential>
+            <local name="foo"/>
+            <property name="foo" value="bar.2"/>
+            <echo>Second sequential: foo is ${foo}</echo>
+        </sequential>
+        <echo>global 3: foo is ${foo}</echo>
+    </parallel>
+
+ +

outputs something similar to

+ +
+     [echo] global 3: foo is foo
+     [echo] global 1: foo is foo
+     [echo] First sequential: foo is bar.1
+     [echo] Second sequential: foo is bar.2
+     [echo] global 2: foo is foo
+
+ +

Use inside macrodef

+ +

This probably is where local can be applied in the most useful + way. If you needed a "temporary property" inside a macrodef in Ant + prior to Ant 1.8.0 you had to try to come up with a property name + that would be unique across macro invocations.

+ +

Say you wanted to write a macro that created the parent directory + of a given file. A naive approach would be:

+ +
+    <macrodef name="makeparentdir">
+        <attribute name="file"/>
+        <sequential>
+            <dirname property="parent" file="@{file}"/>
+            <mkdir dir="${parent}"/>
+        </sequential>
+    </macrodef>
+    <makeparentdir file="some-dir/some-file"/>
+
+ +

but this would create a global property "parent" on the first + invocation - and since properties are not mutable, any subsequent + invocation will see the same value and try to create the same + directory as the first invocation.

+ +

The recommendation prior to Ant 1.8.0 was to use a property name + based on one of the macro's attributes, like

+ +
+    <macrodef name="makeparentdir">
+        <attribute name="file"/>
+        <sequential>
+            <dirname property="parent.@{file}" file="@{file}"/>
+            <mkdir dir="${parent.@{file}}"/>
+        </sequential>
+    </macrodef>
+
+ +

Now invocations for different files will set different properties + and the directories will get created. Unfortunately this "pollutes" + the global properties space. In addition it may be hard to come up + with unique names in some cases.

+ +

Enter <local>:

+ +
+    <macrodef name="makeparentdir">
+        <attribute name="file"/>
+        <sequential>
+            <local name="parent"/>
+            <dirname property="parent" file="@{file}"/>
+            <mkdir dir="${parent}"/>
+        </sequential>
+    </macrodef>
+
+ +

Each invocation gets its own property name "parent" and there will + be no global property of that name at all.

+