Automated builds using Visual Studio and Rational Team Concert

This is the third part of a blog series on using Rational Team Concert (RTC) with Visual Studio (VS). In part 1, I showed how to set up a basic solution in visual studio integrated with Rational Team Concert. In part 2, I provided a working OSLC sample which we will use in an automated build. We will set up an automated Jazz Build for Visual Studio using using the Jazz Build engine.


In order to do this you will need (in addition to the those required for the previous two parts):


-The Jazz Build Engine 3.0.1.2
-Rational Team Client for Eclipse 3.0.1.2


You may wonder why you need the eclipse version of Rational Team Concert. While you can, request builds, examine build status and see build results from visual studio, you can only create build definitions with the eclipse client at this time. So you will need to unzip the client  launch eclipse and connect to the project area to do this. To understand how to do this you can take a look at the CLM information center (Hint: Go to Team Artifact view and create a repository connection)


To keep text editing to a minimum I will provide the visual studio solution which has all the files required to perform an automated build. You can find it here. Unzip this over the corresponding directories in the solution created in the first two parts or if you are starting from here just unzip this and add it to the correct components (as specified in the first part) in RTC.

This is what should be done:


1. To keep things simple we will set up the automated build on the same machine as the visual studio.  Install the Jazz Build Engine (JBE) in the default directory. In my case, this is the C:\Program Files (x86)\IBM\TeamConcertBuild directory. You will see that all property files are configured with the assumption that the build engine is installed here. 


2. To, once again, keep things simple, we will use the current user (the one you used to log into visual studio) as the build engine user. The first thing we need to do is create a workspace which will be used by the build engine to do the build. Go into Visual Studio and create a new repository workspace from the "OLSC Stream". Right click on the OSLC Stream in the project area and click "New Repository Workspace..."

Call the workspace "OSLC Build Workspace" but do not load the workspace when asked as it will solely be used for build 
purposes.

2. At this point we will need to prepare some files in order to facilitate the build. We will be using the MSBuild process to perform our build and we will need to augment it so that it communicates with the jazz repository once it starts and finishes.  MSBuild uses the .proj files to build and we need to modify this file to add some pre and post-build hooks. To do this we would need to change the "OSLC Consumer.proj" file. To modify this file from visual studio it needs to be unloaded and edited. This can be accomplished by right clicking the project in visual studio, click unload and then subsequently "Edit OSLC Consumer.proj". 
Navigating to the end of the file you will see that the following has been added towards the end of the file:



<Import Project="..\OSLCProperties.xml" />
  <Target Name="BeforeBuild" Condition="'$(fetchDestination)'!= '' ">
    <Exec Command="$(AntCommand)-DactivityLabel=startActivity $(propertyFile) $(jazzbuildxml) startActivity" />
  </Target>
  <Target Name="AfterBuild" Condition="'$(fetchDestination)' !='' ">
    <Exec Command="$(AntCommand) -DactivityLabel=publishActivity $(propertyFile) $(jazzbuildxml) publishActivity" />
   </Target>

This uses an OSLCProperties.xml which contains the properties that are used here: $(AntCommand),  $(propertyFile) and $(jazzbuildxml). The $(fetchDestination) will be passed into MSBuild using a command line argument defined in the build definition. (We will do this later).


You will find the OSLCProperties.xml in the solution directory (the root directory of the work space and contains the following. You may need to adjust the JBE root directory to reflect your environment.



<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>  
    <AntCommand>"C:\Program Files (x86)\IBM\TeamConcertBuild\jre\bin\java.exe" -cp "C:\Program Files (x86)\IBM\TeamConcertBuild\buildsystem\buildengine\eclipse\plugins\org.apache.ant_1.7.1.v20090120-1145\lib\ant-launcher.jar" org.apache.tools.ant.launch.Launcher -cp "C:\Program Files (x86)\IBM\TeamConcertBuild\jre\lib" -lib "C:\Program Files (x86)\IBM\TeamConcertBuild\buildsystem\buildtoolkit"</AntCommand>
    <propertyFile>-propertyfile "C:\Program Files (x86)\IBM\TeamConcertBuild\buildsystem\buildengine\eclipse\OSLCBuild.properties"</propertyFile>
    <jazzbuildxml>-f $(fetchDestination)\OSLC\jazzbuild.xml</jazzbuildxml>
  </PropertyGroup>
</Project>

The last file needed is the actual ant file that contains the tags used to communicate with the jazz repository, the jazzbuild.xml file. It contain two activities, one that is launched after the build, "startActivity" and another that is lauched after the build, "publishActivity" that is used to publish the build result. (They are launched from the msbuild tool using the hooks in the .proj above that it uses to perform the build.)


All of these new files should be checked in and delivered into the "OSLC Stream" so that they may be used by the Build engine.

3. Now lets create a build engine and build definition in Rational Team Concert for eclipse. Launch RTC for eclipse and create a "Jazz Build Engine" build definition for the OSLC project area by right clicking on "Build Engines" and give it the name "OSLC Build Engine".  

You may now see a warning that the build engine is not running:

This is a good indication that the build engine is not running. Lets start it now.


4. To, once again, keep things simple, we will use the current user (the one you used to log into visual studio) as the build engine user. With that in mind execute run the build engine. You should see command prompt output as follows:



C:\Program Files (x86)\IBM\TeamConcertBuild\buildsystem\buildengine\eclipse>
jbe -repository https://<rtc host name>:<rtc port>/ccm -userId <rtc build username> -pass <rtc build user password> -engineID "OSLC Build Engine"
2012-03-04 10:29:29 [Jazz build engine] Running build loop...
2012-03-04 10:29:29 [Jazz build engine] Waiting for request...



Now refreshing the build engine page in RTC should eliminate the error.


5. Next we need to create a new build definition called "OSLC Build" for the OSLC project area of type "Jazz Build for Microsoft Visual Studio Solution - Jazz Build Engine"

Ensure that you select "Jazz Source Control" as a pre-build option:

Select MSTest Configuration as a post-build option.

Once you created the build it should be opened and now you must add the build engine we created previously as a supported build engine in the Overview tab.

In the "Jazz Source Control" tab we must specify the workspace we created previously for the purposes of building as the Build Workspace and also specify a directory that will be used to load this workspace during the build process called "OSLC Build Workspace". We should also specify "Delete directory before loading".

Now we must specify some details about the build in the "Microsoft Build" tab. Depending on the install path of your visual studio some of these may need to be adjusted according to your environment:

Some things to note on this page. The OSLCBuild.properties file is a file generated by the JBE that contains the properties used during a build. You also see that here we are passing in the $(fetchDirectory) property that we are using above in the .proj hook. We are using MSBuild as it is more suitable for what we want to do but it is also possible to use the Visual studio "devenv.exe" to do the build. This is usually more useful if there are some visual studio integrations that the build depends on (pre compilers, etc.).


The next tab "MSTest Configuration" is also given here but is unused at the present time and is provided for a future lab. It must nevertheless be completed in order for the build to succeed.   You may need to change the paths as appropriate:

Now you should be able to save the build definition and then you are done with RTC for eclipse.


6. Go back to visual studio and refresh the builds area and now you should be able to request a build from here. You may do so now. Leave the default options and submit.

7. After the build request has been submitted you will see it in the build queue. It may take a little while to build and return eventually with a "Completed" status and a green check mark.

8. Whether the build succeeded or not you can double click on the build to see the results, including the logs and, if successful, a link to the resulting .exe in the "Downloads" tab. If something went wrong you can examine the logs to see what the issue is.

Voila! An automated build using the JBE and visual C++!