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
starteam-sdk.jar
in your classpath to run these tasks.
For more information about the StarTeam API and how to license it, see
the Borland web site.
On Windows machines, the mere presence of starteam-sdk.jar
on the classpath
is not sufficient for getting these tasks to work properly. These tasks also require a
fully-installed and fully-licensed version of the StarGate Runtime. This is part
of a StarTeam client installation or may be installed separately. The full client
install is not required. In particular, the Windows path must include the directory where
the StarGate Runtime .dll
files are installed.
Earlier versions of Ant (prior to 1.5.2) did not have this restriction because they were not as dependent on the StarTeam runtime - which the newer versions use to access StarTeam file status information. The older versions lacked this important capability.
The following parameters, having to do with making the connection to a StarTeam project, are common to all the following tasks except the deprecated StarTeam task.
Attribute | Description | Required |
username | The username of the account used to log in to the StarTeam server. | yes |
password | The password of the account used to log in to the StarTeam server. | yes |
URL | A string of the form servername:portnum/project/view
which enables user to set all of these elements in one string. |
Either this ... |
servername | The name of the StarTeam server. | ... or all four of these must be defined. |
serverport | The port number of the StarTeam server. | |
projectname | The name of the StarTeam project on which to operate. | |
viewname | The name of the view in the StarTeam project on which to operate. |
The includes and excludes attributes function differently from other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
Attribute | Description | Required |
rootstarteamfolder | The root of the subtree in the StarTeam repository from which to check out files. Defaults to the root folder of the view ('/'). | no |
rootlocalfolder | 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 rootstarteamfolder is used. | no |
createworkingdirs | creates local folders even when the corresponding StarTeam folder is empty. Defaults to "true". | no |
deleteuncontrolled | if true, any files NOT in StarTeam will be deleted. Defaults to "true". | no |
includes | Only check out files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. | no |
excludes | Do not check out files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. | no |
label | 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. | no |
recursive | Indicates if subfolders should be searched for files to check out. Defaults to "true". | no |
forced | 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". | no |
locked | If true, file will be locked against changes by other users. If false (default) has no effect. | Either or neither, but not both, may be true. |
unlocked | If true, file will be unlocked so that other users may change it. This is a way to reverse changes that have not yet been checked in. If false (default) has no effect. |
<stcheckout servername="STARTEAM" serverport="49201" projectname="AProject" viewname="AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" force="true" />The minimum necessary to check out files out from a StarTeam server. This will check out all files in the AView view of the AProject project to
C:\dev\buildtest\co
. Empty folders in StarTeam will have local folders
created for them and any non-StarTeam files found in the tree will be deleted.
<stcheckout URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" forced="true" />And this is a simpler way of accomplishing the same thing as the previous example, using the URL attribute.
<stcheckout URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" rootstarteamfolder="\Dev" excludes="*.bak *.old" label="v2.6.001" forced="true" />This will check out all files from the Dev folder and below that do not end in .bak or .old with the label v2.6.001.
<stcheckout URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" includes="*.htm,*.html" excludes="index.*" forced="true" />This is an example of overlapping includes and excludes attributes. Because excludes takes precedence over includes, files named
index.html
will
not be checked out by this command.
<stcheckout URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" includes="*.htm,*.html" excludes="index.*" forced="true" recursive="false" />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.
<stcheckout URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootstarteamfolder="src/java" rootlocalfolder="C:\dev\buildtest\co" forced="true" />
<stcheckout URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootstarteamfolder="src/java" />
<stcheckout URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootstarteamfolder="src/java" rootlocalfolder="C:\dev\buildtest\co\src\java" forced="true" />In the preceding three examples, assuming that the AProject project has a default folder of "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, the second to a tree rooted at C:\work\AProject\src\java (since no rootlocalfolder 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.
The includes and excludes attributes function differently from other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
Attribute | Description | Required |
rootstarteamfolder | The root of the subtree in the StarTeam repository into which to files will be checked. Defaults to the root folder of the view ('/'). | no |
rootlocalfolder | 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 rootstarteamfolder is used. | no |
comment | Checkin comment to be saved with the file. | no |
adduncontrolled | if true, any files or folders NOT in StarTeam will be added to the repository. Defaults to "false". | no |
includes | Only check in files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. | no |
excludes | Do not check in files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. | no |
recursive | Indicates if subfolders should be searched for files to check in. Defaults to "false". | no |
forced | If true, checkins 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 checkin will be based on statuses which do not relate to the target folder. Defaults to "false". | no | unlocked | If true, file will be unlocked so that other users may change it. If false (default) lock status will not change. | no |
<stcheckin servername="STARTEAM" serverport="49201" projectname="AProject" viewname="AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" forced="true" />The minimum necessary to check files into a StarTeam server. This will check all files on the local tree rooted at
C:\dev\buildtest\co
into the AView view of the AProject project in the repository.
For files and folders in the local tree but not in starteam, nothing will be done. Since the forced 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.
<stcheckin URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" forced="true" />And this is a simpler way of giving the same commands as the command above using the URL shortcut.
<stcheckin URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" rootstarteamfolder="\Dev" excludes="*.bak *.old" forced="true" />This will check all files in to the Dev folder and below that do not end in .bak or .old from the tree rooted at"C:\dev\buildtest\co" .
<stcheckin URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" includes="*.htm,*.html" excludes="index.*" forced="true" />This is an example of overlapping includes and excludes attributes. Because excludes takes precedence over includes, files named
index.html
will
not be checked in by this command.
<stcheckin URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" rootstarteamfolder="src/java" includes="*.htm,*.html" excludes="index.*" forced="true" recursive="false" />This example is like the previous one, but will only check in files from C:\dev\buildtest\co, because of the turning off of the recursive attribute.
<stcheckin URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" rootstarteamfolder="src/java" includes="version.txt" forced="true" recursive="false" />This 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.
<stcheckin URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootlocalfolder="C:\dev\buildtest\co" rootstarteamfolder="src/java" includes="version.java" forced="true" recursive="false" addUncontrolled="true" comment="Fix Bug #667" />This 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 addUncontrolled 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.
<stcheckin URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootstarteamfolder="src/java" rootlocalfolder="C:\dev\buildtest\co" forced="true" />
<stcheckin URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootstarteamfolder="src/java" />
<stcheckin URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" rootstarteamfolder="src/java" rootlocalfolder="C:\dev\buildtest\co\src\java" forced="true" />In the preceding three examples, assuming that the AProject project has a default folder of C:\work\buildtest\co\AProject, the first example will check in files from a tree rooted at C:\dev\buildtest\co, the second from a tree rooted at C:\work\buildtest\co\AProject\src\java, and the third from a tree rooted at C:\dev\buildtest\co\src\java all to a tree rooted at src/java
Attribute | Description | Required |
label | The name to be given to the label | yes |
lastbuild | The timestamp of the build that will be stored with the label. Must be formatted yyyyMMddHHmmss |
yes |
description | A description of the label to be stored in the StarTeam project. | no |
<tstamp> <format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/> </tstamp> <stlabel URL="STARTEAM:49201/Aproject/AView" username="auser" password="secret" label="Version 6.2" lastbuild="${nowstamp}" description="Thorough description" />
Attribute | Description | Required |
rootstarteamfolder | The root of the subtree in the StarTeam repository to be listed. Defaults to the root folder of the view ('/'). | no |
rootlocalfolder | 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 rootstarteamfolder is used and a status field will appear in the listing. Otherwise, the status field will not appear. | no |
includes | Only list files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. | no |
excludes | Do not list files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. | no |
label | 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. | no |
recursive | Indicates if subfolders should be searched for files to list. Defaults to "true". | no |
<stlist url="WASHINGTON:49201/build" username="auser" password="secret" />The above command might produce the following listing:
[stlist] Folder: Build (Default folder: C:/work/build) [stlist] Folder: dev (Default folder: C:/work/build/dev) [stlist] Out of date Sue Developer 1/1/02 7:25:47 PM CST 4368 build.xml [stlist] Missing George Hacker 1/1/02 7:25:49 PM CST 36 Test01.properties [stlist] Current 1/1/02 7:25:49 PM CST 4368 build2.xml [stlist] Folder: test (Default folder C:/work/build/dev/test) [stlist] Missing 1/1/02 7:25:50 PM CST 4368 build2.xmlwhile adding a rootlocalfolder and an excludes param ...
<stlist url="WASHINGTON:49201/build" username="auser" password="secret" rootlocalfolder="srcdir2" excludes="*.properties" />might produce this listing. The status is missing because we are not going against the default folder.
[stlist] overriding local folder to srcdir2 [stlist] Folder: Build (Local folder: srcdir2) [stlist] Folder: dev (Local folder: srcdir2/dev) [stlist] Sue Developer 1/1/02 7:25:47 PM CST 4368 build.xml [stlist] 1/1/02 7:25:49 PM CST 4368 build2.xml [stlist] Folder: test (Local folder: srcdir2/dev/test) [stlist] 1/1/02 7:25:50 PM CST 4368 build2.xml
This task has been deprecated. Use the STCheckout task instead.
The includes and excludes attributes function differently from other tasks in Ant. Multiple patterns must be separated by spaces, not commas. See the examples for more information.
Attribute | Description | Required |
username | The username of the account used to log in to the StarTeam server. | yes |
password | The password of the account used to log in to the StarTeam server. | yes |
servername | The name of the StarTeam server. | yes |
serverport | The port number of the StarTeam server. | yes |
projectname | The name of the StarTeam project. | yes |
viewname | The name of the view in the StarTeam project. | yes |
targetfolder | The folder to which files are checked out. What this precisely means is determined by the targetFolderAbsolute param. | yes |
targetFolderAbsolute | Determines how targetfolder is interpreted, that is, whether the StarTeam "default folder" for the project is factored in (false) or whether targetFolder is a complete mapping to foldername (true). If "true", the target tree will be rooted at targetfolder+"default folder". If false, the target tree will be rooted at targetfolder. Defaults to "false". | no |
foldername | The subfolder in the project from which to check out files. | no |
force | Overwrite existing folders if this is set to "true". Defaults to "false". | no |
recursion | Indicates if subfolders should be searched for files to check out. Defaults to "true". | no |
verbose | Provides progress information. Defaults to "false". | no |
includes | Only check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in excludes take precedence over patterns in includes. | no |
excludes | Do not check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in excludes take precedence over patterns in includes. | no |
<starteam servername="STARTEAM" serverport="49201" projectname="AProject" viewname="AView" username="auser" password="secret" targetfolder="C:\dev\buildtest\co" />The minimum necessary to check out files out from a StarTeam server. This will check out all files in the AView view of the AProject project to
C:\dev\buildtest\co
.
<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" />This will checkout all files from the Dev folder and below that do not end in .bak or .old. The force flag will cause any existing files to be overwritten by the version in StarTeam.
<starteam servername="STARTEAM" serverport="49201" projectname="AProject" viewname="AView" username="auser" password="secret" targetfolder="C:\dev\buildtest\co" includes="*.htm *.html" excludes="index.*" />This is an example of overlapping includes and excludes attributes. Because excludes takes precedence over includes, files named
index.html
will
not be checked out by this command.
<starteam servername="STARTEAM" serverport="49201" projectname="AProject" foldername="src/java" viewname="AView" username="auser" password="secret" targetfolder="C:\dev\buildtest\co" targetfolderabsolute="true" />
<starteam servername="STARTEAM" serverport="49201" projectname="AProject" foldername="src/java" viewname="AView" username="auser" password="secret" targetfolder="C:\dev\buildtest\co" targetfolderabsolute ="false" />
<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" />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.
Copyright © 2001-2002 Apache Software Foundation. All rights Reserved.