source: release-kits/lirk3/bin/ant-installer/web/manual/manual/CoreTasks/property.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 9.7 KB
Line 
1<!--
2 Licensed to the Apache Software Foundation (ASF) under one or more
3 contributor license agreements. See the NOTICE file distributed with
4 this work for additional information regarding copyright ownership.
5 The ASF licenses this file to You under the Apache License, Version 2.0
6 (the "License"); you may not use this file except in compliance with
7 the License. You may obtain a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16-->
17<html>
18
19<head>
20<meta http-equiv="Content-Language" content="en-us">
21<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
22<title>Property Task</title>
23</head>
24
25<body>
26
27<h2><a name="property">Property</a></h2>
28<h3>Description</h3>
29<p>Sets a <a href="../using.html#properties">property</a>
30(by name and value), or set of properties (from file or
31resource) in the project. Properties are case sensitive.</p>
32 Properties are immutable: whoever sets a property first freezes it for the
33 rest of the build; they are most definitely not variables.
34<p>There are six ways to set properties:</p>
35<ul>
36 <li>By supplying both the <i>name</i> and <i>value</i> attribute.</li>
37 <li>By supplying both the <i>name</i> and <i>refid</i> attribute.</li>
38 <li>By setting the <i>file</i> attribute with the filename of the property
39 file to load. This property file has the format as defined by the file used
40 in the class java.util.Properties, with the same rules about how
41 non-ISO8859-1 characters must be escaped.</li>
42 <li>By setting the <i>url</i> attribute with the url from which to load the
43 properties. This url must be directed to a file that has the format as defined
44 by the file used in the class java.util.Properties.</li>
45 <li>By setting the <i>resource</i> attribute with the resource name of the
46 property file to load. A resource is a property file on the current
47 classpath, or on the specified classpath.</li>
48 <li>By setting the <i>environment</i> attribute with a prefix to use.
49 Properties will be defined for every environment variable by
50 prefixing the supplied name and a period to the name of the variable.</li>
51</ul>
52<p>Although combinations of these ways are possible, only one should be used
53at a time. Problems might occur with the order in which properties are set, for
54instance.</p>
55<p>The value part of the properties being set, might contain references to other
56properties. These references are resolved at the time these properties are set.
57This also holds for properties loaded from a property file.</p>
58<p>A list of predefined properties can be found <a
59href="../using.html#built-in-props">here</a>.</p>
60
61<h4>OpenVMS Users</h4>
62<p>With the <code>environment</code> attribute this task will load all defined
63logicals on an OpenVMS system. Logicals with multiple equivalence names get
64mapped to a property whose value is a comma separated list of all equivalence
65names. If a logical is defined in multiple tables, only the most local
66definition is available (the table priority order being PROCESS, JOB, GROUP,
67SYSTEM).
68</p>
69
70<h3>Parameters</h3>
71<table border="1" cellpadding="2" cellspacing="0">
72 <tr>
73 <td valign="top"><b>Attribute</b></td>
74 <td valign="top"><b>Description</b></td>
75 <td align="center" valign="top"><b>Required</b></td>
76 </tr>
77 <tr>
78 <td valign="top">name</td>
79 <td valign="top">the name of the property to set.</td>
80 <td valign="top" align="center">No</td>
81 </tr>
82 <tr>
83 <td valign="top">value</td>
84 <td valign="top">the value of the property.</td>
85 <td valign="middle" align="center" rowspan="3">One of these, when using the
86 name attribute</td>
87 </tr>
88 <tr>
89 <td valign="top">location</td>
90 <td valign="top">Sets the property to the absolute filename of the
91 given file. If the value of this attribute is an absolute path, it
92 is left unchanged (with / and \ characters converted to the
93 current platforms conventions). Otherwise it is taken as a path
94 relative to the project's basedir and expanded.</td>
95 </tr>
96 <tr>
97 <td valign="top">refid</td>
98 <td valign="top"><a href="../using.html#references">Reference</a> to an object
99 defined elsewhere. Only yields reasonable results for references
100 to <a href="../using.html#path">PATH like structures</a> or properties.</td>
101 </tr>
102 <tr>
103 <td valign="top">resource</td>
104 <td valign="top">the resource name of the property file.</td>
105 <td valign="middle" align="center" rowspan="4">One of these, when
106 <b>not</b> using the name attribute</td>
107 </tr>
108 <tr>
109 <td valign="top">file</td>
110 <td valign="top">the filename of the property file .</td>
111 </tr>
112 <tr>
113 <td valign="top">url</td>
114 <td valign="top">the url from which to read properties.</td>
115 </tr>
116 <tr>
117 <td valign="top">environment</td>
118 <td valign="top">the prefix to use when retrieving environment variables. Thus
119 if you specify environment=&quot;myenv&quot; you will be able to access OS-specific
120 environment variables via property names &quot;myenv.PATH&quot; or
121 &quot;myenv.TERM&quot;. Note that if you supply a property name with a final
122 &quot;.&quot; it will not be doubled. ie environment=&quot;myenv.&quot; will still
123 allow access of environment variables through &quot;myenv.PATH&quot; and
124 &quot;myenv.TERM&quot;. This functionality is currently only implemented
125 on select platforms. Feel free to send patches to increase the number of platforms
126 this functionality is supported on ;).<br>
127 Note also that properties are case sensitive, even if the
128 environment variables on your operating system are not, e.g. it
129 will be ${env.Path} not ${env.PATH} on Windows 2000.</td>
130
131 </tr>
132 <tr>
133 <td valign="top">classpath</td>
134 <td valign="top">the classpath to use when looking up a resource.</td>
135 <td align="center" valign="top">No</td>
136 </tr>
137 <tr>
138 <td valign="top">classpathref</td>
139 <td valign="top">the classpath to use when looking up a resource,
140 given as <a href="../using.html#references">reference</a> to a <code>&lt;path&gt;</code> defined
141 elsewhere..</td>
142 <td align="center" valign="top">No</td>
143 </tr>
144 <tr>
145 <td valign="top">prefix</td>
146 <td valign="top">Prefix to apply to properties loaded using <code>file</code>
147 or <code>resource</code>. A "." is appended to the prefix if not specified.</td>
148 <td align="center" valign="top">No</td>
149 </tr>
150</table>
151<h3>Parameters specified as nested elements</h3>
152<h4>classpath</h4>
153<p><code>Property</code>'s <i>classpath</i> attribute is a <a
154href="../using.html#path">PATH like structure</a> and can also be set via a nested
155<i>classpath</i> element.</p>
156<h3>Examples</h3>
157<pre> &lt;property name=&quot;foo.dist&quot; value=&quot;dist&quot;/&gt;</pre>
158<p>sets the property <code>foo.dist</code> to the value &quot;dist&quot;.</p>
159<pre> &lt;property file=&quot;foo.properties&quot;/&gt;</pre>
160<p>reads a set of properties from a file called &quot;foo.properties&quot;.</p>
161<pre> &lt;property url=&quot;http://www.mysite.com/bla/props/foo.properties&quot;/&gt;</pre>
162<p>reads a set of properties from the address &quot;http://www.mysite.com/bla/props/foo.properties&quot;.</p>
163<pre> &lt;property resource=&quot;foo.properties&quot;/&gt;</pre>
164<p>reads a set of properties from a resource called &quot;foo.properties&quot;.</p>
165<p>Note that you can reference a global properties file for all of your Ant
166builds using the following:</p>
167<pre> &lt;property file=&quot;${user.home}/.ant-global.properties&quot;/&gt;</pre>
168<p>since the &quot;user.home&quot; property is defined by the Java virtual machine
169to be your home directory. Where the &quot;user.home&quot; property resolves to in
170the file system depends on the operating system version and the JVM implementation.
171On Unix based systems, this will map to the user's home directory. On modern Windows
172variants, this will most likely resolve to the user's directory in the &quot;Documents
173and Settings&quot; folder. Older windows variants such as Windows 98/ME are less
174predictable, as are other operating system/JVM combinations.</p>
175
176<pre>
177 &lt;property environment=&quot;env&quot;/&gt;
178 &lt;echo message=&quot;Number of Processors = ${env.NUMBER_OF_PROCESSORS}&quot;/&gt;
179 &lt;echo message=&quot;ANT_HOME is set to = ${env.ANT_HOME}&quot;/&gt;
180</pre>
181<p>reads the system environment variables and stores them in properties, prefixed with &quot;env&quot;.
182Note that this only works on <em>select</em> operating systems.
183Two of the values are shown being echoed.
184</p>
185
186<h3>Property Files</h3>
187
188As stated, this task will load in a properties file stored in the file
189system, or as a resource on a classpath. Here are some interesting facts
190about this feature
191<ol>
192<li>If the file is not there, nothing is printed except at -verbose log
193level. This lets you have optional configuration files for every
194project, that team members can customize.
195<li>The rules for this format are laid down
196<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html#load(java.io.InputStream)">by Sun</a>.
197This makes it hard for Team Ant to field bug reports about it.
198<li>Trailing spaces are not stripped. It may have been what you wanted.
199<li>Want unusual characters? Escape them \u0456 or \" style.
200<li>Ant Properties are expanded in the file.
201</ol>
202In-file property expansion is very cool. Learn to use it.
203<p>
204Example:
205<pre>
206build.compiler=jikes
207deploy.server=lucky
208deploy.port=8080
209deploy.url=http://${deploy.server}:${deploy.port}/
210</pre>
211
212
213
214</body>
215</html>
216
Note: See TracBrowser for help on using the repository browser.