Search:     Advanced search

Surround SCM Apache Ant Integration

Article ID: 769  |  Last updated: 04 May, 2017

Surround SCM supports integration with Apache Ant. See Surround SCM Third-Party Integrations for supported platforms and versions.

This article includes information about installing the plug-in, supported Surround SCM actions, defining and adding Surround SCM tasks to build files, automating builds, and troubleshooting.

Installing the plug-in

  1. Download the plug-in.
  2. Unzip the file.
  3. Copy the surround.jar file from the Suround SCM application directory (e.g., C:\Program Files\Perforce\Surround SCM) to the ANT_HOMElib directory.

Supported Surround SCM actions

The following Surround SCM actions are supported: Get, Check Out, Check In, Freeze, Unfreeze, Branch, Label, and Batch. You can view example tasks in the sample build.xml file. See the Ant help for additional information about supported tasks.

Note: You must provide the server connection information when performing Surround SCM actions. If you received a server settings file for RSA key exchange from your Surround SCM administrator, you must specify the path to the XML file instead of the server address and port number. 

Defining and adding Surround SCM tasks to build files

After all the application project files are added to Surround SCM, you can define and add Surround SCM tasks to the Ant build file. Tasks must first be defined at the top of the build file and then they can be added to the targets.

The attached file includes an example build file for a Java application named MessageRunner, which was created using the Ant Hello World tutorial. The file includes Surround SCM tasks to get the latest version of project files, check in the files after the build, and create a snapshot branch to capture the build. Depending on your setup, you may need to add different tasks to the build file. For example, you may add tasks to check out files depending on the server configuration or to freeze the branch before the build and unfreeze it after.

Note: The ${DSTAMP} and ${TSTAMP} Ant properties are used in the example to return the current date and time and create a unique snapshot branch name. To set the properties, is added before the branch task.

After the Surround SCM tasks are saved in the build file, enter the Ant command at a command prompt to run the build.

Automating builds

You can use Surround SCM changelists and triggers to automate builds. Because triggers do not run from the directory where the build file is located, you can use a batch file command with the -buildfile option to specify the file to run.

If using the MessageRunner example, the batch file needs to include the following command:

ant -buildfile C:\MessageRunner\build.xml

You can then create a trigger to run the batch file after a changelist is committed. Following is an example of the options set for the trigger:

Trigger applies to files in branch [Ant Example] and in repository [Ant Example/MessageRunner/src] — after an event when a changelist is committed — Run script located at "C:\batch\anttrigger.bat"

To add more events to the workflow, you may want to create additional triggers to change the file state after a build is created.


Exceptions after getting files

Surround SCM may return an unexpected message to Ant, which causes exceptions. Make sure the force="true" parameter is included in the Get command to force retrieval from the server.

Unable to check in files

The files are not checked out and the server does not allow check in without check out. A Surround SCM task to check out files is not used in the MessageRunner example, so the example only works if connecting to a Surround SCM Server configured to allow check in of files without check out. Make sure the tasks added to your build file perform actions allowed in Surround SCM.

Files are read-only

The files were not made writable when retrieved from Surround SCM. Change the writable flag to true in the sscmget task to ensure retrieved files are writable.

If you are using DOS, you can also run the following command in the top-level directory to make the files writable:

attrib -r *.* /s

Snapshot branch is not created

A branch with the same name already exists. If you use the ${TSTAMP} Ant property to name the snapshot branch, multiple builds run within the same minute have the same timestamp because the property only provides the hours and minutes. Leave at least a one-minute difference between the build timestamps.

Article ID: 769  |   Last updated: 04 May, 2017
Apache Ant

Attached files
file MessageRunnerExample.txt (2 kb)

Prev   Next
Metacity Crashes When Using Surround SCM Integrations on Ubuntu     Surround SCM CruiseControl.NET Integration