Using Glean

Glean needs to know only a few things to do most of its work:

the location of the project files (source, binary and libraries, if any)
which feedback tools to run

Being Ant scripts, all of the config is done using properties, and the easiest way to override properties for a project is usually to put them in a properties file. To tell Glean about your project, copy the template/sample.feedback.properties file to any place you like and edit it.

Running from the command line

You run Glean from the command line by running Ant from within the Glean directory and telling it where the properties file is.

cd /path/to/glean
ant -Dfeedback.properties=/path/to/myfeedback.properties

The output will be, by default, in your project's folder, under a glean folder. That location is one of the values you can override in your properties file. Browse to the index.html and you should see a summary page with links to each of the reports.

Running from another Ant build file

If you want to run Glean from your project build file, simply call it with an <ant> task, such as this.

    <property name="glean.home"  value="${user.home}/tools/glean"/>
    <property name="project.feedback.properties" 
                                 value="/path/to/my.feedback.properties"/>
    
    <target name="call-glean">
        <ant 
            antfile="${glean.home}/build.xml"
            inheritall="false"
            dir="${glean.home}">
            <property name="feedback.properties" 
                     value="${project.feedback.properties}"/>
        </ant>
    </target>

You can pass in any additional properties as subelements as well. This can be a useful way to share common settings, such as log or distribution directories, between your project build and Glean.

Running from CruiseControl

One way to incorporate project feedback into your development cycle is to have it generated automatically by a continuous integration server such as CruiseControl. Once you have it set up, you can have it publish to a common area and know that your metrics and documentation are always up to date.

A CruiseControl project configuration to run Glean could contain a couple of elements like this.

    <project name="my-project-feedback">
        ...        
        <ant
            buildfile="build.xml"
            antWorkingDir="${glean.home}"
            target="clean glean dist deploy"
            time="2300">
            <property name="feedback.properties"
                      value="/path/to/myproject.feedback.properties"/>
            <property name="glean.log.dir"   value="${log.dir}"/>
            <property name="glean.log.file"  value="${project.name}-feedback.log"/>
        </ant>
        
        <publishers>
            <artifactspublisher 
                file="${log.dir}/${project.name}-feedback.log"
                dest="build_artifacts/${project.name}"/>
        </publishers>
        ...
    </project>

With plugin preconfiguration and template projects, you can create a quick template that allows you to add new Glean projects with just a few lines.

Publishing The Results

The results will be generated as subdirectories under the root defined above, one subdirectory per tool. You can copy the files to a documentation area of a simple web server to be served up for your team.

There are a couple of targets available for handling the results as a WAR. The dist target will package all of them up as a WAR that can be deployed to a simple servlet engine. The deploy target will copy this WAR to the location defined by the report.deploy.dir property. Override this in your project's myproject.feedback.properties file to point to the deploy area of your application server or servlet engine.

Configuration

The basic setup of Glean assumes a simple project structure, but many other structures can be handled by adjusting properties that are used. The key properties are in the file feedback.properties. Rather than change the values there, though, you can follow the rules of Ant property overrides to change the values.

Glean will look for properties files at a number of different levels. This lets you decide how broadly you want the changes to apply for your setting. The list here is the order in which the properties are applied, so to override properties, define them at a place lower in the list.

Property settings	When to use them
specified on the command-line with `-Dproperty=value`	To define an override for this one invocation.
from file specified by `-Dfeedback.properties=/path/to/my.project.properties`	For settings specific to `myproject`. This is the preferred place to put your project settings.
`myproject/feedback.properties.local`	For general settings for Glean unique to `myproject` and a particular local install
`myproject/feedback.properties`	For general settings for Glean unique to `myproject`.
`${glean.home}/tool/(tool dir)/tool.override.properties.local`	For settings specific to this tool for this installation which should override default settings in `feedback.properties`.
`${glean.home}/tool/(tool dir)/tool.override.properties`	For settings specific to this tool. Override them in your project properties file or in `tool.override.properties.local`.
`${glean.home}/feedback.properties.local`	For settings general settings for Glean unique to a particular local install, and that you want to apply to all projects. This is the preferred place to put settings that you want to apply to all of your projects. For instance, you might define `tool.pattern` here so that all projects run the same set of scripts.
`${glean.home}/feedback.properties`	These are general settings for Glean that define the default behavior.
`${glean.home}/tool/(tool dir)/tool.extend.properties.local`	For settings specific to this tool for this installation which need to be defined in terms of properties set in `feedback.properties`.
`${glean.home}/tool/(tool dir)/tool.extend.properties`	For settings specific to this tool. Override them in your project properties file or in `tool.extend.properties.local`.

Properties

There are a number of common properties that Glean makes available to all scripts, such as the source file locations or the directory to hold tool output. There are also properties specific to individual scripts; those are described on the tools page.

You can override any of these values using one of the mechanisms described above. Having multiple levels of properties files can sometimes make setting values tricky, particular when they are defined in terms of other properties. In general, the less you need to depend on other properties in your overrides, the better off you will be.

Here is the contents of the feedback.properties file. This is the last properties file read, so it provides the default values when nothing else is specified.

#######################################################
#
#     Glean properties used for overall processing
#
#######################################################

# You can define the tools to run using an Ant pattern, either a '*' for all,
# or a comma-separated list of individual tools.
# For a list of available tools, look in ${glean.home}/tool, 
# or see http://jbrugge.com/glean/tools.html
# The default set of tools is just a starting point for basic feedback.
tool.pattern        = java2html14,javadoc,javancss,pmd

# Collector tools are those that use the output of the other tools to provide
# some type of aggregate feedback. These will run after the tools defined above.
# Examples of collector tools are 'qalab', 'xradar' and 'dashboard'.
# You can specify them using the same pattern style as for tool.pattern.
# To not run any of them, use the value "none".
collector.pattern   = none

# REMOVED: Use collector.pattern instead.
# Turn on/off Dashboard generation (requires Groovy)
create.dashboard    = false

# The base of the target project should be defined as an absolute path
project.root        = ${basedir}

# The base of the Glean scripts is used in order to refer to other elements
# of the framework
feedback.script.dir = ${basedir}

# The default name of the source project will be the last directory found in the
# project.root path. For example, if ${project.root} = /path/to/myproject, then
# ${src.project.name} will be 'myproject'.
# If you want a more descriptive name, define it here
#src.project.name   = MyProjectName

# Override this property to change the location of the output
gen.report.root     = ${project.root}/glean

# Override this property too change the location of the tool logs
glean.log.dir       = ${feedback.script.dir}/logs

# Properties defining the report summary page
project.report.stylesheet = ${feedback.script.dir}/feedback-summary.xsl
project.report.summary    = ${gen.report.root}/feedback-summary.xml
project.report.page       = ${gen.report.root}/index.html

# Define the styles available to all of the reports
report.css          = ${feedback.script.dir}/reports.css

# Timestamp format used for reports and logs
tool.timestamp.format     = MM-dd-yyyy hh:mm:ss a

# The output will be packaged into a WAR for easy deployment. Use this property
# to change where you want the WAR built or sent.
report.war.dir      = ${feedback.script.dir}/target

# You can also override the name of the packaged WAR. It is defined by default
# in the build script since it uses the src.project.name, which may not be defined
# at this point.
#report.war.file     = ${src.project.name}-feedback.war

# Override this property to change the location for WAR deployment 
report.deploy.dir   = ${tomcat.home}/webapps

# Document root for publishing to a simple web server
report.publish.dir  = ${gen.report.root}

# A project URL can be used to provide a link in the summary report 
project.url         = 

####################################################
#
#     Properties used by the individual reports
#
####################################################

# Default locations for source, binary, and tools
src.dir             = ${project.root}/src
bin.dir             = ${project.root}/bin
lib.dir             = ${project.root}/lib
resources.dir       = ${project.root}/src

# Default properties for an individual report.
gen.report.dir      = ${gen.report.root}/${ant.project.name}
report.name         = ${src.project.name}-${ant.project.name}-feedback
styled.report.name  = index
report.format       = xml
report.stylesheet   = ${tool.basedir}/${ant.project.name}.xsl
index.page          = ${styled.report.name}.html

# If your source is JDK 1.5-compliant, change this
# in your project's feedback.properties file.
source.level        = 1.4

# Point this to whichever Java-to-HTML tool you have chosen
# Certain tools can use this to point their results to specific
# source files (e.g. PMD and CPD)
src.link.prefix     = ../java2html14

# Default locations for test code
test.src.dir        = ${project.root}/test-src
test.bin.dir        = ${bin.dir}
test.lib.dir        = ${lib.dir}
test.resources.dir  = ${resources.dir}
test.report.dir     = ${project.root}/test-results
test.fork.mode      = true
test.results.pattern= TEST*.xml
unit.test.pattern   = **/*Test.class

# If your project needs other JARs or folders on the classpath for JUnit,
# define them with this property.06/25/2007 09:54:52 PM 
extra.test.path     =

# Certain tools need the 'dot' program from the GraphViz package
# (http://www.graphviz.org)
dot.exe             = /usr/bin/dot

report.debug        = false
# These are documentation properties for the tools. 
# Each tool script should override these.
tool.description    = 'NO DESCRIPTION AVAILABLE'
tool.min.jdk        = 1.4
tool.dependencies   = None
tool.url            =

tool.doc.fragment   = ${feedback.script.dir}/tool-table-fragment.html

Selecting Tools To Use

The tool.pattern property determines which tools are run. It's value is a standard Ant glob patterns. You can list as many patterns as you want, separated by commas. The default pattern is to run a small subset of the tools available.

If you were mostly interested in documentation, for example, you might define these reports.

tool.pattern=beandoc,doccheck,javadoc,java2html

If you wanted to run all of the tools available, you would just specify a '*'.

tool.pattern=*

Changing the report look

Many of the reports use a stylesheet called reports.css. Change this in any way that you want. It is based on a number of styles from the standard stylesheets that come with Ant.