← Back to branch summary

~mandel/ubuntuone-windows-installer/update_nunit_net_4

« back to all changes in this revision

Viewing changes to tools/Nant/doc/help/fundamentals/properties.html

  • Committer: Manuel de la Pena
  • Date: 2010-10-12 13:38:14 UTC
  • Revision ID: mandel@themacaque.com-20101012133814-nxp9kr2lx2jygmmx
Updated nant to work with .Net 4.0 and removed useless docs.

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/Nant/doc/help/fundamentals/properties.html
1
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
2
 
<html xmlns="http://www.w3.org/1999/xhtml">
3
 
    <head>
4
 
        <meta http-equiv="Content-Language" content="en-ca" />
5
 
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6
 
        <meta name="description" content="Properties" />
7
 
        <link rel="stylesheet" type="text/css" href="../style.css" />
8
 
        <title>NAnt - Properties</title>
9
 
    </head>
10
 
    <body>
11
 
        <table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar">
12
 
            <tr>
13
 
                <td class="NavBar-Cell">
14
 
                    <a title="NAnt home page" href="http://nant.sourceforge.net"><b>NAnt</b></a> <img src="../images/arrow.gif" alt="-&gt;" width="13" height="9" />
15
 
                    <a href="../index.html">Help</a> <img alt="-&gt;" src="../images/arrow.gif" /> <a href="index.html">
16
 
                        Fundamentals</a> <img height="9" alt="-&gt;" src="../images/arrow.gif" width="13" />
17
 
                    Properties
18
 
                </td>
19
 
                <td class="NavBar-Cell" align="right">
20
 
                    v0.90
21
 
                </td>
22
 
            </tr>
23
 
        </table>
24
 
        <h1>Properties</h1>
25
 
        
26
 
        <h2><a id="contents" />Contents</h2>
27
 
        <div>
28
 
            1 <a href="#introduction">Introduction</a><br />
29
 
            2 <a href="#naming-rules">Naming rules</a><br />
30
 
            3 <a href="#built-in-properties">Built-in Properties</a><br />
31
 
            <div style="margin-left: 20px;">
32
 
                3.1 <a href="#framework-related-properties">Framework related Properties</a><br />
33
 
                3.2 <a href="#platform-related-properties">Platform related Properties</a>
34
 
            </div>
35
 
            4 <a href="#readonly-properties">Read-only Properties</a><br />
36
 
            5 <a href="#global-properties">Global Properties</a><br />
37
 
            6 <a href="#examples">Examples</a><br />            
38
 
        </div>
39
 
        <h2><a id="introduction" />1 Introduction</h2>
40
 
        <p>A project can have a set of properties.&nbsp; These might be set in the 
41
 
            buildfile by the <a href="../tasks/property.html">&lt;property&gt;</a> task, or 
42
 
            might be set outside NAnt.&nbsp; A property has a name and a value. Properties 
43
 
            may be used in the value of task attributes. This is done by placing the 
44
 
            property name between "<code>${</code>" and "<code>}</code>" in the attribute 
45
 
            value. Properties may also be used in <a href="expressions.html">expressions</a>.
46
 
        </p>
47
 
        <h2><a id="naming-rules" />2 Naming rules</h2>
48
 
        <p>A property name is a string of the following characters:</p>
49
 
        <ul>
50
 
            <li>
51
 
                letters (<code>A-Z</code>, <code>a-z</code>),</li>
52
 
            <li>
53
 
                digits (<code>0-9</code>),</li>
54
 
            <li>
55
 
                underscore characters (<code>_</code>),</li>
56
 
            <li>
57
 
                dash characters (<code>-</code>),</li>
58
 
            <li>
59
 
                dot characters (<code>.</code>),</li>
60
 
        </ul>
61
 
        <p>In addition, a valid property name must start with a letter or an underscore and 
62
 
            must end with a letter, digit or an uderscore.</p>
63
 
        <p>Examples of valid property names include:</p>
64
 
        <ul>
65
 
            <li>
66
 
                <code>propertyname</code></li>
67
 
            <li>
68
 
                <code>property.name.with.dots</code></li>
69
 
            <li>
70
 
                <code>property-name-with-dashes</code></li>
71
 
            <li>
72
 
                <code>property.name-with.both-dots.and-dashes</code></li>
73
 
            <li>
74
 
                <code>__prop---3-erty__</code></li>
75
 
            <li>
76
 
                <code>__prop.1...erty__</code></li>
77
 
            <li>
78
 
                <code>property1</code></li>
79
 
            <li>
80
 
                <code>property1.0</code></li>
81
 
            <li>
82
 
                <code>property2.0.0</code></li>
83
 
            <li>
84
 
                <code>_property-2-1__</code></li>
85
 
            <li>
86
 
                <code>property-1-name_</code></li>
87
 
            <li>
88
 
                <code>property-1.0-name</code></li>
89
 
        </ul>
90
 
        <p>The following property names are not valid in NAnt:</p>
91
 
        <ul>
92
 
            <li>
93
 
                <code>!@#!@$!@</code> (contains illegal characters)</li>
94
 
            <li>
95
 
                <code>.aaaaa</code> (starts with a dot)</li>
96
 
            <li>
97
 
                <code>-aaaaa</code> (starts with a dash)</li>
98
 
            <li>
99
 
                <code>1aaaaa</code> (starts with a digit)</li>
100
 
            <li>
101
 
                <code>aaaaa.aaa.a.a.a.a-</code> (ends with a dash)</li>
102
 
            <li>
103
 
                <code>aaaaa.aaa.a.a.a.a.</code> (ends with a dot)</li>
104
 
        </ul>
105
 
        <h2><a id="built-in-properties" />3 Built-in Properties</h2>
106
 
        <p>NAnt has these built-in properties:</p>
107
 
        <div class="table">
108
 
            <table>
109
 
                <tbody>
110
 
                    <tr>
111
 
                        <th>
112
 
                            Property</th>
113
 
                        <th>
114
 
                            Description</th>
115
 
                    </tr>
116
 
                    <tr>
117
 
                        <td>nant.version</td>
118
 
                        <td><i>Deprecated.</i> The version of NAnt.</td>
119
 
                    </tr>
120
 
                    <tr>
121
 
                        <td>nant.filename</td>
122
 
                        <td><i>Deprecated.</i> The full path to the NAnt assembly.</td>
123
 
                    </tr>
124
 
                    <tr>
125
 
                        <td>nant.location</td>
126
 
                        <td><i>Deprecated.</i> The base directory of the NAnt assembly.</td>
127
 
                    </tr>
128
 
                    <tr>
129
 
                        <td>nant.project.basedir</td>
130
 
                        <td><i>Deprecated.</i> The absolute path of the project's basedir.</td>
131
 
                    </tr>
132
 
                    <tr>
133
 
                        <td>nant.project.buildfile</td>
134
 
                        <td><i>Deprecated.</i> The absolute path of the buildfile.</td>
135
 
                    </tr>
136
 
                    <tr>
137
 
                        <td>nant.project.name</td>
138
 
                        <td><i>Deprecated.</i> The name of the project.</td>
139
 
                    </tr>
140
 
                    <tr>
141
 
                        <td>nant.project.default</td>
142
 
                        <td><i>Deprecated.</i> The name of the project's default target.</td>
143
 
                    </tr>
144
 
                    <tr>
145
 
                        <td>nant.onsuccess</td>
146
 
                        <td>The name of a target to be executed when the build succeeds.</td>
147
 
                    </tr>
148
 
                    <tr>
149
 
                        <td>nant.onfailure</td>
150
 
                        <td>The name of a target to be executed when the build fails.</td>
151
 
                    </tr>
152
 
                </tbody>
153
 
            </table>
154
 
        </div>
155
 
        <h3><a id="framework-related-properties" />3.1 Framework related Properties:</h3>
156
 
        <div class="table">
157
 
            <table>
158
 
                <tbody>
159
 
                    <tr>
160
 
                        <th>
161
 
                            Property</th>
162
 
                        <th>
163
 
                            Description</th>
164
 
                    </tr>
165
 
                    <tr>
166
 
                        <td>nant.settings.currentframework</td>
167
 
                        <td>The current target framework, eg. 'net-1.0'.</td>
168
 
                    </tr>
169
 
                    <tr>
170
 
                        <td>nant.settings.currentframework.description</td>
171
 
                        <td><i>Deprecated.</i> Description of the current target framework.</td>
172
 
                    </tr>
173
 
                    <tr>
174
 
                        <td>nant.settings.currentframework.frameworkdirectory</td>
175
 
                        <td><i>Deprecated.</i> The framework directory of the current target framework.</td>
176
 
                    </tr>
177
 
                    <tr>
178
 
                        <td>nant.settings.currentframework.sdkdirectory</td>
179
 
                        <td><i>Deprecated.</i> The framework SDK directory of the current target framework.</td>
180
 
                    </tr>
181
 
                    <tr>
182
 
                        <td>nant.settings.currentframework.frameworkassemblydirectory</td>
183
 
                        <td><i>Deprecated.</i> The framework assembly directory of the current target 
184
 
                            framework.</td>
185
 
                    </tr>
186
 
                    <tr>
187
 
                        <td>nant.settings.currentframework.runtimeengine</td>
188
 
                        <td><i>Deprecated.</i> The runtime engine of the current target framework if used 
189
 
                            eg. mono.exe.</td>
190
 
                    </tr>
191
 
                </tbody>
192
 
            </table>
193
 
        </div>
194
 
        <h3><a id="platform-related-properties" />3.2 Platform related Properties:</h3>
195
 
        <div class="table">
196
 
            <table>
197
 
                <tbody>
198
 
                    <tr>
199
 
                        <th>
200
 
                            Property</th>
201
 
                        <th>
202
 
                            Description</th>
203
 
                    </tr>
204
 
                    <tr>
205
 
                        <td>nant.platform.name</td>
206
 
                        <td><i>Deprecated.</i> The name of the platform on which NAnt is currently running 
207
 
                            - either <code>win32</code> or <code>unix</code>.</td>
208
 
                    </tr>
209
 
                    <tr>
210
 
                        <td>nant.platform.win32</td>
211
 
                        <td><i>Deprecated.</i> Holds the value <code>true</code> if NAnt is running on the <code>
212
 
                                win32</code> platform; otherwise, <code>false</code>.</td>
213
 
                    </tr>
214
 
                    <tr>
215
 
                        <td>nant.platform.unix</td>
216
 
                        <td><i>Deprecated.</i> Holds the value <code>true</code> if NAnt is running on the <code>
217
 
                                unix</code> platform; otherwise, <code>false</code>.</td>
218
 
                    </tr>
219
 
                </tbody>
220
 
            </table>
221
 
        </div>
222
 
        <h2><a id="readonly-properties" />4 Read-only Properties</h2>
223
 
        <p>
224
 
            A property can be explicitly marked read-only by setting the 
225
 
            &quot;readonly&quot; attribute on the <a href="../tasks/property.html">&lt;property&gt;</a>
226
 
            task to <b>true</b>.
227
 
        </p>
228
 
        <p>
229
 
            The value of a read-only property cannot be modified after it has been set.
230
 
        </p>
231
 
        <p>
232
 
            When attempting to override a read-only property using the <a href="../tasks/property.html">
233
 
                &lt;property&gt;</a> task, the new value will be ignored and a warning 
234
 
            message will be output in the build log. Attempting to override read-only 
235
 
            properties using any other means (eg. other tasks) will result in a build 
236
 
            failure.
237
 
        </p>
238
 
        <p><b>Note:</b> properties set on the command-line are always read-only.</p>
239
 
        <h2><a id="global-properties" />5 Global Properties</h2>
240
 
        <p>Properties that should be accessible to all build files on a system can be 
241
 
            defined in the <code>&lt;properties&gt;</code> node of the NAnt configuration 
242
 
            file (<code>NAnt.exe.config</code>).</p>
243
 
        <p>By changing the value of the property in the NAnt configuration file, the 
244
 
            updated value will be accessible to all build files on the system:</p>
245
 
        <pre class="code">
246
 
    &lt;?xml version="1.0"?&gt;
247
 
    &lt;configuration&gt;
248
 
        ...
249
 
        &lt;nant&gt;
250
 
            ...
251
 
            &lt;properties&gt;
252
 
                &lt;!-- properties defined here are accessible to all build files --&gt;
253
 
                &lt;property name="company.name" value="Foo Ltd." readonly="true" /&gt;
254
 
            &lt;/properties&gt;
255
 
        &lt;/nant&gt;
256
 
    &lt;/configuration&gt;
257
 
        </pre>
258
 
                <p>Individual build files can then use this property:</p>
259
 
                <pre class="code">
260
 
    &lt;?xml version="1.0"?&gt;
261
 
    &lt;project name="test"&gt;
262
 
        &lt;echo message="Company: ${company.name}" /&gt;
263
 
    &lt;/project&gt;
264
 
        </pre>
265
 
        <p>The output of this build is:</p>
266
 
        <pre>
267
 
    [echo] Company: Foo Ltd.
268
 
        </pre>
269
 
        <h2><a id="example" /> 6 Examples</h2>
270
 
        <p>The following build file demonstrates the use of property expansion:</p>
271
 
        <pre class="code">
272
 
    &lt;?xml version="1.0"?&gt;
273
 
    &lt;project name="Property Test" default="test" basedir="."&gt;
274
 
        &lt;property name="project.name" value="PropertyTest"/&gt;
275
 
        &lt;property name="project.version" value="1.0.0"/&gt;
276
 
        &lt;target name="test"&gt;
277
 
            &lt;echo message="Building ${project.name}-${project.version}"/&gt;
278
 
        &lt;/target&gt;
279
 
    &lt;/project&gt;
280
 
        </pre>
281
 
        <p>The output of this build is:</p>
282
 
        <pre>
283
 
    [echo] Building PropertyTest-1.0.0
284
 
        </pre>
285
 
        <p>The following build file demonstrates the use of properties in <a href="expressions.html">
286
 
                expressions</a>. It evaluates the length of the property <code>project.name</code>
287
 
            and displays it.</p>
288
 
        <pre class="code">
289
 
    &lt;?xml version="1.0"?&gt;
290
 
    &lt;project name="Expression Test" default="test" basedir="."&gt;
291
 
        &lt;property name="project.name" value="Expression Test"/&gt;
292
 
        &lt;target name="test"&gt;
293
 
            &lt;echo message="Project name consists of ${string::get-length(project.name)} characters."/&gt;
294
 
        &lt;/target&gt;
295
 
    &lt;/project&gt;
296
 
        </pre>
297
 
        <p>The output of this build is:</p>
298
 
        <pre>
299
 
   [echo] Project name consists of 15 characters.
300
 
        </pre>
301
 
        <h3>See Also</h3>
302
 
        <ul>
303
 
            <li>
304
 
                <a href="../tasks/property.html">&lt;property&gt;</a>
305
 
            </li>
306
 
            <li>
307
 
                <a href="../tasks/sysinfo.html">&lt;sysinfo&gt;</a>
308
 
            </li>
309
 
            <li>
310
 
                <a href="../tasks/tstamp.html">&lt;tstamp&gt;</a>
311
 
            </li>
312
 
        </ul>
313
 
    </body>
314
 
</html>