2001-03-16 09:01:38 +00:00
< html >
< head >
< meta http-equiv = "Content-Language" content = "en-us" >
2001-10-30 10:05:39 +00:00
< title > Apache Ant User Manual< / title >
2001-03-16 09:01:38 +00:00
< / head >
< body >
2001-12-18 22:18:17 +00:00
< h1 > StarTeam Support< / h1 >
< ul >
<!-- <li><a href="#stcheckin">STCheckin</a></li> -->
< li > < a href = "#stcheckout" > STCheckout< / a > < / li >
< li > < a href = "#stlabel" > STLabel< / a > < / li >
< li > < a href = "#starteam" > < i > StarTeam (deprecated) < / i > < / a > < / li >
< / ul >
2001-03-16 09:01:38 +00:00
2001-12-18 22:18:17 +00:00
< p >
These tasks make use of functions from the StarTeam API. As a result
they are only available to licensed users of StarTeam. You must have
< CODE > starteam-sdk.jar< / CODE > in your classpath to run these tasks.
For more information about the StarTeam API and how to license it, see
the < a href = "http://www.starbase.com" > StarBase< / a > web site.< / p >
< hr > < / hr >
< a name = "stcheckout" >
< h2 > STCheckout< / h2 > < / a >
2001-03-16 09:01:38 +00:00
< h3 > Description< / h3 >
Checks out files from a StarTeam project.
< p >
The < i > includes< / i > and < i > excludes< / i > attributes function differently from
2001-12-18 22:18:17 +00:00
other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
< / p >
2001-03-16 09:01:38 +00:00
< h3 > Parameters< / h3 >
< table border = "1" cellpadding = "2" cellspacing = "0" >
< tr >
2001-12-18 22:18:17 +00:00
< td valign = "top" > username< / td >
< td valign = "top" > The username of the account used to log in to the StarTeam server.< / td >
< td align = "center" valign = "top" > yes< / td >
< / tr >
< tr >
< td valign = "top" > password< / td >
< td valign = "top" > The password of the account used to log in to the StarTeam server.< / td >
< td align = "center" valign = "top" > yes< / td >
2001-03-16 09:01:38 +00:00
< / tr >
2001-12-18 22:18:17 +00:00
2001-03-16 09:01:38 +00:00
< tr >
2001-12-18 22:18:17 +00:00
< td valign = "top" > URL< / td >
2001-12-31 20:15:57 +00:00
< td valign = "top" > A string of the form < code > servername:portnum/project/view< / code >
2001-12-18 22:18:17 +00:00
which enables user to set all of these elements in one string. < / td >
< td align = "center" valign = "top" > yes*< / td >
< / tr > < tr >
2001-03-16 09:01:38 +00:00
< td valign = "top" > servername< / td >
< td valign = "top" > The name of the StarTeam server.< / td >
2001-12-18 22:18:17 +00:00
< td align = "center" valign = "top" > yes*< / td >
2001-03-16 09:01:38 +00:00
< / tr >
< tr >
< td valign = "top" > serverport< / td >
< td valign = "top" > The port number of the StarTeam server.< / td >
2001-12-18 22:18:17 +00:00
< td align = "center" valign = "top" > yes*< / td >
2001-03-16 09:01:38 +00:00
< / tr >
< tr >
< td valign = "top" > projectname< / td >
< td valign = "top" > The name of the StarTeam project.< / td >
2001-12-18 22:18:17 +00:00
< td align = "center" valign = "top" > yes*< / td >
< / tr >
< tr >
< td valign = "top" > viewname< / td >
< td valign = "top" > The name of the view in the StarTeam project.< / td >
< td align = "center" valign = "top" > yes*< / td >
< / tr >
< tr >
< td valign = "top" > rootstarteamfolder< / td >
< td valign = "top" > The root of the subtree in the StarTeam repository from which to
check out files. Defaults to the root folder of the view ('/'). < / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > rootlocalfolder< / td >
2001-12-31 20:15:57 +00:00
< 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.
Setting this may be thought of as setting a different mode of operation, since when set, it makes no sense to check StarTeam's status flags for each file, and they are not checked.
When not set, we use the default folder and so we do check the status flags.< / td >
2001-12-18 22:18:17 +00:00
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > createworkingdirs< / td >
< td valign = "top" > creates local folders even when the corresponding StarTeam folder is empty. Defaults to "true".< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > deleteuncontrolled< / td >
< td valign = "top" > if true, any files NOT in StarTeam will be deleted. Defaults to "true".< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > includes< / td >
< 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 >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > excludes< / td >
< 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 >
< td align = "center" valign = "top" > no< / td >
< / tr >
2001-12-31 20:15:57 +00:00
< tr >
< td valign = "top" > label< / td >
< td valign = "top" > Check out files 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 checked out.< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > recursive< / td >
< td valign = "top" > Indicates if subfolders should be searched for files to check out. Defaults to "true".< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > forced< / td >
< td valign = "top" > If true, checkouts will occur regardless of the status
that StarTeam is maintaining for the file. If rootlocalfolder is set then
this should be set "true" as otherwise the checkout will be based on statuses
which do not relate to the target folder. Defaults to "false".< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
2001-12-18 22:18:17 +00:00
< / table >
* Either the URL attribute or < b > all four< / b > of the servername, serverport, projectname and viewname attributes must be defined. < br / >
< h3 > Examples< / h3 >
< pre >
< stcheckout servername="STARTEAM"
serverport="49201"
projectname="AProject"
viewname="AView"
username="auser"
password="secret"
rootlocalfolder="C:\dev\buildtest\co"
2001-12-31 20:15:57 +00:00
force="true"
2001-12-18 22:18:17 +00:00
/>
< / pre >
The minimum necessary to check out files out from a StarTeam server. This will
check out all files in the < i > AView< / i > view of the < i > AProject< / i > project to
< code > C:\dev\buildtest\co< / code > . Empty folders in StarTeam will have local folders
created for them and any non-StarTeam files found in the tree will be deleted.
Or more simply:
< pre >
< stcheckout URL="STARTEAM:49201/Aproject/AView"
username="auser"
password="secret"
rootlocalfolder="C:\dev\buildtest\co"
2001-12-31 20:15:57 +00:00
force="true"
2001-12-18 22:18:17 +00:00
/>
< / pre >
< br > < / br >
< pre >
< stcheckout URL="STARTEAM:49201/Aproject/AView"
username="auser"
password="secret"
rootlocalfolder="C:\dev\buildtest\co"
rootstarteamfolder="\Dev"
excludes="*.bak *.old"
2001-12-31 20:15:57 +00:00
label="v2.6.001"
force="true"
2001-12-18 22:18:17 +00:00
/>
< / pre >
This will checkout all files from the < i > Dev< / i > folder and below that do not
2001-12-31 20:15:57 +00:00
end in < i > .bak< / i > or < i > .old< / i > with the label < i > v2.6.001< / i > .
2001-12-18 22:18:17 +00:00
< pre >
< stcheckout URL="STARTEAM:49201/Aproject/AView"
username="auser"
password="secret"
rootlocalfolder="C:\dev\buildtest\co"
includes="*.htm,*.html"
excludes="index.*"
2001-12-31 20:15:57 +00:00
force="true"
2001-12-18 22:18:17 +00:00
/>
< / pre >
2001-12-31 20:15:57 +00:00
2001-12-18 22:18:17 +00:00
This is an example of overlapping < i > includes< / i > and < i > excludes< / i > attributes. Because
< i > excludes< / i > takes precedence over < i > includes< / i > , files named < code > index.html< / code > will
not be checked out by this command.
2001-12-31 20:15:57 +00:00
< pre >
< stcheckout URL="STARTEAM:49201/Aproject/AView"
username="auser"
password="secret"
rootlocalfolder="C:\dev\buildtest\co"
includes="*.htm,*.html"
excludes="index.*"
force="true"
recursive="false"
/>
< / pre >
This example is like the previous one, but will only check out files in
C:\dev\buildtest\co, because of the turning off of the recursive attribute.
2001-12-18 22:18:17 +00:00
< pre >
< stcheckout URL="STARTEAM:49201/Aproject/AView"
username="auser"
password="secret"
rootstarteamfolder="src/java"
rootlocalfolder="C:\dev\buildtest\co"
2001-12-31 20:15:57 +00:00
force="true"
2001-12-18 22:18:17 +00:00
/>
< / pre >
< br > < / br >
< pre >
< stcheckout URL="STARTEAM:49201/Aproject/AView"
username="auser"
password="secret"
rootstarteamfolder="src/java"
/>
< / pre >
< br > < / br >
< pre >
< stcheckout URL="STARTEAM:49201/Aproject/AView"
username="auser"
password="secret"
rootstarteamfolder="src/java"
rootlocalfolder="C:\dev\buildtest\co\src\java"
2001-12-31 20:15:57 +00:00
force="true"
2001-12-18 22:18:17 +00:00
/>
< / pre >
In the preceding three examples, assuming that the AProject project has a default folder of
"AProject", the first example will check the files located in starteam under src/java out to a tree rooted at C:\dev\buildtest\co,
the 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.
< a name = "stlabel" >
< h2 > STLabel< / h2 > < / a >
< h3 > Description< / h3 >
Creates 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 exexists in < i > viewname< / i > a label with the same name as the < i > label< / i > parameter.
< h3 > Parameters< / h3 >
< table border = "1" cellpadding = "2" cellspacing = "0" >
< tr >
< td valign = "top" > username< / td >
< td valign = "top" > The username of the account used to log in to the StarTeam server.< / td >
2001-03-16 09:01:38 +00:00
< td align = "center" valign = "top" > yes< / td >
< / tr >
2001-12-18 22:18:17 +00:00
< tr >
< td valign = "top" > password< / td >
< td valign = "top" > The password of the account used to log in to the StarTeam server.< / td >
< td align = "center" valign = "top" > yes< / td >
< / tr >
< tr >
< td valign = "top" > URL< / td >
< td valign = "top" > A string of the form < code > "servername:portnum/project/view"< / code >
which enables user to set all of these elements in one string. < / td >
< td align = "center" valign = "top" > yes*< / td >
< / tr > < tr >
< td valign = "top" > servername< / td >
< td valign = "top" > The name of the StarTeam server.< / td >
< td align = "center" valign = "top" > yes*< / td >
< / tr >
< tr >
< td valign = "top" > serverport< / td >
< td valign = "top" > The port number of the StarTeam server.< / td >
< td align = "center" valign = "top" > yes*< / td >
< / tr >
< tr >
< td valign = "top" > projectname< / td >
< td valign = "top" > The name of the StarTeam project.< / td >
< td align = "center" valign = "top" > yes*< / td >
< / tr >
2001-03-16 09:01:38 +00:00
< tr >
< td valign = "top" > viewname< / td >
< td valign = "top" > The name of the view in the StarTeam project.< / td >
2001-12-18 22:18:17 +00:00
< td align = "center" valign = "top" > yes*< / td >
< / tr >
< tr >
< td valign = "top" > label< / td >
< td valign = "top" > The name to be given to the label< / td >
< td align = "center" valign = "top" > yes< / td >
< / tr >
< tr >
< td valign = "top" > lastbuild< / td >
< td valign = "top" > The timestamp of the build that will be stored with the label. Must be formatted < code > yyyyMMddHHmmss< / code > < / td >
2001-03-16 09:01:38 +00:00
< td align = "center" valign = "top" > yes< / td >
< / tr >
2001-12-18 22:18:17 +00:00
< tr >
< td valign = "top" > description< / td >
< td valign = "top" > A description of the view to be stored in the StarTeam project.< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< / table >
* Either the URL attribute or < b > all four< / b > of the servername, serverport, projectname and viewname attributes must be defined. < br / >
< h3 > Examples< / h3 >
This example shows the use of this tag. It will create a label named < i > Version 6.2< / i > with
< i > "Thorough description"< / i > as its description.
< pre >
< tstamp>
< format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/>
< /tstamp>
< starteamlabel URL="STARTEAM:49201/Aproject/AView"
username="auser"
password="secret"
label="Version 6.2"
lastbuild="${nowstamp}"
description-"Thorough description"
/>
< / pre >
< hr > < / hr >
< a name = "starteam" >
< h2 > Starteam< / h2 > < / a >
< h3 > < i > Deprecated< / i > < / h3 >
< p > < i > This task has been deprecated. Use the < a href = #stcheckout" > STCheckout< / a > task instead.< / i > < / p >
< h3 > Description< / h3 >
Checks out files from a StarTeam project.
< p >
The < i > includes< / i > and < i > excludes< / i > attributes function differently from
other tasks in Ant. Multiple patterns must be separated by spaces, not
commas. See the examples for more information.< / p >
< h3 > Parameters< / h3 >
< table border = "1" cellpadding = "2" cellspacing = "0" >
< tr >
< td valign = "top" > < b > Attribute< / b > < / td >
< td valign = "top" > < b > Description< / b > < / td >
< td align = "center" valign = "top" > < b > Required< / b > < / td >
< / tr >
2001-03-16 09:01:38 +00:00
< tr >
< td valign = "top" > username< / td >
< td valign = "top" > The username of the account used to log in to the StarTeam server.< / td >
< td align = "center" valign = "top" > yes< / td >
< / tr >
< tr >
< td valign = "top" > password< / td >
< td valign = "top" > The password of the account used to log in to the StarTeam server.< / td >
< td align = "center" valign = "top" > yes< / td >
2001-12-18 22:18:17 +00:00
< / tr >
< tr >
< td valign = "top" > servername< / td >
< td valign = "top" > The name of the StarTeam server.< / td >
< td align = "center" valign = "top" > yes< / td >
2001-03-16 09:01:38 +00:00
< / tr >
2001-12-18 22:18:17 +00:00
< tr >
< td valign = "top" > serverport< / td >
< td valign = "top" > The port number of the StarTeam server.< / td >
< td align = "center" valign = "top" > yes< / td >
< / tr >
< tr >
< td valign = "top" > projectname< / td >
< td valign = "top" > The name of the StarTeam project.< / td >
< td align = "center" valign = "top" > yes< / td >
< / tr >
< tr >
< td valign = "top" > viewname< / td >
< td valign = "top" > The name of the view in the StarTeam project.< / td >
< td align = "center" valign = "top" > yes< / td >
< / tr >
2001-03-16 09:01:38 +00:00
< tr >
< td valign = "top" > targetfolder< / td >
2001-12-11 21:08:23 +00:00
< td valign = "top" > The folder to which files are checked out. What this precisely means is determined by the < i > targetFolderAbsolute< / i > param.< / td >
2001-03-16 09:01:38 +00:00
< td align = "center" valign = "top" > yes< / td >
< / tr >
2001-12-07 21:51:01 +00:00
< tr >
2001-12-11 21:08:23 +00:00
< td valign = "top" > targetFolderAbsolute< / td >
< 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).
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 >
2001-12-07 21:51:01 +00:00
< td align = "center" valign = "top" > no< / td >
< / tr >
2001-03-16 09:01:38 +00:00
< tr >
< td valign = "top" > foldername< / td >
< td valign = "top" > The subfolder in the project from which to check out files.< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > force< / td >
< td valign = "top" > Overwrite existing folders if this is set to "true". Defaults to "false".< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > recursion< / td >
< td valign = "top" > Indicates if subfolders should be searched for files to check out. Defaults to "true".< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > verbose< / td >
< td valign = "top" > Provides progress information. Defaults to "false".< / td >
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > includes< / td >
2001-12-11 21:08:23 +00:00
< 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 >
2001-03-16 09:01:38 +00:00
< td align = "center" valign = "top" > no< / td >
< / tr >
< tr >
< td valign = "top" > excludes< / td >
2001-12-11 21:08:23 +00:00
< 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 >
2001-03-16 09:01:38 +00:00
< td align = "center" valign = "top" > no< / td >
< / tr >
< / table >
< h3 > Examples< / h3 >
< pre >
< starteam servername="STARTEAM"
serverport="49201"
projectname="AProject"
viewname="AView"
username="auser"
password="secret"
targetfolder="C:\dev\buildtest\co"
/>
< / pre >
The minimum necessary to check out files out from a StarTeam server. This will
check out all files in the < i > AView< / i > view of the < i > AProject< / i > project to
< code > C:\dev\buildtest\co< / code > .
< pre >
< starteam servername="STARTEAM"
serverport="49201"
projectname="AProject"
viewname="AView"
username="auser"
password="secret"
targetfolder="C:\dev\buildtest\co"
foldername="\Dev"
excludes="*.bak *.old"
force="true"
/>
< / pre >
This will checkout all files from the < i > Dev< / i > folder and below that do not
end in < i > .bak< / i > or < i > .old< / i > . The force flag will cause any existing files to be
overwritten by the version in StarTeam.
< pre >
< starteam servername="STARTEAM"
serverport="49201"
projectname="AProject"
viewname="AView"
username="auser"
password="secret"
targetfolder="C:\dev\buildtest\co"
includes="*.htm *.html"
excludes="index.*"
/>
< / pre >
2001-12-07 21:51:01 +00:00
2001-03-16 09:01:38 +00:00
This is an example of overlapping < i > includes< / i > and < i > excludes< / i > attributes. Because
< i > excludes< / i > takes precedence over < i > includes< / i > , files named < code > index.html< / code > will
not be checked out by this command.
2001-12-07 21:51:01 +00:00
< pre >
< starteam servername="STARTEAM"
serverport="49201"
projectname="AProject"
2001-12-11 21:08:23 +00:00
foldername="src/java"
2001-12-07 21:51:01 +00:00
viewname="AView"
username="auser"
password="secret"
targetfolder="C:\dev\buildtest\co"
2001-12-11 21:08:23 +00:00
targetfolderabsolute="true"
2001-12-07 21:51:01 +00:00
/>
< / pre >
2001-12-11 21:08:23 +00:00
< br > < / br >
2001-12-07 21:51:01 +00:00
< pre >
< starteam servername="STARTEAM"
serverport="49201"
projectname="AProject"
2001-12-11 21:08:23 +00:00
foldername="src/java"
2001-12-07 21:51:01 +00:00
viewname="AView"
username="auser"
password="secret"
targetfolder="C:\dev\buildtest\co"
2001-12-11 21:08:23 +00:00
targetfolderabsolute ="false"
/>
< / pre >
< br > < / br >
< pre >
< starteam servername="STARTEAM"
serverport="49201"
projectname="AProject"
foldername="src/java"
viewname="AView"
username="auser"
password="secret"
targetfolder="C:\dev\buildtest\co\src\java"
targetfolderabsolute="true"
2001-12-07 21:51:01 +00:00
/>
< / pre >
2001-12-11 21:08:23 +00:00
In the preceding three examples, assuming that the AProject project has a default folder of
"AProject", the first example will check the files located in starteam under src/java out to a tree rooted at C:\dev\buildtest\co,
the 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.
2001-12-07 21:51:01 +00:00
2001-03-16 09:01:38 +00:00
< hr >
< p align = "center" >
2002-01-10 08:48:33 +00:00
Copyright © 2001 Apache Software Foundation. All rights Reserved.
2001-03-16 09:01:38 +00:00
< / p >
< / body >
< / html >
