How to Configure the XRadar with Ant

Setting up the XRadar for a project is a relatively simple task with ant. It will probably take you less than a couple of hours to set up your project with ant. In this case you will get the analysis for the current build on the system. Setting up XRadar Dynamics, might take a litte longer since it involves having the source and builds of previous system releases. Once you have that the task of setting XRadar Dynamics up is fairly simple.

To get the XRadar properly installed, you first need to do some mandatory downloads and installs, second set some common properties and do some simple configs, and finally running the testproject to see that everything is working smoothely.

Prerequisites

Before you begin installing the XRadar, the following prerequisites are mandatory:

Necessary common configuration

  • Unzip the XRadar. The directory where xradar is unzipped is hereafter called XRADAR_HOME.
Set up XRADAR_HOME/xradar.properties with the following values.
Setup Property Description Commands
ANT.HOME XRadar uses the environement variable to find its Ant, you most likely have this variable set is already using ant. On windows : set ANT_HOME="path/to/ant", on *nix : export ANT_HOME="/path/to/ant"
Here, that's it. XRadar is configurer. However, this is not easy, as now we have to configure it to analyse a project. The following walkthrough will help you to set and run the 'testproject', a dummy project included in the XRadar release.

Update XRADAR_HOME/testproject/user.properties with the follow value.

Setup Property Description
xradar.home Set to the xradar home directory.

Ant Configurations

XRadar is a XSLT product based, and it uses Ant for the transformation, which means XRadar is basicly a bunch of xsl script triggered by Ant. In order to run the XRadar properly, you need to set properly your Ant environement.

  1. File encoding: First of all, you should set properly your encoding using the proper jvm parameter: 
                    	# For windows
                    ANT_OPTS=-Dfile.encoding=ISO-8859-1
                    # For *nix
                    export ANT_OPTS="-Dfile.encoding=UTF-8"
    The file encoding used here is the default for each platform. If you are using a linux box with the ISO-8858-1 encoding or a Windows box with UTF-8 ( is there such a thing ?), please adapt this configuration, and used the proprer setting.
  2. Memory usage: As it does a LOT of XSLT transformation, over A LOT of source code, XRadar ( as some of the tools it uses) can be quite memory consuming. To avoid a always frustrating "Java.OutOfMemory", you should add as much memory as you can ( 512Mo is in most of the case just fine, more will speed a bit the process): 
                    	# For windows
                    ANT_OPTS=-Dfile.encoding=ISO-8859-1 -Xmx512M
                    # For *nix
                    export ANT_OPTS="-Dfile.encoding=UTF-8 -Xmx512M"
  3. Endorsed librairies: There used to be problems while running the XRadar in Java 5. This was mainly due to the use of some deprecated xslt or XPath grammar. XRadar runs (almost) fine with JDK 5 now. We say "almost" because if you use it a medium sized or a large project, you'll run into a "No more DTM IDs are available" problem. This is a bug in the xalan ship in sun's JDK5. To avoid it, we have placed xalan-2.7.0 with it two pals xercesImpl-2.7.0.jar and the serializer-2.7.0.jar in the XRADAR_HOME/lib/endorsed directory. To override the JDK's default librairies you just have to set the proper parameter: 
    	                	# For windows
	                    ANT_OPTS=-Dfile.encoding=ISO-8859-1 -Djava.endorsed.dirs=XRADAR_HOME/lib/endorsed/ -Xmx512M
	                    # For *nix
	                    export ANT_OPTS="-Dfile.encoding=UTF-8 -Djava.endorsed.dirs=XRADAR_HOME/lib/endorsed/ -Xmx512M"
  4. Error messages and debug info: As it is always possible to encounter problem, you should also set the language parameter to be english, as english error messages are always more "googlable": 
                    	# For windows
                    ANT_OPTS=-Dfile.encoding=ISO-8859-1 -Duser.language=en -Djava.endorsed.dirs=XRADAR_HOME/lib/endorsed/ -Xmx512M
                    # For *nix
                    export ANT_OPTS="-Dfile.encoding=UTF-8 -Duser.language=en -Djava.endorsed.dirs=XRADAR_HOME/lib/endorsed/ -Xmx512M"
    Also note that if an xslt transformation encounter a problem, Ant may not systematicly crash, so it important, at least the first times, to the logging messages as warning appear in a "successfull" target. All of this is advice to help you, but you'll probably won't need it !

All of this will ensure that when you run ant, the needed operations will get the right encoding information. Furthermore, the Xmx preoperty ensures that you have enough memory to run the XRadar (works with 5000 classes). Notice that if you have problems with a even larger project, this propery may be set higher.

Running the test project

After having done the previous steps, you are ready to see if the configuration works. The testproject can also be used as a template for how you may implement analysis on your own project.

In your console, go to the XRADAR_HOME directory and type: 

XRADAR_HOME$ cd testproject
XRADAR_HOME/testproject$ ant

On a modern PC, the task will take a few minutes ( 1 to 5), and should run successfully. If not, there is something wrong in the configuration (you should go back and see if there is something that you have forgotten).The script will build 4 test projects and analyse them all. The XRadar Statics analysis of these projects can be found in XRADAR_HOME/release[1..4]/docs/index.html on your system. The XRadar Dynamics analysis for them all can be found in XRADAR_HOME/dynamics/docs/index.html. Enjoy!

Next Steps

After these initial steps, you may continue with the XRadar setup for your project through XRadar Statics Installation and XRadar Dynamics Installation . We do recommend that you do try to install the Unit test and coverage features so that you can see the XRadar's full potentional, however, Cobertura is known to be quite buggy. We plan to have it replaced by the new Emma project as soon as possible. Anyway, if you're interested in this feature, read on!

Unit Test and Coverage Configuraton

Running the testproject with junit

If you want to integrate JUnit or JCoverage into the XRadar, that is possible as well. JUnit is the first thing recommended to integrate. The solution is fairly simple. From $XRADAR_HOME/testproject/lib, copy junit.jar over to the $ANT_HOME/lib directory.

Then, in your console, go to the $XRADAR_HOME/testproject directory and type: 

            # On windows
            export ANT_OPTS="-Dinclude.junit=true"
			$XRADAR_HOME\testproject$ ant
            # On *nix
            $XRADAR_HOME/testproject$ ant -Dinclude.junit=true

The system will now build the unit tests and run them against the testproject. A report will finally be formatted and integrated into the XRadar. The prosess will take some time, but afterwards, you will see unit test metrics in both XRadar reports.

Running the testproject with junit and cobertura coverage tool

The second part that you may want to integrate is Cobertura test coverage tool. The solution is relatively simple, but since the XRadar is licenced under a standard BSD licence, and Cobertura runs under GPL, we cannot distribute it with the XRadar. See instructions below.

What you need to do is to get a full cobertura installation from cobertura site . The installation will typically come in a zip file. All jar-files included in the zip, you need to put in the $XRADAR_HOME/testproject/lib directory.

Assuming you have done the necessary installion of junit as described in the previos section you are now ready to go. In your console, go to the $XRADAR_HOME/testproject directory and type: 

		        # On windows
		        export ANT_OPTS="-Dinclude.junit=true -Dinclude.cobertura=true"
				$XRADAR_HOME\testproject$ ant
		        # On *nix
				$XRADAR_HOME$/testproject ant -Dinclude.junit=true -Dinclude.cobertura=true

The system will now instument the classes of the testproject for coverage. The the system will build the unit tests and run them agains the testproject. A junit-report and cobertura-report will finally be formatted and integrated into the XRadar.

Optional: Running the testproject with junit and jcoverage test coverage tool

An optional second part that you may want to integrate is JCoverage as a replacement to cobertura. Still, Cobertura is based on the GPL version og JCoverage, and seems much more stable. Hence we recommend to only use JCoverage if you are using the commersial version. Jcoverage is a commercial company but has an open source version of its tool. The problem is that the xml-stream from the open source version is not working properly, but you can get a trial version of JCoverage-plus from their site if you register some information. In the future, let's hope they fix their bug. The following solution should be similar for both versions.

What you need to do is to get a full jcoverage installation from jcoverage . The installation will typically come in a zip file. All jar-files included in the zip, you need to put in the $XRADAR_HOME/testproject/lib directory. For jcoverage-plus, you will also need to put the licence file in the same directory.

Assuming you have done the necessary installion of junit as described in the previos section you are now ready to go. In your console, go to the $XRADAR_HOME/testproject directory and type: 

$XRADAR_HOME$/testproject ant statics_all dynamics_all -Dinclude.junit=true -Dinclude.jcoverage=true

The system will now instument the classes of the testproject for coverage. The the system will build the unit tests and run them agains the testproject. A junit-report and jcoverage-report will finally be formatted and integrated into the XRadar.