August 7, 2007

CruiseControl.NET Integration

Surround SCM
The following article is a summary of the steps taken to integrate CruiseControl.Net with a simple Visual Basic 2005 project stored in Surround SCM. The version used in this article is 1.3 and it was downloaded from SourceForge. For more information on CruiseControl.NET please visit this site


SourceForge site's gives a few options as to what to download. For this article, the Windows installer was downloaded (.msi file). All default settings were accepted (including using IIS for the web dashboard).

Configuring the Server

The next step is to configure the server. To do this, the ccnet.config file must be set up. Before going into details, let's take a look first at the project being used in this example: The project is a single form application written in C# using Visual Studio 2005. In order to set up the ccnet.config file. you will need to know the branch, repository and working directory for this project in Surround SCM. The screenshot below shows the project in Surround SCM:
The ccnet.config file will be set so a everytime a change is detected, a snapshot branch will be created under the current branch, WysiCM 1.x, which is a "maintenance" branch for the ficticious product WysiCM version 1. Here is the ccnet.config file used in this example:
  <project name="SurroundSCMSampleProject" webURL="http://localhost/ccnet">
   <sourcecontrol type="surround">
     <executable>C:Program FilesSeapineSurround SCMsscm.exe</executable>
     <branch>"WysiCM 1.x"</branch>
     <repository>"WysiCorp Products/WysiCM"</repository>
     <workingDirectory>"D:WysiCM 1.x"</workingDirectory>
  		<workingDirectory>D:WysiCM 1.x</workingDirectory>
                <logger>c:Program FilesCruiseControl.NETserverRodemeyer.MsBuildToCCNet.dll</logger>
      <xmllogger logDir="log" />

The file is located under the server directory. Under a default installation, it was installed in "C:Program FilesCruiseControl.NETserver". Also, note that this is a very simple config file. More options could used in this file. Please refer to the CruiseControl.NET documentation for more information on all available options. Now for a bried discussion on some of the items in the config file: Project name: This is the CruiseControl.NET project name, does not have to nescessarily match the application name. Executable: Path to the command line interface executable for Surround SCM. Server connect: The address and port number of the Surround SCM server. Server Login: The Surround SCM username and password. Probably do not want to use Administrator with a blank password. You would set up sometihng linke <username>:<password>. You should create user that has read-only access at the file level. The user has create branch rights but can only login from the CLI. This is necessary because the username and password will be displayed in plain text in the build reports and any batch files used to create snapshots. This allows the user to Get the latest source code and create the snapshot branch, while preventing users who know the login credentials from performing other activities like a check in, rename, or remove. Branch: Name of the branch in Surround SCM. Hint: To avoid spell errors, right click on the branch in Surround SCM, and select "Properties". You can select, and copy the branch name and then paste it into the config file.Repository: The repository name in Surround SCM (must include the full path). Hint: To avoid spell errors, right click on the repository in Surround SCM, and select "Properties". You can select, and copy the repository name and then paste it into the config file. The repository name in the properties window contains the full path.Working Directory: The working directory for the repository specified above. Hint: To avoid spell errors, right click on the repository in Surround SCM, and select "Properties". You can select, and copy the working directory and then paste it into the config file.Recursive: Indicates whether to include sub repositories. A one means yes, a zero means no. File: The asterisk indicates to include all files. SearchRegExp: Indicates whether to evaluate the value given for the file above as a regular expression. A one means yes, a zero means no. Few things to note:
  • All of the values under the <source control> tags that were enclosed in quotation marks are becuase they contain spaces. These values will be passed to the Surround SCM Command Line Interface, and this requires that any parameter that contains spaces be contained within quotation marks.
  • The logger file used, Rodemeyer.MsBuildToCCNet.dll was not installed by default. Please refer to this page for further information on how to obtain it.
  • The batch file, C:snap.bat will actually create the snashot branch. The way this batch file is created, it will only allow for the creation of one snapshot per day. This are the contents of this batch file:
sscm mb "WysiCM 1.x - %CCNetBuildDate%" "WysiCorp Products/WysiCM" -b"WysiCM 1.x" -cc"CC.NET Build" -ssnapshot -yAdministrator: -z127.0.0.1:4900
The batch file only consists of the make branch command in the Surround SCM CLI. The CruiseControl.NET environment variables for build date is used as part of the snapshot branch name. Since the date is being used as part of the name, this will only allow you to create one snapshot per day (a second one in one day would result in an error, since the branch name already exists). Using the CruiseControl.NET %CCNetBuildTime% will result in an error because the value returned by this variable contains colons, and you can not include colons in a branch name, and the branch will not be created and result in an error. An alternative could be to use a random number for the branch name. You would use the %RANDOM% variable for this, however, the name would not make much sense then. A better approach would be to create an executable instead of a batch file. Using a programming language you can use string functions to strip the colons out of the time variable.

Setting it into Motion

To start this process, the first thing is to start the server executable, by default installed under "C:Program FilesCruiseControl.NETserver". The file name is ccnet.exe. This will bring up a command console that you can monitor the progress with. Then, in Surround SCM, a small change is made to the Form1.Designer.cs file (the cordinate for a button was changed) and checked in. The next interval, Cruise Control detects the change, and it launches a build. The batch file then creates the snapshot branch. Once it is finished, look for a success message. A failure message indicates someting did not work properly. Once the process finish you can close the CCNET console window to stop the process. Otherwise, based on your configuration, CruiseControl.NET will again attempt to run a build next time it detects a change, and it will then try to create the snapshot branch with the name already used, which will result in a failure message by CruiseControl.NET. In the same directory as the exectuable, there will be a ccnet.log file that captures the same output seen in the console window. The screenshot below shows the snapshot branch created by this process.


The following references were used in the writing of this article and in the implementation of the example used in the article: Surround SCM CruiseControl.NET ExampleCruiseControl.NET Page mantained by ThoughtWorks