AHrg Documentation

 SourceForge.net Logo

Contents

  1. Introduction
  2. Installation
  3. Configuration
  4. Developer Information
    1. Guide to Writing Your Own Adapters
    2. AHrg Internals and Design

Introduction

Agile development began in the late 1990's as a collaboration of several emerging methodologies. Each of these methodologies, while different, all emphasized close contact between the customer and the development team, frequent and iterative delivery of a working, even if not fully functional, program, and a process that allowed requirement shift to be handled with ease. The term 'Agile' was coined at a workshop in 2001 as an umbrella term for the software development methodologies represented at the workshop. The similarities between these methods were discussed and written down as part of the Manifesto for Agile Software Development. The most important part of the manifesto is a list of shared values:

[...] Through this work we have come to value:

Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan

That is, while there is value in the items on
the right, we value the items on the left more.

Even though Agile development values 'Individuals and Interactions over processes and tools' there is still a need for tools in the development process. The ability to automate the building and testing of a program under development is a crucial part of the Agile development process. Since the Agile process emphasizes frequent builds, it would be a burden on the development team to have to manually organize and execute a build even on a daily basis. Since builds are happening so frequently it is equally important to be able to test as often as the builds happen. This way bugs that are introduced from one build to another are found quickly, before they become compounded into the program and become a pain to resolve. Finally, having metric information for every single build fits well into the Agile process as it can help guide the team's direction as they adapt over the life of their project. The metics may also raise software quality issues throughout the development of the project instead of only worrying about software quality in the late stages of development.

Named AHrg (AH for AgileHelper and rg for the amount of times I made that exclamation durring development) the tool combines a continuous build tool with testing and metrics capabilities. This is accomplished through a plugin architechture that allows existing tools that offered the required functionality to be linked together.

Installation Instructions

This sections details the steps involved in installing AHrg. Before installing there are several pieces of software required for AHrg to function properly. There is no need, however, to be daunted as installing these requirements is a straightforward process. If you need help at any point durring installation, you can send me an email at gnugy AT users.sourceforge DOT net.

The following pieces of software are required for AHrg to function properly:

Actuall installation of AHrg is as simple as deploying the ahrg.war file (found in the dist directory) to your servlet container.

Configuration Instructions

This section provides details on how to properly configure an AHrg project to use the AnthillAdapter as it's continuous integration tool, the JUnitTestRunner as it's test suite and JCSC for providing metric information.

The first thing you need to do is set up your project properly. The AnthillAdapter expects a couple of things. First of all, it expects to find an Ant build file called build.xml in your project's root directory. AHrg makes this build file responsible for moving the project's source to the notify directory so that the project can be tested and have metrics applied to it whenever it is built. To do this create a build.xml in your project's root with the following basic structure:

<project name="YourProjectsName" default="all" basedir=".">
<description>Sample Build File for AHrg</description>

<!-- Optional task definitions -->
<taskdef name="jcsc" classpath="d:\Ahrg-install\jcsc\lib\jcsc.jar" classname="rj.tools.jcsc.ant.JCSCTask"/>

<!-- set global properties for this build -->
...
<property name="publishLocation" location="ahrg_home/notify/projectName"/>
...

<target name="all" depends="AHrgNotifyPublish,AHrgMetrics">
<!-- Built the project -->
<echo>Building Project</echo>
</target>

<target name="AHrgNotifyPublish" depends="compile">
<!-- Copy the source files to ahrg_home/notify/projectName/ -->
<mkdir dir="${publishLocation}"/>
<copy todir="${publishLocation}">
<fileset dir="${srcLocation}"/>
</copy>
</target>

<target name="AHrgMetrics" depends="compile">
Ommited, included later in section
</target>

...
Other targets such as making a Jar file etc.
...

<target name="compile" depends="init" description="compile the source">
<!-- Compile the java code from ${src} into ${build} -->
Tasks to compile your code here
</target>

<target name="init">
Initialize the build process here.
</target>
</project>

The parts that need editing have been bolded. A sample build file can be found in the top level of the TestApp directory.

The AnthillAdapter also expects to find a file called version.txt in the top level of your project. This file simply contains a version number for you project. Anthill will increment this number everytime if performs a build. A sample version.txt file can be found in the top level of the TestApp directory.

In order for the JCSC metric to be properly applied to your project you need to modify your project's build.xml file to run the JCSC task and move it's results to ahrg_home/projects/projectName/JCSC. To do this modify your build.xml as follows:

<project name="YourProjectsName" default="all" basedir=".">
<description>Sample Build File for AHrg</description>

<!-- Optional task definitions -->
<taskdef name="jcsc" classpath="d:\Ahrg-install\jcsc\lib\jcsc.jar" classname="rj.tools.jcsc.ant.JCSCTask"/>

<!-- set global properties for this build -->
...
<property name="metricsLocation" location="ahrg_home/metrics/JCSC/projectName"/>
...

<!-- Project's build targets -->
<target name="all" depends="AHrgNotifyPublish,AHrgMetrics">
<!-- Built the project -->
<echo>Building Project</echo>
</target>

<!-- Notify target is omitted -->

<target name="AHrgMetrics" depends="compile">
<!-- Run the JCSC Ant task on the project's source -->
<jcsc rules="path to rules file"
destdir="${metricsLocation}"
copyassociatedfiles="true"
jcschome="ahrg_home/jcsc">

<fileset dir="${srcLocation}" includes="**\*.java"/>
</jcsc>
</target>
<!-- The rest of the targets have been omitted -->
...

</project>

The sections that need editing have been bolded. Some of the file has been omitted because it is the same as the one above. Please note that JCSC requires the paths you provide it to be fully qualified or else they will not work. For more information on using JCSC please refer to the JCSC Homepage.

Now that your project is set up to work with AHrg, you are ready to set up AHrg to build your project.

  1. Using your web browser navigate to http://ahrg_address:8080/AHrg where ahrg_address is the address of the machine where your Servlet Container is running. This assumes a Tomcat installation running on it's default port 8080.
  2. If this is the first time anyone has accessed AHrg, you will be directed to specify the installation directory of AHrg. This is a fully qualified path to the location of the Ahrg-install directory on the host machine. Please note that if after entering the directory you are told it is invalid, make sure that there is a file named AHrgInstallDir in the ahrg_home/conf directory. This file is used by the program to verify that this is indeed an AHrg directory. If the file is not there create it. It does not have to contain anything.
  3. After specifying ahrg_home you will be taken to the main screen. To create a new project click on the Create a Project link. This will take you to the Create a Project screen. Enter the following information: Now click create.
  4. After clicking create you arrive at the Adapter Configuration Screen. Enter the following information: After entering your information, click done.
  5. You will now return to the main screen where your new project should show up. To test that everything is set up properly, click the Build link next to your project. Once the project has completed building you can view the build report by clicking on the View Report link next to your project.

Developer Information

This section contains information pertinent to those who wish to help with the development of AHrg. It is divided into two parts. The first part is a guide to writing an AHrg adapter for the continuous integration tool, testing suite or metric of your desire. It first takes a brief overview of the structure of AHrg, then guides the reader through the steps of writing each kind of adapter. The second part of this section