cvs commit: ant/proposal/xdocs/src/org/apache/tools/ant/taskdefs Property.xml

[jesse]

jesse       2003/04/28 17:07:23

  Added:       proposal/xdocs/src/org/apache/tools/ant/taskdefs
                        Property.xml
  Log:
  Merge file for <property>
  
  Revision  Changes    Path
  1.1                  
ant/proposal/xdocs/src/org/apache/tools/ant/taskdefs/Property.xml
  
  Index: Property.xml
  ===================================================================
  <!-- property task -->
  <external>
  <description>
  
  <p>Sets a property (by name and value), or set of properties (from file or 
resource) in the project.</p>
  
  <p>Properties are case sensitive.</p>
  
  <p>Properties are immutable: whoever sets a property first freezes it for the 
rest of the build; they are most definately not variable.</p>
  
  <p>There are five ways to set properties:
    <ul>
      <li>By supplying both the name and value attribute.</li>
      <li>By supplying both the name and refid attribute.</li>
      <li>By setting the file attribute with the filename of the property file 
to load. This property file has the format as defined by the file used in the 
class java.util.Properties.</li>
      <li>By setting the resource attribute with the resource name of the 
property file to load. This property file has the format as defined by the file 
used in the class java.util.Properties.</li>
      <li>By setting the environment attribute with a prefix to use. Properties 
will be defined for every environment variable by prefixing the supplied name 
and a period to the name of the variable.</li>
    </ul>
  </p>  
  <p>Although combinations of these ways are possible, only one should be used 
at a time. Problems might occur with the order in which properties are set, for 
instance.</p>
  
  <p>The value part of the properties being set, might contain references to 
other properties. These references are resolved at the time these properties 
are set. This also holds for properties loaded from a property file.</p>
  
  <p>A list of predefined properties can be found here.</p>
  
  </description>
  
  <section anchor="examples" name="Examples">
  <pre>  &lt;property name=&quot;foo.dist&quot; 
value=&quot;dist&quot;/&gt;</pre>
  <p>sets the property <code>foo.dist</code> to the value &quot;dist&quot;.</p>
  <pre>  &lt;property file=&quot;foo.properties&quot;/&gt;</pre>
  <p>reads a set of properties from a file called 
&quot;foo.properties&quot;.</p>
  <pre>  &lt;property resource=&quot;foo.properties&quot;/&gt;</pre>
  <p>reads a set of properties from a resource called 
&quot;foo.properties&quot;.</p>
  <p>Note that you can reference a global properties file for all of your Ant
  builds using the following:</p>
  <pre>  &lt;property 
file=&quot;${user.home}/.ant-global.properties&quot;/&gt;</pre>
  <p>since the &quot;user.home&quot; property is defined by the Java virtual 
machine
  to be your home directory.  Where the &quot;user.home&quot; property resolves 
to in
  the file system depends on the operating system version and the JVM 
implementation.
  On Unix based systems, this will map to the user's home directory. On modern 
Windows
  variants, this will most likely resolve to the user's directory in the 
&quot;Documents
  and Settings&quot; folder. Older windows variants such as Windows 98/ME are 
less 
  predictable, as are other operating system/JVM combinations.</p>
  
  <pre>
    &lt;property environment=&quot;env&quot;/&gt;
    &lt;echo message=&quot;Number of Processors = 
${env.NUMBER_OF_PROCESSORS}&quot;/&gt;
    &lt;echo message=&quot;ANT_HOME is set to = ${env.ANT_HOME}&quot;/&gt;
  </pre>
  <p>reads the system environment variables and stores them in properties, 
prefixed with &quot;env&quot;.
  Note that this only works on <em>select</em> operating systems.
  Two of the values are shown being echoed. 
  </p>
  
  </section>
  </external>