Before you start...

Clanker has been built for Java 5 and above and there are two things to consider:

  • Clanker uses the Java compiler, located in the tools package (com.sun.tools.javac)
  • Clanker has been written using Java 5 syntax and supports Java 5 features, like Annotations and enum types.
The first of these aspects introduces also another important point to keep in mind when considering this framework: as the Javadoc documentation for the com.sun.tools.javac API states, [quote]This is NOT part of any API supported by Sun Microsystems. If you write code that depends on this, you do so at your own risk. This code and its internal interfaces are subject to change or deletion without notice.[/quote], so be aware that the API, the functionalities and the support may change without notice. On the other hand, by using the Java compiler as tool to parse Java sources, Clanker ensures that the results are compliant with the JSL. I also tested the analysis engine with Java 6 Beta and it worked fine, although I have to test the result engine with Java 6 final.

The technologies used by Clanker

SoftwareVersionWhere to find itNotes
log4j1.2.8http://logging.apache.org/log4j/docs/index.htmlLog4j is distributed under the Apache licence
tools5.0http://java.sun.com/This is the tools.jar file for JDK 5 which you'll find under %JAVA_HOME%/lib. tools.jar is distributed under the JRL licence
commons-jelly1.0http://jakarta.apache.org/commons/Commons-Jelly is distributed under the Apache licence
commons-lang1.1-devhttp://jakarta.apache.org/commons/Commons-Lang is distributed under the Apache licence
commons-logging1.1-devhttp://jakarta.apache.org/commons/Commons-Logging is distributed under the Apache licence
commons-collections3.1http://jakarta.apache.org/commons/Commons-Collections is distributed under the Apache licence
commons-beanutils1.7.0http://jakarta.apache.org/commons/Commons-Beanutils is distributed under the Apache licence
dom4j1.6http://www.jemos.co.uk/maven/repositoryDom4j is distributed under the Dom4j licence

Clanker uses also Maven 1.x as its building tool. In order to build Clanker, you will need to install Maven. Jemos offers a public Maven repository as regards the required dependencies, so that if you add the locations specified by the maven.repo.remote property in the build.properties file coming with the distribution to your list of remote repositories, you can download the above dependencies directly from Jemos.

Getting the source from a distribution

You can refer here to download Jemos Clanker.

The source directory structure

Back to the top

Regardless of the way you'll decide to get the source, the folder structure will appear as follows:

Top level structure:



The top level structure shows the following components:

  • analysis-engine folder. This is the folder containing the analysis engine code. For documentation related to the analysis engine, please click the subproject documentation on the left menu.
  • result-engine folder. This is the folder containing the result engine, i.e. the set of Jelly tags and Clanker utilities to make easy for a user to use the analysis tool. For documentation related to the result engine, please click the subproject documentation on the left menu.
  • apache, dom4j, JRL and Clanker licences, all in form of text files. Just a reminder: Clanker runs under the BSD licence
  • build.properties This file contains maven repository-related properties. Those properties are needed by CruiseControl in order to build the project. As the build process is concerned, you will need the maven.repo.remote property which, in addition to Ibiblio, contains links to the Maven remote repository on Jemos, where the build process will retrieve the dependencies needed by Clanker. More on how to build in the appropriate section.
  • clanker.properties This file is used by the unit tests in order to locate the Java source to analyze. It contains only one property (jemos-clanker.src.dir) which should point to the location where the Java source files for the unit tests are located.
  • jelly-config.xml This file contains the list of Jelly Tags used by the result-engine. You can create your own tags and add their declaration in this file. At runtime, the Clanker Jelly library will automatically register with the Jelly engine all the tags declared in this file.
  • maven.xml, project.xml Those are the files used by Maven to build Jemos Clanker.
  • project.properties This file contains the multiproject properties and mainly properties which have to do with the publishing process.

Analysis Engine structure:



The Analysis Engine structure shows the following components:

  • src/conf Here you will find the log4j.properties file used to configure log4j. This file is used to set the debugging level when running the unit tests. If the logging level is set to DEBUG the unit test logging will show a great deal of information, especially the printout of the structure created by the analysis engine; if you don't want to see extensive logging, just set the logging level to INFO (the default).
  • src/java Under this folder you'll find the analysis-engine source code. For more information on the analysis-engine, please refer to the analysis-engine documentation.
  • src/test Under this folder you'll find the analysis-engine unit tests source code. For more information on the analysis-engine, please refer to the analysis-engine documentation.

Result Engine structure:



The Result Engine structure shows the following components:

  • src/conf Here you will find the log4j.properties file used to configure log4j. This file is used to set the debugging level when running the unit tests.
  • src/java Under this folder you'll find the result-engine source code. For more information on the result-engine, please refer to the result-engine documentation.
  • src/test Under this folder you'll find the result-engine unit tests source code. For more information on the result-engine, please refer to the result-engine documentation.

Building Jemos Clanker

Back to the top

In order to build Jemos Clanker you will need the following pre-requisites:

  • Java 5 (Clanker has been built with JDK 1.5.0_06 and it has not been tested with previous versions of the JDK). Clanker is not backwards compatible (that means it cannot be built using Java 2 or earlier versions)
  • Maven 1.x (I'm using Maven 1.0.2)

Those are the steps in order to build Clanker:

  • Downloads and install the source code. The root folder where Clanker has been installed will be referred to as JEMOS_CLANKER_HOME
  • Define an environment variable JEMOS_CLANKER_HOME pointing to the root installation folder. This environment variable is used to locate some of the files needed by Clanker: the unit test source files and the jelly-config.xml file used by the Result engine in order to locate the configuration file which contains the declaration of the Jelly tags used by Clanker.
  • If you already have a build.properties file under {user.home} ({user.home} in Windows points to C:\Documents and Settings\user-name) and you have defined a maven.repo.remote property there, ensure that the following remote repository be added to your list: http://www.jemos.co.uk/maven/repository and be sure that the maven local repository property defined in JEMOS_CLANKER_HOME/build.properties corresponds to the one (if any) that you defined under {user.home}/build.properties. If you haven't got a {user.home}/build.properties file, the one under JEMOS_CLANKER_HOME shall be enough to build the application
  • Open a command window and point to JEMOS_CLANKER_HOME
  • Type 
    	      maven multiproject:install
    This will build all Jemos Clanker subprojects (analysis and result engines). The artifacts will be placed under {maven.home.local}/repository/jemos-clanker. Subsequent builds can be obtained by typing the following: 

    	      maven -o multiproject:clean multiproject:install
    The -o option tells Maven to build using the local dependencies, rather than trying to go on the internet each time (this is useful if you are building a SNAPSHOT version).

SourceForge.net Logo