Monday, May 11, 2009

TeamCity, Ant & DITA

Over the last few days I have been trying to get a CI server (aka build server) up and running. After trying out both CruiseControl and CruiseControl.NET I landed on TeamCity since it is a bit simpler with a decent web GUI as well as being somewhat familiar from my work.

You can download TeamCity and try it out for yourself since they offer a free edition that supports up to 20 build configurations and 3 build agents.

One of the tasks I wished to accomplish in by CI server was to build the online help files (HTML) as well as the user manual (PDF). Having all the source material in DITA formatted XML files makes that pretty easy from the command line using the DITA Open Toolkit full easy install distribution. Getting it to run automatically from TeamCity proved to cost me some gray hairs though.

So as a note-to-self here is a short checklist of what to do after TeamCity has been installed:
  1. Download DITA and unzip it. (Ex in: C:\DITA-OT1.4.3)
  2. Create a new build configuration for you project, and set "Ant" as the "Build runner".
  3. "Ant Home" should be the ant folder in your DITA installation. (Ex: c:\DITA-OT1.4.3\tools\ant\)
  4. In "Additional Ant Command Line Options" input the classpath and any options for Ant or the DITA toolchain it spawns.
  5. Add DITA_DIR environment variable to the build configuration and set it to the folder you unzipped DITA to in step 1.
  6. Create a build.xml file for your targets and point TeamCity at it.
Setting the CLASSPATH environment variable had NO effect, neither had adding -classpath to the JVM command line options. Only adding it as a -cp option to the Ant command line did the trick. I did not find any mention of this in either DITA documentation or TeamCity documentation.
It might be obvious for someone more familiar with Ant, but for me it was a big hurdle I only discovered while (desperately) searching trought the Ant plugin configuration on my TeamCity server.