About

Glean is a framework of Ant scripts for generating feedback on a team's source code. Glean's goal is to make it possible to add feedback to your build cycle with as little pain as possible. The scripts drive a number of open-source tools and collect the resulting HTML for you to deploy to a project website or some other common team area. Add it at the end of a daily build cycle and it is a quick way to keep a number of feedback sources up to date and in one place.

There are any number of feedback tools that have Ant tasks, but applying them individually to your project build script usually involves copying some boilerplate Ant target from the tool's documentation and tweaking it a little for your project. Of course, even that doesn't help when you move on to the next project, other than now having a new place to copy and paste. And as you find more areas where another feedback tool would help, it adds an organizing challenge to the build script maintainer to figure out where to put the script for this new tool.

Glean is a collection of these boilerplate Ant targets, tied together with some common properties that describe your source project. The goal is to give you flexibility in a couple of different directions: to let you plug in different tools that analyze, document or measure your code, and to let you apply those tools to any source project you have.

If the set of tools that Glean scripts doesn't include one that you use, I can add it to the list to be worked on, or you can try adding it yourself. As the set of tools available to Java teams grows, I will be trying to keep up with the ones that are most valuable to people, so let me know if there are tools that you need.

Getting Started

Download and unpack the distribution anywhere you would like. The pre-requisites for running the basic scripts are a minimal Ant setup.

Java JDK 1.4
Ant 1.6.5

You will also need to download whichever tools you want Glean to run, along with any dependencies that they may have. The tools that Glean has scripts for are listed on the tools page. You can get them individually, or use an Ant script that comes with Glean that will download a number of them for you.

Running Glean involves telling it where your project is and what tools you want to run. The default set of tools will give you some of the staple feedback for a basic component project. To run Glean from the command-line, here are the common steps.

cd /path/to/glean
To let Glean know where you have feedback tools installed locally, there is a toolhome.properties file. To override the values defined here, create a toolhome.properties.local file with the specifics of your environment.
Create a properties file to describe you project by copying template/sample.feedback.properties to /path/to/myproject/myproject.feedback.properties

Edit this file to define where your source, bin and lib directories are. If the defaults work, you don't need to change anything. Here is what the properties file looks like for the Jakarta Commons-Lang project. You can find it in the sample directory.

#######################################################
#
#     Properties used for overall processing
#
#######################################################

# Define which tools you want feedback from
tool.pattern        = checkstyle,cpd,java2html14,javadoc,javancss,pmd

# Source download available at
# http://jakarta.apache.org/site/downloads/downloads_commons-lang.cgi
project.root        = ${user.home}/tools/commons-lang-2.2-src

# For this project, we can use the default layout
src.dir             = ${project.root}/src/java
bin.dir             = ${project.root}/target/classes
# This project doesn't have any other components it uses, so we define
# the lib directory as blank.
lib.dir             =

# The source for commons-lang 2.2 uses "enum" in its package name
# so the Javadoc engine needs to know that it is only 1.4-level code
source.level        = 1.4

src.project.name    = Jakarta Commons-Lang 2.2

Run Glean: ant -Dfeedback.properties=/path/to/myproject/myproject.feedback.properties

This will run all of the tools in the basic setup. The results will be simple HTML files, along with a summary page. From a browser, open the file /path/to/myproject/glean/index.html. The summary should look something like this.

See the documentation and tools pages for more complete instructions and descriptions of the properties the configure the different tools. Several types of project setups are shown on the samples page to give you an idea of what a project definition for Glean might look like.

Glean is distributed under an MIT License. Use it well, share it freely. I plan to continue improving it, so your feedback is appreciated. If you have ideas or scripts to share, feel free to post a note on the glean-code-users list, or contact me.