315 lines
14 KiB
HTML
315 lines
14 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Language" content="en-ca" />
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="description" content="Properties" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="../style.css" />
|
||
|
|
<title>NAnt - Properties</title>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar">
|
||
|
|
<tr>
|
||
|
|
<td class="NavBar-Cell">
|
||
|
|
<a title="NAnt home page" href="http://nant.sourceforge.net"><b>NAnt</b></a> <img src="../images/arrow.gif" alt="->" width="13" height="9" />
|
||
|
|
<a href="../index.html">Help</a> <img alt="->" src="../images/arrow.gif" /> <a href="index.html">
|
||
|
|
Fundamentals</a> <img height="9" alt="->" src="../images/arrow.gif" width="13" />
|
||
|
|
Properties
|
||
|
|
</td>
|
||
|
|
<td class="NavBar-Cell" align="right">
|
||
|
|
v0.91
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<h1>Properties</h1>
|
||
|
|
|
||
|
|
<h2><a id="contents" />Contents</h2>
|
||
|
|
<div>
|
||
|
|
1 <a href="#introduction">Introduction</a><br />
|
||
|
|
2 <a href="#naming-rules">Naming rules</a><br />
|
||
|
|
3 <a href="#built-in-properties">Built-in Properties</a><br />
|
||
|
|
<div style="margin-left: 20px;">
|
||
|
|
3.1 <a href="#framework-related-properties">Framework related Properties</a><br />
|
||
|
|
3.2 <a href="#platform-related-properties">Platform related Properties</a>
|
||
|
|
</div>
|
||
|
|
4 <a href="#readonly-properties">Read-only Properties</a><br />
|
||
|
|
5 <a href="#global-properties">Global Properties</a><br />
|
||
|
|
6 <a href="#examples">Examples</a><br />
|
||
|
|
</div>
|
||
|
|
<h2><a id="introduction" />1 Introduction</h2>
|
||
|
|
<p>A project can have a set of properties. These might be set in the
|
||
|
|
buildfile by the <a href="../tasks/property.html"><property></a> task, or
|
||
|
|
might be set outside NAnt. A property has a name and a value. Properties
|
||
|
|
may be used in the value of task attributes. This is done by placing the
|
||
|
|
property name between "<code>${</code>" and "<code>}</code>" in the attribute
|
||
|
|
value. Properties may also be used in <a href="expressions.html">expressions</a>.
|
||
|
|
</p>
|
||
|
|
<h2><a id="naming-rules" />2 Naming rules</h2>
|
||
|
|
<p>A property name is a string of the following characters:</p>
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
letters (<code>A-Z</code>, <code>a-z</code>),</li>
|
||
|
|
<li>
|
||
|
|
digits (<code>0-9</code>),</li>
|
||
|
|
<li>
|
||
|
|
underscore characters (<code>_</code>),</li>
|
||
|
|
<li>
|
||
|
|
dash characters (<code>-</code>),</li>
|
||
|
|
<li>
|
||
|
|
dot characters (<code>.</code>),</li>
|
||
|
|
</ul>
|
||
|
|
<p>In addition, a valid property name must start with a letter or an underscore and
|
||
|
|
must end with a letter, digit or an uderscore.</p>
|
||
|
|
<p>Examples of valid property names include:</p>
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<code>propertyname</code></li>
|
||
|
|
<li>
|
||
|
|
<code>property.name.with.dots</code></li>
|
||
|
|
<li>
|
||
|
|
<code>property-name-with-dashes</code></li>
|
||
|
|
<li>
|
||
|
|
<code>property.name-with.both-dots.and-dashes</code></li>
|
||
|
|
<li>
|
||
|
|
<code>__prop---3-erty__</code></li>
|
||
|
|
<li>
|
||
|
|
<code>__prop.1...erty__</code></li>
|
||
|
|
<li>
|
||
|
|
<code>property1</code></li>
|
||
|
|
<li>
|
||
|
|
<code>property1.0</code></li>
|
||
|
|
<li>
|
||
|
|
<code>property2.0.0</code></li>
|
||
|
|
<li>
|
||
|
|
<code>_property-2-1__</code></li>
|
||
|
|
<li>
|
||
|
|
<code>property-1-name_</code></li>
|
||
|
|
<li>
|
||
|
|
<code>property-1.0-name</code></li>
|
||
|
|
</ul>
|
||
|
|
<p>The following property names are not valid in NAnt:</p>
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<code>!@#!@$!@</code> (contains illegal characters)</li>
|
||
|
|
<li>
|
||
|
|
<code>.aaaaa</code> (starts with a dot)</li>
|
||
|
|
<li>
|
||
|
|
<code>-aaaaa</code> (starts with a dash)</li>
|
||
|
|
<li>
|
||
|
|
<code>1aaaaa</code> (starts with a digit)</li>
|
||
|
|
<li>
|
||
|
|
<code>aaaaa.aaa.a.a.a.a-</code> (ends with a dash)</li>
|
||
|
|
<li>
|
||
|
|
<code>aaaaa.aaa.a.a.a.a.</code> (ends with a dot)</li>
|
||
|
|
</ul>
|
||
|
|
<h2><a id="built-in-properties" />3 Built-in Properties</h2>
|
||
|
|
<p>NAnt has these built-in properties:</p>
|
||
|
|
<div class="table">
|
||
|
|
<table>
|
||
|
|
<tbody>
|
||
|
|
<tr>
|
||
|
|
<th>
|
||
|
|
Property</th>
|
||
|
|
<th>
|
||
|
|
Description</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.version</td>
|
||
|
|
<td><i>Deprecated.</i> The version of NAnt.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.filename</td>
|
||
|
|
<td><i>Deprecated.</i> The full path to the NAnt assembly.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.location</td>
|
||
|
|
<td><i>Deprecated.</i> The base directory of the NAnt assembly.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.project.basedir</td>
|
||
|
|
<td><i>Deprecated.</i> The absolute path of the project's basedir.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.project.buildfile</td>
|
||
|
|
<td><i>Deprecated.</i> The absolute path of the buildfile.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.project.name</td>
|
||
|
|
<td><i>Deprecated.</i> The name of the project.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.project.default</td>
|
||
|
|
<td><i>Deprecated.</i> The name of the project's default target.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.onsuccess</td>
|
||
|
|
<td>The name of a target to be executed when the build succeeds.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.onfailure</td>
|
||
|
|
<td>The name of a target to be executed when the build fails.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<h3><a id="framework-related-properties" />3.1 Framework related Properties:</h3>
|
||
|
|
<div class="table">
|
||
|
|
<table>
|
||
|
|
<tbody>
|
||
|
|
<tr>
|
||
|
|
<th>
|
||
|
|
Property</th>
|
||
|
|
<th>
|
||
|
|
Description</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.settings.currentframework</td>
|
||
|
|
<td>The current target framework, eg. 'net-1.0'.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.settings.currentframework.description</td>
|
||
|
|
<td><i>Deprecated.</i> Description of the current target framework.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.settings.currentframework.frameworkdirectory</td>
|
||
|
|
<td><i>Deprecated.</i> The framework directory of the current target framework.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.settings.currentframework.sdkdirectory</td>
|
||
|
|
<td><i>Deprecated.</i> The framework SDK directory of the current target framework.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.settings.currentframework.frameworkassemblydirectory</td>
|
||
|
|
<td><i>Deprecated.</i> The framework assembly directory of the current target
|
||
|
|
framework.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.settings.currentframework.runtimeengine</td>
|
||
|
|
<td><i>Deprecated.</i> The runtime engine of the current target framework if used
|
||
|
|
eg. mono.exe.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<h3><a id="platform-related-properties" />3.2 Platform related Properties:</h3>
|
||
|
|
<div class="table">
|
||
|
|
<table>
|
||
|
|
<tbody>
|
||
|
|
<tr>
|
||
|
|
<th>
|
||
|
|
Property</th>
|
||
|
|
<th>
|
||
|
|
Description</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.platform.name</td>
|
||
|
|
<td><i>Deprecated.</i> The name of the platform on which NAnt is currently running
|
||
|
|
- either <code>win32</code> or <code>unix</code>.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.platform.win32</td>
|
||
|
|
<td><i>Deprecated.</i> Holds the value <code>true</code> if NAnt is running on the <code>
|
||
|
|
win32</code> platform; otherwise, <code>false</code>.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>nant.platform.unix</td>
|
||
|
|
<td><i>Deprecated.</i> Holds the value <code>true</code> if NAnt is running on the <code>
|
||
|
|
unix</code> platform; otherwise, <code>false</code>.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<h2><a id="readonly-properties" />4 Read-only Properties</h2>
|
||
|
|
<p>
|
||
|
|
A property can be explicitly marked read-only by setting the
|
||
|
|
"readonly" attribute on the <a href="../tasks/property.html"><property></a>
|
||
|
|
task to <b>true</b>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The value of a read-only property cannot be modified after it has been set.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
When attempting to override a read-only property using the <a href="../tasks/property.html">
|
||
|
|
<property></a> task, the new value will be ignored and a warning
|
||
|
|
message will be output in the build log. Attempting to override read-only
|
||
|
|
properties using any other means (eg. other tasks) will result in a build
|
||
|
|
failure.
|
||
|
|
</p>
|
||
|
|
<p><b>Note:</b> properties set on the command-line are always read-only.</p>
|
||
|
|
<h2><a id="global-properties" />5 Global Properties</h2>
|
||
|
|
<p>Properties that should be accessible to all build files on a system can be
|
||
|
|
defined in the <code><properties></code> node of the NAnt configuration
|
||
|
|
file (<code>NAnt.exe.config</code>).</p>
|
||
|
|
<p>By changing the value of the property in the NAnt configuration file, the
|
||
|
|
updated value will be accessible to all build files on the system:</p>
|
||
|
|
<pre class="code">
|
||
|
|
<?xml version="1.0"?>
|
||
|
|
<configuration>
|
||
|
|
...
|
||
|
|
<nant>
|
||
|
|
...
|
||
|
|
<properties>
|
||
|
|
<!-- properties defined here are accessible to all build files -->
|
||
|
|
<property name="company.name" value="Foo Ltd." readonly="true" />
|
||
|
|
</properties>
|
||
|
|
</nant>
|
||
|
|
</configuration>
|
||
|
|
</pre>
|
||
|
|
<p>Individual build files can then use this property:</p>
|
||
|
|
<pre class="code">
|
||
|
|
<?xml version="1.0"?>
|
||
|
|
<project name="test">
|
||
|
|
<echo message="Company: ${company.name}" />
|
||
|
|
</project>
|
||
|
|
</pre>
|
||
|
|
<p>The output of this build is:</p>
|
||
|
|
<pre>
|
||
|
|
[echo] Company: Foo Ltd.
|
||
|
|
</pre>
|
||
|
|
<h2><a id="example" /> 6 Examples</h2>
|
||
|
|
<p>The following build file demonstrates the use of property expansion:</p>
|
||
|
|
<pre class="code">
|
||
|
|
<?xml version="1.0"?>
|
||
|
|
<project name="Property Test" default="test" basedir=".">
|
||
|
|
<property name="project.name" value="PropertyTest"/>
|
||
|
|
<property name="project.version" value="1.0.0"/>
|
||
|
|
<target name="test">
|
||
|
|
<echo message="Building ${project.name}-${project.version}"/>
|
||
|
|
</target>
|
||
|
|
</project>
|
||
|
|
</pre>
|
||
|
|
<p>The output of this build is:</p>
|
||
|
|
<pre>
|
||
|
|
[echo] Building PropertyTest-1.0.0
|
||
|
|
</pre>
|
||
|
|
<p>The following build file demonstrates the use of properties in <a href="expressions.html">
|
||
|
|
expressions</a>. It evaluates the length of the property <code>project.name</code>
|
||
|
|
and displays it.</p>
|
||
|
|
<pre class="code">
|
||
|
|
<?xml version="1.0"?>
|
||
|
|
<project name="Expression Test" default="test" basedir=".">
|
||
|
|
<property name="project.name" value="Expression Test"/>
|
||
|
|
<target name="test">
|
||
|
|
<echo message="Project name consists of ${string::get-length(project.name)} characters."/>
|
||
|
|
</target>
|
||
|
|
</project>
|
||
|
|
</pre>
|
||
|
|
<p>The output of this build is:</p>
|
||
|
|
<pre>
|
||
|
|
[echo] Project name consists of 15 characters.
|
||
|
|
</pre>
|
||
|
|
<h3>See Also</h3>
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<a href="../tasks/property.html"><property></a>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<a href="../tasks/sysinfo.html"><sysinfo></a>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<a href="../tasks/tstamp.html"><tstamp></a>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</body>
|
||
|
|
</html>
|