= Cowley - Making Coding against IBM's Rational Team Concert Easier = This project is a collection of libraries with the combined goal of making use of [http://jazz.net IBM's Rational Team Concert Platform] (RTC) easier. Each library has been produced as a result of an itch being scratched. Currently there are only two sub projects: * '''jazz-proxy-common''' - a wrapped, simpler-to-use API for RTC SCM and Build Engine (RTC platform version 2.0.0.X) * '''jazz-hudson-scm''' - a plugin for the [http://hudson.dev.java.net Hudson] build engine which provides two-way integration with RTC Builds = Quickstart = These steps are for when you just want to get the current Hudson plugin and use it. Unfortunately you can't just download some pre packaged HPI or JAR from this project's download page as we need a bunch of dependencies from the IBM RTC Build Toolkit (which are free but licenced). The steps below show you how to get from source + libraries to a working HPI. Enjoy. == Installing the RTC Build Toolkit Dependencies into your Maven Repository == The current version of RTC which is supported is 2.0.0.0, though it is likely that other 2.0.0.X versions will also work, they just haven't been tested fully yet. (Some files are in place for 2.0.0.2 but I still need to test everything fully.) Consequently, in order to use any of the libraries, you will need to do a little pre-work. # Install and configure Maven 2.X and Java 1.6.X so that running "mvn -version" works from your command line. # Download and unzip the latest RTC Build System Toolkit ([https://jazz.net/downloads/rational-team-concert/releases/2.0/RTC-ExpressC-BuildSystemToolkit-2.0-Win.zip Windows]) / ([https://jazz.net/downloads/rational-team-concert/releases/2.0/RTC-ExpressC-BuildSystemToolkit-2.0-Linux.zip Linux]) (registration required). # Check out the '''[http://kenai.com/projects/cowley/sources/source-code-repository/show jazz-proxy-common]''' maven project. # Open the "jazz-proxy-common/src/main/resources/mvn_install_build_toolkit_jars-jazz_2.0.bat/.sh file" and edit the "BUILD_ENGINE_PLUGIN_DIR" variable (unless you've followed the defaults from these instructions) so it points to the "plugins" dierctory inside the Build System Toolkit you just unzipped. # Run the mvn_install_build_toolkit_jars-jazz_2.0.bat/.sh file. (This will install into your personal maven repository the jars you need to compile, test and run the jazz-proxy-common code.) == Compile the jazz-proxy-common Project == Once you have installed the RTC Build Toolkit Dependencies into your Local Maven Repository you can compile the jazz-proxy-common project. # Run "mvn install" in the jazz-proxy-common "directory" (NOTE: if you want to run the unit tests, you need to enable them explicitly in the pom. Many require manual creation of Build Requests through the RTC Eclipse client. See the instructions for developing the Hudson below if you want to do this.) This will create a jazz-proxy-common jar file and add it to your local maven repository in the com\capgemini\jazz-proxy-common\1.0.1 directory (or later if there has been an updated version). == Compiling your Hudson RTC Plugin == Once you have the jazz-proxy-common safely compiled and installed in your local maven repository you can compile and package the Hudson RTC plugin. # Check out the '''[http://kenai.com/projects/cowley/sources/source-code-repository/show jazz-hudson-scm]''' maven project. # Add the following to your maven settings.xml file: <pluginGroups> <pluginGroup>org.jvnet.hudson.tools</pluginGroup> </pluginGroups> # Package the plugin with the command "mvn install" NOTE: If you want to see it working straight away; # Compile and then run the Jazz Hudson Plugin with the command: mvn hpi:run (Don't worry if this takes ages downloading all the dependencies. There are a ''lot''.) # Open up your browser and navigate to http://localhost:8080. You should see the Hudson main screen. == Adding the Hudson RTC Plugin to your Hudson Server == Once you have your Hudson RTC Plugin, you can install # If it isn't running already, start up your Hudson server # Select the "Manage Hudson" link on the left hand side of the main page # On the next screen, select the "Manage Plugins", and when this screen appears select the "Advanced" tab # Manually upload the plugin HPI you created earlier. = Configuring a RTC/Hudson Build Job = Once you've installed the Hudson RTC plugin into your Hudson server you can start creating jobs for yourself. Because RTC is a development platform, providing build support of its own in addition to SCM facilities, there is a bit more configuration to do for an RTC build job that there is for other Hudson builds. The basic aim is to set up both the RTC Build and Hudson job so that both have the ablilty to keep in synch. We'll start with the RTC end. (Note: These instructions assume you already know how to setup and administer RTC Builds. If you need more information, consult the [http://publib.boulder.ibm.com/infocenter/rtc/v2r0m0/index.jsp RTC documentation].) == Setting up RTC == # First you should create a new RTC user who will run your builds (build/build) with an RTC Build System Licence. # Next create a repository workspace for this build user from the stream you wish to build called "''Your Job Name'' Build Workspace", making sure it contains all the Components you will need. Also ensure it only has a single flow target of the Stream you created it from. (When you create it, it'll belong to the user you are logged in as. Just change it (remembering to click "save")) Don't load it. # Create a new Build Engine called "hudson". # Create a new Build Definition with the ID: "''You Job Name''", using the "Generic" template and "General", "Properties" and "Schedule" options enabled. (Note: a "Hudson" Build Definition Template Eclipse plugin needs to be created.) # Set the Build Engine for the new Build Definition as "hudson". Next you will set up the Hudson end of the build. == Creating and Configuring the Hudson Job == # Open the Hudson Server main page. # Click the "New Job" link. # Enter a value for the "Job Name". (It is recommended that you make this the same as the value you entered for the RTC Build Definition above.) # Select the "Build a free-style software project" radio button # Click "OK". # Select the "Rational Team Concert" radio button in the "Source Code Management" section. # Enter values in the fields which appear: ## Repository URL: This is the URL for your project's Repository. Typically it is something like http://[hostname]:9443/[projectname] ## Build Workspace: This is the workspace you have created for the builds to run from. Jazz best practice suggests this is a dedicated workspace. ## Build Engine ID: This is the ID you have given this build engine when configuring your Jazz Build. It is also shown as the name which is displayed against your chosen Build Engine in RTC. ## Build Definition ID: This is the ID you gave the build definition when configuring your Jazz Build. It is also shown as the name which is displayed against your chosen Build deinition in RTC. Note: Ensure that the Build definition you are selecting has the box ticked for the Build Engine you are also specifiying. ## Build User's Username: This is the username for the user you have set up in Jazz to perform your builds. Jazz best practice suggests that this is a dedicated user. ## Build User's Password: This is the password for the user you have set up in Jazz to perform your builds. Jazz best practice suggests that this is a dedicated user. ## Build Label Prefix: This is the prefix which will be added to the build label when updating the RTC build result. ## SCM Components to Build: Provide a comma-seperated list of the Jazz Components that this build is concerned with. E.g. myapp-master-build, myapp-core. # Choose a type of Build trigger if you want one in the "Build Triggers" Section. (You don't need one if you are always going to start builds manually.) # Add build steps as appropriate to build your code in the "Build" section. # Select the "RTC Build Result Notifier" checkbox in the "Post Build Actions" section. # Click the "Save" button at the bottom of the page. == Running the First Build == You can now run your first build. Remember that you need to have your RTC server running. You can start the build manually from either the Hudson dashboard (the "schedule a build" clock and green arrow at the far right of each job) or the build details page (the "Build Now" button on the left hand side). Once you've started the build, click on the running build, and then click on the "Console Output" button to see the build as it runs. If everything is OK, it should run to completion. You can confirm is has all worked by opening up your RTC client, double clicking on the Build Definition which corresponds to the Job you just ran. This will list all the build results for that build. You should see the Hudson build which just ran listed at the top. if you double click it you should see the detailed build result and the build log from Hudson in the "Links" tab. = Notes for the careful user = * Shut down Hudson nicely with a "prepare for shutdown". If you don't do this a mess can get left behind by the plugin which I haven't been able to get to the bottom of yet.