source: other-projects/trunk/realistic-books/packages/AntInstaller/web/manual/manual/OptionalTasks/starteam.html@ 19253

Last change on this file since 19253 was 19253, checked in by davidb, 15 years ago

Establishing a source code repository for Veronica's Realistic Book's software
File size: 38.4 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<head>
19<meta http-equiv="Content-Language" content="en-us">
20<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
21<title>StarTeam Tasks</title>
22</head>
23<body>
24<h1>StarTeam Support</h1>
25<ul>
26 <li><a href="#stcheckout">STCheckout</a></li>
27 <li><a href="#stcheckin">STCheckin</a></li>
28 <li><a href="#stlabel">STLabel</a></li>
29 <li><a href="#stlist">STList</a></li>
30 <li><a href="#starteam"><i>StarTeam (deprecated) </i></a></li>
31</ul>
32
33<p>
34The StarTeam revision control system was recently acquired by Borland.
35These tasks make use of functions from the StarTeam API to work with that system.
36As a result they are only available to licensed users of StarTeam. You must have
37<CODE>starteam-sdk.jar</CODE> in your classpath to run these tasks.
38For more information about the StarTeam API and how to license it, see
39the <a href="http://www.borland.com/starteam/">Borland</a> web site.</p>
40 <p>
41 <em>All the StarTeam task names are in lower case.</em>
42 </p>
43<h3>Important Note on Installation and Licensing:</h3>
44<p>
45<b>On Windows machines, the mere presence of <CODE>starteam-sdk.jar</CODE> on the classpath
46is not sufficient for getting these tasks to work properly.</b> These tasks also require a
47fully-installed and fully-licensed version of the StarGate Runtime. This is part
48of a StarTeam client installation or may be installed separately. The full client
49install is not required. In particular, the Windows path must include the directory where
50the StarGate Runtime <CODE>.dll</CODE> files are installed.
51</p><p>
52Earlier versions of Ant (prior to 1.5.2) did not have this restriction because they
53were not as dependent on the StarTeam runtime - which the newer versions use to access
54StarTeam file status information. The older versions lacked this important capability.
55</p>
56<hr></hr>
57
58<a name="common-params">
59<h2>Common Parameters for All Starteam Tasks</h2></a>
60<p>
61The following parameters, having to do with making the connection to a StarTeam project, are common to all the following tasks except the deprecated <i>StarTeam</i> task.
62</p>
63
64<table border="1" cellpadding="2" cellspacing="0">
65 <tr>
66 <td valign="top"><b>Attribute</b></td>
67 <td valign="top"><b>Description</b></td>
68 <td align="center" valign="top"><b>Required</b></td>
69 </tr>
70 <tr>
71 <td valign="top">username</td>
72 <td valign="top">The username of the account used to log in to the StarTeam server.</td>
73 <td align="center" valign="top">yes</td>
74 </tr>
75 <tr>
76 <td valign="top">password</td>
77 <td valign="top">The password of the account used to log in to the StarTeam server.</td>
78 <td align="center" valign="top">yes</td>
79 </tr>
80
81 <tr>
82 <td valign="top">URL</td>
83 <td valign="top">A string of the form <code>servername:portnum/project/view</code>
84which enables user to set all of these elements in one string. </td>
85 <td align="center" valign="center"> Either this ...</td>
86 </tr>
87 <tr>
88 <td valign="top">servername</td>
89 <td valign="top">The name of the StarTeam server.</td>
90 <td align="center" valign="center" rowspan = "4">... or <b>all four</b> of these must be defined.</td>
91 </tr>
92 <tr>
93 <td valign="top">serverport</td>
94 <td valign="top">The port number of the StarTeam server.</td>
95 </tr>
96 <tr>
97 <td valign="top">projectname</td>
98 <td valign="top">The name of the StarTeam project on which to operate.</td>
99 </tr>
100 <tr>
101 <td valign="top">viewname</td>
102 <td valign="top">The name of the view in the StarTeam project on which to operate.</td>
103 </tr>
104
105
106</table>
107
108<hr></hr>
109
110<a name="stcheckout">
111<h2>STCheckout</h2></a>
112
113<h3>Description</h3>
114
115Checks out files from a StarTeam project.
116
117<p>
118The <i>includes</i> and <i>excludes</i> attributes function differently from
119other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
120</p>
121
122<h3>Parameters</h3>
123See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
124<table border="1" cellpadding="2" cellspacing="0">
125 <tr>
126 <td valign="top"><b>Attribute</b></td>
127 <td valign="top"><b>Description</b></td>
128 <td align="center" valign="top"><b>Required</b></td>
129 </tr>
130
131 <tr>
132 <td valign="top">rootstarteamfolder</td>
133 <td valign="top">The root of the subtree in the StarTeam repository from which to
134 check out files. Defaults to the root folder of the view ('/').
135 <b><i>If supplied, this should always be an "absolute" path, that is, it should begin with a '/'.
136 Relative paths have little meaning in this context and confuse StarTeam.</i></b>
137 </td>
138 <td align="center" valign="top">no</td>
139 </tr>
140 <tr>
141 <td valign="top">rootlocalfolder</td>
142 <td valign="top">The local folder which will be the root of the tree to which files are checked out. If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used.
143 </td>
144 <td align="center" valign="top">no</td>
145 </tr>
146
147 <tr>
148 <td valign="top">createworkingdirs</td>
149 <td valign="top">creates local folders even when the corresponding StarTeam folder is empty. Defaults to "true".</td>
150 <td align="center" valign="top">no</td>
151 </tr>
152 <tr>
153 <td valign="top">deleteuncontrolled</td>
154 <td valign="top">if true, any files NOT in StarTeam will be deleted. Defaults to "true".</td>
155 <td align="center" valign="top">no</td>
156 </tr>
157 <tr>
158 <td valign="top">includes</td>
159 <td valign="top">Only check out files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
160 <td align="center" valign="top">no</td>
161 </tr>
162 <tr>
163 <td valign="top">excludes</td>
164 <td valign="top">Do not check out files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
165 <td align="center" valign="top">no</td>
166 </tr>
167 <tr>
168 <td valign="top">label</td>
169 <td valign="top">Check out files as of this label. The label must exist in starteam or an exception will be thrown.</td>
170 <td align="center" valign="center" rowspan="2">Either or neither, but not both, may be specified. Neither <code>locked</code> or <code>unlocked</code> may be true if either <code>label</code> or <code>asofdate</code> is specified.</td>
171 </tr>
172 <tr>
173 <td valign="top">asofdate</td>
174 <td valign="top">Check out files as of this date. The date must
175 be formatted in ISO8601 datetime
176 (<code>yyyy-MM-dd'T'HH:mm:ss</code>), ISO8601
177 date(<code>yyyy-MM-dd</code>) or a user-defined SimpleDateFormat
178 defined in the <code>asofDateFormat</code> attribute. If the date
179 is not parsable by the default or selected format, an exception
180 will be thrown. <em>Since Ant 1.6.</em></td>
181 </tr>
182 <tr>
183 <td valign="top">asofdateformat</td>
184 <td valign="top">java.util.SimpleDateFormat compatible string used
185 to parse the <code>asofdate</code> attribute. <em>Since Ant
186 1.6.</em></td>
187 <td align="center" valign="top">no</td>
188 </tr>
189 <tr>
190 <td valign="top">recursive</td>
191 <td valign="top">Indicates if subfolders should be searched for files to check out. Defaults to "true".</td>
192 <td align="center" valign="top">no</td>
193 </tr>
194 <tr>
195 <td valign="top">forced</td>
196 <td valign="top">If true, checkouts will occur regardless of the status
197that StarTeam is maintaining for the file. If false, status will be used to determine which files to check out. Defaults to "false".</td>
198 <td align="center" valign="top">no</td>
199 </tr>
200 <tr>
201 <td valign="top">locked</td>
202 <td valign="top">If true, file will be locked against changes by other
203users. If false (default) has no effect.
204 <td align="center" valign="center" rowspan="2">Either or neither, but not both, may be true. Neither may be true if a <code>label</code> or an <code>asofdate</code> is specified.</td>
205 </tr>
206 <tr>
207 <td valign="top">unlocked</td>
208 <td valign="top">If true, file will be unlocked so that other users may
209change it. This is a way to reverse changes that have not yet been checked in.
210If false (default) has no effect.</td>
211 </tr>
212 <tr>
213 <td valign="top">userepositorytimestamp</td>
214 <td valign="top">true means checked out files will get the repository timestamp.
215false(default) means the checked out files will be timestamped at the time
216of checkout.</td> <td align="center" valign="top">no</td>
217
218 </tr>
219 <tr>
220 <td valign="top">preloadfileinformation</td>
221 <td valign="top">The StarTeam server has the ability to preload file metadata for an
222 entire tree prior to beginning action on that tree. Doing so can in some instances
223 lead to substantially faster actions, particularly over large trees. Setting this
224 to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>
225 <td align="center" valign="top">no</td>
226 </tr>
227
228 <tr>
229 <td valign="top">convertEOL</td>
230 <td valign="top">If true, (default) all ascii files will have their end-of-line
231 characters adjusted to that of the local machine on checkout. This is normally
232 what you'd want but if for some reason you don't want that to happen, set it to false
233 and the files will be checked out with whatever end-of-line characters are used on
234 the server. </td>
235 <td align="center" valign="top">no</td>
236 </tr>
237
238</table>
239
240<h3>Examples</h3>
241
242<pre>
243 &lt;stcheckout servername="STARTEAM"
244 serverport="49201"
245 projectname="AProject"
246 viewname="AView"
247 username="auser"
248 password="secret"
249 rootlocalfolder="C:\dev\buildtest\co"
250 forced="true"
251 /&gt;
252</pre>
253
254The minimum necessary to check out files out from a StarTeam server. This will
255check out all files in the <i>AView</i> view of the <i>AProject</i> project to
256<code>C:\dev\buildtest\co</code>. Empty folders in StarTeam will have local folders
257created for them and any non-StarTeam files found in the tree will be deleted.
258
259<pre>
260 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
261 username="auser"
262 password="secret"
263 rootlocalfolder="C:\dev\buildtest\co"
264 forced="true"
265 /&gt;
266</pre>
267And this is a simpler way of accomplishing the same thing as the previous example, using the URL attribute.
268<br></br>
269<pre>
270 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
271 username="auser"
272 password="secret"
273 rootlocalfolder="C:\dev\buildtest\co"
274 rootstarteamfolder="\Dev"
275 excludes="*.bak *.old"
276 label="v2.6.001"
277 forced="true"
278 /&gt;
279</pre>
280
281This will check out all files from the <i>Dev</i> folder and below that do not
282end in <i>.bak</i> or <i>.old</i> with the label <i>v2.6.001</i>.
283
284<pre>
285 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
286 username="auser"
287 password="secret"
288 rootlocalfolder="C:\dev\buildtest\co"
289 includes="*.htm,*.html"
290 excludes="index.*"
291 forced="true"
292 /&gt;
293</pre>
294
295
296This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes. Because
297<i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
298not be checked out by this command.
299
300<pre>
301 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
302 username="auser"
303 password="secret"
304 rootlocalfolder="C:\dev\buildtest\co"
305 includes="*.htm,*.html"
306 excludes="index.*"
307 forced="true"
308 recursive="false"
309 /&gt;
310</pre>
311This example is like the previous one, but will only check out files in
312C:\dev\buildtest\co, because of the turning off of the recursive attribute.
313
314<pre>
315 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
316 username="auser"
317 password="secret"
318 rootstarteamfolder="src/java"
319 rootlocalfolder="C:\dev\buildtest\co"
320 forced="true"
321 /&gt;
322</pre>
323<br></br>
324<pre>
325 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
326 username="auser"
327 password="secret"
328 rootstarteamfolder="src/java"
329 /&gt;
330</pre>
331<br></br>
332<pre>
333 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
334 username="auser"
335 password="secret"
336 rootstarteamfolder="src/java"
337 rootlocalfolder="C:\dev\buildtest\co\src\java"
338 forced="true"
339 /&gt;
340</pre>
341
342In the preceding three examples, assuming that the AProject project has a default folder of
343"C:\work\AProject", the first example will check out the tree of files rooted in the src/java folder of the AView view of the AProject in the StarTeam repository to a local tree rooted at C:\dev\buildtest\co,
344the second to a tree rooted at C:\work\AProject\src\java (since no <i>rootlocalfolder</i> is specified) and the third to a tree rooted at C:\dev\buildtest\co\src\java. Note also, that since the second example does not set "forced" true, only those files which the repository considers out-of-date will be checked out.
345<hr></hr>
346
347<a name="stcheckin">
348<h2>STCheckin</h2></a>
349
350<h3>Description</h3>
351
352Checks files into a StarTeam project. Optionally adds files and in the local tree that are not managed by the repository to its control.
353
354<p>
355The <i>includes</i> and <i>excludes</i> attributes function differently from
356other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
357</p>
358
359<h3>Parameters</h3>
360See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
361<table border="1" cellpadding="2" cellspacing="0">
362 <tr>
363 <td valign="top"><b>Attribute</b></td>
364 <td valign="top"><b>Description</b></td>
365 <td align="center" valign="top"><b>Required</b></td>
366 </tr>
367 <tr>
368 <td valign="top">rootstarteamfolder</td>
369 <td valign="top">The root of the subtree in the StarTeam repository into which to
370 files will be checked. Defaults to the root folder of the view ('/').
371 <b><i>If supplied, this should always be an "absolute" path, that is, it should begin with a '/'.
372 Relative paths have little meaning in this context and confuse StarTeam.</i></b></td>
373 <td align="center" valign="top">no</td>
374 </tr>
375 <tr>
376 <td valign="top">rootlocalfolder</td>
377 <td valign="top">The local folder which will be the root of the tree to which files are checked out. If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used. </td>
378 <td align="center" valign="top">no</td>
379 </tr>
380
381
382 <tr>
383 <td valign="top">comment</td>
384 <td valign="top">Checkin comment to be saved with the file.</td>
385 <td align="center" valign="top">no</td>
386 </tr>
387
388 <tr>
389 <td valign="top">adduncontrolled</td>
390 <td valign="top">if true, any files or folders NOT in StarTeam will be
391added to the repository. Defaults to "false".</td>
392 <td align="center" valign="top">no</td>
393 </tr>
394 <tr>
395 <td valign="top">includes</td>
396 <td valign="top">Only check in files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
397 <td align="center" valign="top">no</td>
398 </tr>
399 <tr>
400 <td valign="top">excludes</td>
401 <td valign="top">Do not check in files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
402 <td align="center" valign="top">no</td>
403 </tr>
404 <tr>
405 <td valign="top">recursive</td>
406 <td valign="top">Indicates if subfolders should be searched for files to check in. Defaults to "false".</td>
407 <td align="center" valign="top">no</td>
408 </tr>
409 <tr>
410 <td valign="top">forced</td>
411 <td valign="top">If true, checkins will occur regardless of the status
412that StarTeam is maintaining for the file. If false, checkins will use this status to decide which files to update. Defaults to "false".</td>
413 <td align="center" valign="top">no</td>
414 </tr>
415 <td valign="top">unlocked</td>
416 <td valign="top">If true, file will be unlocked so that other users may
417change it. If false (default) lock status will not change.
418 <td align="center" valign="top">no</td>
419 </tr>
420 <tr>
421 <td valign="top">preloadfileinformation</td>
422 <td valign="top">The StarTeam server has the ability to preload file metadata for an
423 entire tree prior to beginning action on that tree. Doing so can in some instances
424 lead to substantially faster actions, particularly over large trees. Setting this
425 to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>
426 <td align="center" valign="top">no</td>
427 </tr>
428 </table>
429
430<h3>Examples</h3>
431
432<pre>
433 &lt;stcheckin servername="STARTEAM"
434 serverport="49201"
435 projectname="AProject"
436 viewname="AView"
437 username="auser"
438 password="secret"
439 rootlocalfolder="C:\dev\buildtest\co"
440 forced="true"
441 /&gt;
442</pre>
443
444The minimum necessary to check files into a StarTeam server. This will
445check all files on the local tree rooted at <code>C:\dev\buildtest\co</code>
446into the <i>AView</i> view of the <i>AProject</i> project in the repository.
447For files and folders in the local tree but not in starteam, nothing will be done. Since the <i>forced</i> attribute is set, the files which are checked in will be checked in without regard to what the StarTeam repository considers their status to be. This is a reasonable choice of attributes since StarTeam's status for a file is calculated based on the local file in the StarTeam default directory, not on the directory we are actually working with.
448
449<pre>
450 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
451 username="auser"
452 password="secret"
453 rootlocalfolder="C:\dev\buildtest\co"
454 forced="true"
455 /&gt;
456</pre>
457And this is a simpler way of giving the same commands as the command above using the URL shortcut.
458<br></br>
459<pre>
460 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
461 username="auser"
462 password="secret"
463 rootlocalfolder="C:\dev\buildtest\co"
464 rootstarteamfolder="\Dev"
465 excludes="*.bak *.old"
466 forced="true"
467 /&gt;
468</pre>
469
470This will check all files in to the <i>Dev</i> folder and below that do not
471end in <i>.bak</i> or <i>.old</i> from the tree rooted at"C:\dev\buildtest\co" .
472
473<pre>
474 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
475 username="auser"
476 password="secret"
477 rootlocalfolder="C:\dev\buildtest\co"
478 includes="*.htm,*.html"
479 excludes="index.*"
480 forced="true"
481 /&gt;
482</pre>
483
484
485This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes. Because
486<i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
487not be checked in by this command.
488
489<pre>
490 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
491 username="auser"
492 password="secret"
493 rootlocalfolder="C:\dev\buildtest\co"
494 rootstarteamfolder="src/java"
495 includes="*.htm,*.html"
496 excludes="index.*"
497 forced="true"
498 recursive="false"
499 /&gt;
500</pre>
501This example is like the previous one, but will only check in files from
502C:\dev\buildtest\co, because of the turning off of the recursive attribute.
503
504<pre>
505 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
506 username="auser"
507 password="secret"
508 rootlocalfolder="C:\dev\buildtest\co"
509 rootstarteamfolder="src/java"
510 includes="version.txt"
511 forced="true"
512 recursive="false"
513 /&gt;
514</pre>
515This example is like the previous one, but will only check only in one file, C:\dev\buildtest\co\version.txt to the StarTeam folder src/java.
516
517<pre>
518 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
519 username="auser"
520 password="secret"
521 rootlocalfolder="C:\dev\buildtest\co"
522 rootstarteamfolder="src/java"
523 includes="version.java"
524 forced="true"
525 recursive="false"
526 addUncontrolled="true"
527 comment="Fix Bug #667"
528 /&gt;
529</pre>
530This example is like the previous one, but will only check only in one file, C:\dev\buildtest\co\version.java to the StarTeam folder src/java. Because the <i>addUncontrolled</i> attribute has been set, if StarTeam does not already control this file in this location, it will be added to the repository. Also, it will write a comment to the repository for this version of the file.
531
532<pre>
533 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
534 username="auser"
535 password="secret"
536 rootstarteamfolder="src/java"
537 rootlocalfolder="C:\dev\buildtest\co"
538 forced="true"
539 /&gt;
540</pre>
541<br></br>
542<pre>
543 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
544 username="auser"
545 password="secret"
546 rootstarteamfolder="src/java"
547 /&gt;
548</pre>
549<br></br>
550<pre>
551 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
552 username="auser"
553 password="secret"
554 rootstarteamfolder="src/java"
555 rootlocalfolder="C:\dev\buildtest\co\src\java"
556 forced="true"
557 /&gt;
558</pre>
559
560In the preceding three examples, assuming that the AProject project has a default folder of C:\work\buildtest\co\AProject,
561the first example will check in files from a tree rooted at C:\dev\buildtest\co,
562the second from a tree rooted at C:\work\buildtest\co\AProject\src\java,
563and the third from a tree rooted at C:\dev\buildtest\co\src\java all to a tree rooted at src/java
564
565<hr></hr>
566
567<a name="stlabel">
568<h2>STLabel</h2></a>
569
570<h3>Description</h3>
571
572Creates a view label in StarTeam at the specified view. The label will be classified by StarTeam as a "build label". This task will fail if there already exists in <i>viewname</i> a label with the same name as the <i>label</i> parameter.
573
574<h3>Parameters</h3>
575See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
576<table border="1" cellpadding="2" cellspacing="0">
577 <tr>
578 <td valign="top"><b>Attribute</b></td>
579 <td valign="top"><b>Description</b></td>
580 <td align="center" valign="top"><b>Required</b></td>
581 </tr>
582
583 <tr>
584 <td valign="top">label</td>
585 <td valign="top">The name to be given to the label</td>
586 <td align="center" valign="top">yes</td>
587 </tr>
588 <tr>
589 <td valign="top">description</td>
590 <td valign="top">A description of the label to be stored in the StarTeam project.</td>
591 <td align="center" valign="top">yes</td>
592 </tr>
593 <tr>
594 <td valign="top">revisionlabel</td>
595 <td valign="top">Yes means that the label attribute is to be saved as a &quot;revision label&quot;. No (default) means that it will be saved as a &quot;view label&quot;</td>
596 <td align="center" valign="top">no</td>
597 </tr>
598 <tr>
599 <td valign="top">buildlabel</td>
600 <td valign="top">Yes means that the label attribute is to be saved as a &quot;build label&quot;.
601 This means that Change Requests which have an &quot;AddressedIn&quot; field value of &quot;next build&quot;
602 will have this label assigned to that field when the label is created.
603 No (default) means that no CRs will have this label assigned to them. This will have no effect if <b>revisionlabel</b> is also true. </td>
604 <td align="center" valign="top">no</td>
605 </tr>
606
607 <tr>
608 <td valign="top">lastbuild</td>
609 <td valign="top">The timestamp of the build that will be stored with the label. Must be formatted <code>yyyyMMddHHmmss</code></td>
610 <td align="center" valign="top">no</td>
611 </tr>
612</table>
613
614<h3>Examples</h3>
615
616This example shows the use of this tag. It will create a View label that is a build label named <i>Version 6.2</i> with
617<i>&quot;Thorough description&quot;</i> as its description.
618<pre>
619 &lt;tstamp&gt;
620 &lt;format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/&gt;
621 &lt;/tstamp&gt;
622 &lt;stlabel URL="STARTEAM:49201/Aproject/AView"
623 username="auser"
624 password="secret"
625 label="Version 6.2"
626 lastbuild="${nowstamp}"
627 description="Thorough description"
628 /&gt;
629</pre>
630This example creates a non-build View label named <i>Version 6.3</i> with
631<i>&quot;Thorough description&quot;</i> as its description.
632<pre>
633 &lt;tstamp&gt;
634 &lt;format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/&gt;
635 &lt;/tstamp&gt;
636 &lt;stlabel URL="STARTEAM:49201/Aproject/AView"
637 username="auser"
638 password="secret"
639 label="Version 6.3"
640 lastbuild="${nowstamp}"
641 description="Thorough description"
642 buildlabel="false"
643 /&gt;
644</pre>
645This example will create a Revision label that is a build label named <i>Version 6.2.00.001</i> with
646<i>&quot;revision label&quot;</i> as its description.
647<pre>
648 &lt;tstamp&gt;
649 &lt;format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/&gt;
650 &lt;/tstamp&gt;
651 &lt;stlabel URL="STARTEAM:49201/Aproject/AView"
652 username="auser"
653 password="secret"
654 label="Version 6.2.00.001"
655 description="revision label"
656 revisionlabel="true"
657 /&gt;
658</pre>
659
660<hr></hr>
661<a name="stlist">
662<h2>STList</h2></a>
663
664<h3>Description</h3>
665
666Produces a listing of the contents of the StarTeam repository at the specified view and StarTeamFolder. The listing will contain the name of the user, if any, who has the file locked, the size of the file, its lastModifiedDate in the repository, the name of the file, and the status of the local file in the default local directory relative to the repository.
667
668<h3>Parameters</h3>
669See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
670<table border="1" cellpadding="2" cellspacing="0">
671 <tr>
672 <td valign="top"><b>Attribute</b></td>
673 <td valign="top"><b>Description</b></td>
674 <td align="center" valign="top"><b>Required</b></td>
675 </tr>
676
677 <tr>
678 <td valign="top">rootstarteamfolder</td>
679 <td valign="top">The root of the subtree in the StarTeam repository to be listed. Defaults to the root folder of the view ('/'). <b><i>If supplied, this should always be an "absolute" path, that is, it should begin with a '/'.
680 Relative paths have little meaning in this context and confuse StarTeam.</i></b></td>
681 <td align="center" valign="top">no</td>
682 </tr>
683 <tr>
684 <td valign="top">rootlocalfolder</td>
685 <td valign="top">The local folder which will be the root of the tree to which files are compared. If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used and a status field will appear in the listing. Otherwise, the status field will not appear.
686 </td>
687 <td align="center" valign="top">no</td>
688 </tr>
689 <tr>
690 <td valign="top">includes</td>
691 <td valign="top">Only list files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
692 <td align="center" valign="top">no</td>
693 </tr>
694 <tr>
695 <td valign="top">excludes</td>
696 <td valign="top">Do not list files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
697 <td align="center" valign="top">no</td>
698 </tr>
699 <tr>
700 <td valign="top">label</td>
701 <td valign="top">List files, dates, and statuses as of this label. The label must exist in starteam or an exception will be thrown. If not specified, the most recent version of each file will be listed.</td>
702 <td align="center" valign="top">no</td>
703 </tr>
704 <tr>
705 <td valign="top">asofdate</td>
706 <td valign="top">List files, dates, and statuses as of this date.
707 The date must be formatted in ISO8601 datetime
708 (<code>yyyy-MM-dd'T'HH:mm:ss</code>), ISO8601
709 date(<code>yyyy-MM-dd</code>) or a user-defined SimpleDateFormat
710 defined in the <code>asofDateFormat</code> attribute. If the date
711 is not parsable by the default or selected format, an exception
712 will be thrown. <em>Since Ant 1.6.</em></td>
713 <td align="center" valign="top">no</td>
714 </tr>
715 <tr>
716 <td valign="top">asofdateformat</td>
717 <td valign="top">java.util.SimpleDateFormat compatible string used
718 to parse the <code>asofdate</code> attribute. <em>Since Ant
719 1.6.</em></td>
720 <td align="center" valign="top">no</td>
721 </tr>
722
723 <tr>
724 <td valign="top">recursive</td>
725 <td valign="top">Indicates if subfolders should be searched for files to list. Defaults to "true".</td>
726 <td align="center" valign="top">no</td>
727 </tr>
728 <tr>
729 <td valign="top">listuncontrolled</td>
730 <td valign="top">if true, any files or folders NOT in StarTeam will be included in the listing.
731 If false, they won't. Defaults to "true".</td>
732 <td align="center" valign="top">no</td>
733 </tr>
734
735 <tr>
736 <td valign="top">preloadfileinformation</td>
737 <td valign="top">The StarTeam server has the ability to preload file metadata for an
738 entire tree prior to beginning action on that tree. Doing so can in some instances
739 lead to substantially faster actions, particularly over large trees. Setting this
740 to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>
741 <td align="center" valign="top">no</td>
742 </tr>
743
744</table>
745<h3>Examples</h3>
746
747<pre>
748
749 &lt;stlist url="WASHINGTON:49201/build"
750 username="auser"
751 password="secret"
752 /&gt;
753</pre>
754
755The above command might produce the following listing:
756
757<pre>
758 [stlist] Folder: Build (Default folder: C:/work/build)
759 [stlist] Folder: dev (Default folder: C:/work/build/dev)
760 [stlist] Out of date Sue Developer 1/1/02 7:25:47 PM CST 4368 build.xml
761 [stlist] Missing George Hacker 1/1/02 7:25:49 PM CST 36 Test01.properties
762 [stlist] Current 1/1/02 7:25:49 PM CST 4368 build2.xml
763 [stlist] Folder: test (Default folder C:/work/build/dev/test)
764 [stlist] Missing 1/1/02 7:25:50 PM CST 4368 build2.xml
765</pre>
766
767while adding a <i>rootlocalfolder</i> and an <i>excludes</i> param ...
768
769<pre>
770
771 &lt;stlist url="WASHINGTON:49201/build"
772 username="auser"
773 password="secret"
774 rootlocalfolder="srcdir2"
775 excludes="*.properties"
776 /&gt;
777</pre>
778
779might produce this listing. The status is missing because we are not going against the default folder.
780
781<pre>
782 [stlist] overriding local folder to srcdir2
783 [stlist] Folder: Build (Local folder: srcdir2)
784 [stlist] Folder: dev (Local folder: srcdir2/dev)
785 [stlist] Sue Developer 1/1/02 7:25:47 PM CST 4368 build.xml
786 [stlist] 1/1/02 7:25:49 PM CST 4368 build2.xml
787 [stlist] Folder: test (Local folder: srcdir2/dev/test)
788 [stlist] 1/1/02 7:25:50 PM CST 4368 build2.xml
789
790
791</pre>
792
793<hr></hr>
794
795<a name="starteam">
796<h2>Starteam</h2></a>
797<h3><i>Deprecated</i></h3>
798<p><i>This task has been deprecated. Use the <a href="#stcheckout">STCheckout</a> task instead.</i></p>
799<h3>Description</h3>
800
801Checks out files from a StarTeam project.
802
803<p>
804The <i>includes</i> and <i>excludes</i> attributes function differently from
805other tasks in Ant. Multiple patterns must be separated by spaces, not
806commas. See the examples for more information.</p>
807
808<h3>Parameters</h3>
809<table border="1" cellpadding="2" cellspacing="0">
810 <tr>
811 <td valign="top"><b>Attribute</b></td>
812 <td valign="top"><b>Description</b></td>
813 <td align="center" valign="top"><b>Required</b></td>
814 </tr>
815 <tr>
816 <td valign="top">username</td>
817 <td valign="top">The username of the account used to log in to the StarTeam server.</td>
818 <td align="center" valign="top">yes</td>
819 </tr>
820 <tr>
821 <td valign="top">password</td>
822 <td valign="top">The password of the account used to log in to the StarTeam server.</td>
823 <td align="center" valign="top">yes</td>
824 </tr>
825 <tr>
826 <td valign="top">servername</td>
827 <td valign="top">The name of the StarTeam server.</td>
828 <td align="center" valign="top">yes</td>
829 </tr>
830 <tr>
831 <td valign="top">serverport</td>
832 <td valign="top">The port number of the StarTeam server.</td>
833 <td align="center" valign="top">yes</td>
834 </tr>
835 <tr>
836 <td valign="top">projectname</td>
837 <td valign="top">The name of the StarTeam project.</td>
838 <td align="center" valign="top">yes</td>
839 </tr>
840 <tr>
841 <td valign="top">viewname</td>
842 <td valign="top">The name of the view in the StarTeam project.</td>
843 <td align="center" valign="top">yes</td>
844 </tr>
845
846 <tr>
847 <td valign="top">targetfolder</td>
848 <td valign="top">The folder to which files are checked out. What this precisely means is determined by the <i>targetFolderAbsolute</i> param.</td>
849 <td align="center" valign="top">yes</td>
850 </tr>
851 <tr>
852 <td valign="top">targetFolderAbsolute</td>
853 <td valign="top">Determines how <i>targetfolder</i> is interpreted, that is, whether the StarTeam "default folder" for the project is factored in (false) or whether <i>targetFolder</i> is a complete mapping to <i>foldername</i> (true).
854 If "true", the target tree will be rooted at <i>targetfolder+"default folder"</i>. If false, the target tree will be rooted at <i>targetfolder</i>. Defaults to "false". </td>
855 <td align="center" valign="top">no</td>
856 </tr>
857 <tr>
858 <td valign="top">foldername</td>
859 <td valign="top">The subfolder in the project from which to check out files.</td>
860 <td align="center" valign="top">no</td>
861 </tr>
862 <tr>
863 <td valign="top">force</td>
864 <td valign="top">Overwrite existing folders if this is set to "true". Defaults to "false".</td>
865 <td align="center" valign="top">no</td>
866 </tr>
867 <tr>
868 <td valign="top">recursion</td>
869 <td valign="top">Indicates if subfolders should be searched for files to check out. Defaults to "true".</td>
870 <td align="center" valign="top">no</td>
871 </tr>
872 <tr>
873 <td valign="top">verbose</td>
874 <td valign="top">Provides progress information. Defaults to "false".</td>
875 <td align="center" valign="top">no</td>
876 </tr>
877 <tr>
878 <td valign="top">includes</td>
879 <td valign="top">Only check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
880 <td align="center" valign="top">no</td>
881 </tr>
882 <tr>
883 <td valign="top">excludes</td>
884 <td valign="top">Do not check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
885 <td align="center" valign="top">no</td>
886 </tr>
887</table>
888
889<h3>Examples</h3>
890
891<pre>
892 &lt;starteam servername="STARTEAM"
893 serverport="49201"
894 projectname="AProject"
895 viewname="AView"
896 username="auser"
897 password="secret"
898 targetfolder="C:\dev\buildtest\co"
899 /&gt;
900</pre>
901
902The minimum necessary to check out files out from a StarTeam server. This will
903check out all files in the <i>AView</i> view of the <i>AProject</i> project to
904<code>C:\dev\buildtest\co</code>.
905
906<pre>
907 &lt;starteam servername="STARTEAM"
908 serverport="49201"
909 projectname="AProject"
910 viewname="AView"
911 username="auser"
912 password="secret"
913 targetfolder="C:\dev\buildtest\co"
914 foldername="\Dev"
915 excludes="*.bak *.old"
916 force="true"
917 /&gt;
918</pre>
919
920This will checkout all files from the <i>Dev</i> folder and below that do not
921end in <i>.bak</i> or <i>.old</i>. The force flag will cause any existing files to be
922overwritten by the version in StarTeam.
923
924<pre>
925 &lt;starteam servername="STARTEAM"
926 serverport="49201"
927 projectname="AProject"
928 viewname="AView"
929 username="auser"
930 password="secret"
931 targetfolder="C:\dev\buildtest\co"
932 includes="*.htm *.html"
933 excludes="index.*"
934 /&gt;
935</pre>
936
937
938
939This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes. Because
940<i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
941not be checked out by this command.
942
943
944<pre>
945 &lt;starteam servername="STARTEAM"
946 serverport="49201"
947 projectname="AProject"
948 foldername="src/java"
949 viewname="AView"
950 username="auser"
951 password="secret"
952 targetfolder="C:\dev\buildtest\co"
953 targetfolderabsolute="true"
954 /&gt;
955</pre>
956<br></br>
957<pre>
958 &lt;starteam servername="STARTEAM"
959 serverport="49201"
960 projectname="AProject"
961 foldername="src/java"
962 viewname="AView"
963 username="auser"
964 password="secret"
965 targetfolder="C:\dev\buildtest\co"
966 targetfolderabsolute ="false"
967 /&gt;
968</pre>
969<br></br>
970<pre>
971 &lt;starteam servername="STARTEAM"
972 serverport="49201"
973 projectname="AProject"
974 foldername="src/java"
975 viewname="AView"
976 username="auser"
977 password="secret"
978 targetfolder="C:\dev\buildtest\co\src\java"
979 targetfolderabsolute="true"
980 /&gt;
981</pre>
982
983In the preceding three examples, assuming that the AProject project has a default folder of
984"AProject", the first example will check the files located in starteam under src/java out to a tree rooted at C:\dev\buildtest\co,
985the second to a tree rooted at C:\dev\buildtest\co\AProject\src\java and the third to a tree rooted at C:\dev\buildtest\co\src\java.
986
987
988
989</body>
990</html>
Note: See TracBrowser for help on using the repository browser.