Using Rational Team Concert on Mac with Xcode (Part 3)
Chris McGee, IBM Canada Ltd.
Last updated: June 1, 2012
Build basis: Rational Team Concert 4.0, Xcode 4.1
This is the last article in a three part series covering how to use Mac and Xcode with RTC. Previously, you saw how you could transition your project from a single contributor to multiple contributors. Work items enable you to record the outstanding defects, tasks and enhancements as well as review each other’s changes. You have built up a collection of useful Jazz SCM CLI commands along the way.
In order to release your product one of the members of your team uses Xcode to produce a release build, runs the unit tests to make sure they are green, creates a disk image (dmg file) and creates a snapshot to record the state. It would be much better if this work was automated so that builds are created in a consistent way every time. It would be great if anyone can trigger a build when they need one and to have builds scheduled automatically.
Setting up automated builds in RTC
Xcode provides a set of tools to run headless builds and run unit tests but they have to be run on a Mac. The builds should run on a desktop computer or server grade computer that will not be taken offline very often and has constant network access to the RTC server.
Once you pick a computer to run your builds you can install the Jazz Build System Toolkit available on jazz.net via the RTC Downloads > All Downloads section. The build system toolkit includes a build engine that you run so that it continually checks for build requests from the RTC server. Once a build is scheduled the build engine will run what you have defined in your build definition and send the results back to the RTC as part of the build results.
The build engine needs to authenticate to the RTC server. In order to do this the build engine must log in using a build user account (e.g. macbuild) on the RTC server. It is not recommended that you use your normal user account for this. The build user will need access to your project area so it should be added as a member of your team. Contact your RTC server administrator to help create the user and add them to your project area. Make sure to protect the password to the account as it will have access to your project area and your code.
When you run the build engine it authenticates but then needs a build engine id on the server in order to identify itself for build requests. This can only be done using the RTC Eclipse client. Launch the Eclipse client and open up the Team Artifacts view like you did in the previous article. Expand your project area and go to Builds > Build Engines and right-click to choose New Build Engine. Leave the first page of the wizard with the defaults and click next. On the second page choose a unique identifier for your build engine and write it down for later. Make sure that the build engine type is set to Jazz Build Engine and click finish.
New build engine
New build engine wizard
Build engine type and identifier
Before starting up the build engine there are some extra paths that should be added to your path so that the build engine can run Xcode build scripts when requested. If you have not already done so add the following path to the .bash_profile of your build account on your build computer (e.g. /Users/Build/.bash_profile).
Once you have have added a build engine, a build user and added the special Xcode path you can start up your build engine on your build computer. Make sure to restart the terminal app to get the new path you added and run the build engine with this command.
$ <fill_in_path_here>/jazz/buildsystem/buildengine/jbe.sh -repository https://myserver:9443/jazz -userId macbuild -pass xyzabc -engineId xcodebuilder 2012-06-08 09:47:21 [Jazz build engine] Running build loop... 2012-06-08 09:47:21 [Jazz build engine] Waiting for request... ...
The user id and password are the ones that this build user uses to authenticate against the RTC server. The build engine id should be the same as you created on the RTC server. You should start up the build engine interactively from the desktop and not through a remote shell or system startup task to make sure that the build engine has access to the Mac UI. There are certain tasks such as the unit tests that require access to the UI in order to work properly.
In the above example the build engine is run with the password provided as a command-line parameter. This is not the most secure way to do this. There is a special build engine command that allows you to generate a hashed password for your password and store this in a file. The file should still be secured properly but it adds an extra measure of security.
$ <fill_in_path_here>/jazz/buildsystem/buildengine/jbe.sh -createPasswordFile ~/passwordFile $ <fill_in_path_here>/jazz/buildsystem/buildengine/jbe.sh -passwordFile ~/passwordFile -repository https://myserver:9443/jazz -userId macbuild -engineId xcodebuilder 2012-06-08 09:47:21 [Jazz build engine] Running build loop... 2012-06-08 09:47:21 [Jazz build engine] Waiting for request... ...
The build engine is now ready to execute build requests but you will first need a build definition. Build definitions can only be created using the Eclipse client. Go to your project area in the Team Artifacts view, right-click on Builds and choose New Build Definition. Click next on the first page of the wizard. on the second page choose a build definition ID and select the "Ant – Jazz Build Engine" type. Ant is a popular XML build scripting language and will be used as the front-end script for this build. On the third page check "Jazz Source Control" so that the build will perform SCM related operations to get the latest code from the stream and load the contents into a build directory. Finally, on the fourth page check "JUnit Publishing" to enable unit tests results to be published.
New build definition
New build definition wizard
Set build definition type
Add Jazz Source Control option
Add unit test publishing option
Once you have created your build definition you can start editing it to add in the details of your build. For example, the build definition will need to have the path to your build directory where the Xcode source code will be placed and then built. Also, you can create your repository workspace on the server to accept changes from the stream, snapshot and load into the build directory.
Add build engine
Builds require a repository workspace to accept changes from the team stream, create snapshots and load your Xcode project code into a build directory. Also, people in the team can use it to compare build snapshots to find differences in the code. In the "Jazz Source Control" section you can create the repository workspace using the "Create…" button. Create the repository workspace from your team stream so that it flows with that stream and has an initial contents. When you are ready to save, make the visibility public and change the owner to the special build user for your build engine.
Jazz source control page
Create repository workspace
Once you have set the repository workspace in the build definition the build engine will need to know where to load the code on the local filesystem. Create an empty build directory on your build computer (e.g. /Users/Build/builddir) and provide this path in the "Load Directory" field of the build definition. It is recommended that you check the "Delete directory before loading" option to prevent cross-build contamination from an older build to a newer one.
The build definition needs an Ant script in order to execute the build steps after the source code has been loaded into the build directory. The Ant script will also inform the RTC server what activity the build is running as well as publish downloads, logs and test results. The Ant script setup options are in the "Ant" section of the build definition.
A sample zip is provided to demonstrate how to run an Xcode build and test. Unzip it into your development sandbox, edit them to suit the project names and settings for your project, check them in to a change set and deliver them to the stream. The build definition needs to know the location of the build script on the build computer after it is loaded into the build directory. Put this path in the "Build file" field (e.g. /Users/Build/builddir/MyXcodeProject/build.xml).
Set the Ant script path
In order for the Ant script to communicate with the server it needs the build user credentials and the special password file. See the comments at the top of the build.xml script for more details. Although the build scripts are in your sandbox keep in mind that when the build executes them they will be loaded into the build directory on the build computer and not your sandbox. The password file should be on the build computer with permissions only for the build user to see it. Do not check it in nor share it with anyone else on the team.
If you want to run the build on a regular schedule like every weekday at 5:00pm then you can use the "schedule" section of the build definition. You can use this section to run the build continuously every x number of minutes if there are any new change sets delivered to the stream.
Working with builds
Now that the build engine, build definition and build scripts are in place you or anyone else on your team can request a build using your web browser. Go to the RTC server URL (e.g. https://myserver:9443/jazz), login using your normal user credentials (not the build user). Once you have logged in pick the project area and then click on the Builds > Build Definitions and choose your build definition.
Request a build
From the build definition screen you can see any previous builds that have run before and request new builds using the "Request Build" button on the upper-right. Once a build has been submitted it’s progress is shown in the build definition screen. You can click on the build to get a build summary.
Build definition screen
Request build screen
Build test results
Builds will pass and fail from time to time. Also, the application will occasionally break from one build to another. Builds are really useful for identifying the cause of the regressions because you can easily compare them to find the cause of the failure or regression. On the build definition screen check two builds and click on the "Compare Build" button in the upper-right. The snapshot compare screen has two tabs, which show the change sets that are in one build but not the other.
Compare builds from the build definition screen
Compare build results
Test changes with a personal build
When projects get large and it takes more than a trivial amount of time to build and run all of the unit tests. There can be times when you want to test out a set of changes to make sure that they don’t produce a build failure in the regular build but it would take too long to run on your development computer. Perhaps your development computer is a MacBook and you want to be able to sleep it in between meetings or leaving work at the end of the day?
Jazz Build has a special "personal" build option that you can use. Instead of using the repository workspace that is normally used in the build it can use the development workspace you use for your normal development activities. The workspace must have a public visibility and as long as you have checked everything in it will perform a build and run the unit tests against your changes before you deliver them.
To set your repository workspace as public you will need to use the Eclipse client. Launch it as described earlier, create a repository connection to your RTC server and find your repository workspace under My Repository Workspaces in the Team Artifacts View. Double-click on the workspace and change visibility to Public.
Change repository workspace visibility to public
You can request a personal build in the same way as a regular build except you check the "Personal Build" option and choose your repository worksace in the request build screen.
Request personal build
Compare build results
This final article in the series demonstrated how you can create Xcode builds and unit tests into RTC. Using a separate build computer builds can be scheduled by anyone on the team and/or scheduled automatically on a regular basis. The build results are recorded along with a downloadable disk image, logs, test results and a snapshot. Any user on the team can look at these results and and compare builds to see the changes in the code. Personal builds are available for you to try out changes in a build before delivering them to the team stream.
RTC can complement the Xcode IDE in the development of Mac applications. As your team expands beyond a single person RTC brings powerful collaborative features including stream management, work item tracking and builds. This series has only briefly touched on each of these areas for demonstation purposes. There are many more areas to explore.
About the author
Chris McGee is a member of the Jazz Source Control team. Previously, he worked on modeling tools for the Rational Software Architect project.
Copyright © 2012 IBM Corporation