One useful product measurement is system size. By measuring system size over time, one obtains a perspective on whether the system is gradually growing, gradually shrinking, or staying the same. Unexpected large changes in system size in a short period of time can indicate the need for quality assurance activities, for example.
StackyHack illustrates size measurement and analysis for two tools: LOCC and SCLC. LOCC is a grammar-based size counting tool that provides relatively detailed size metrics (such as the number of methods and their sizes) for a relatively small number of languages (currently, Java is the only language fully supported). SCLC is a token-based counting tool that provides relatively less detailed size metrics (basically, the number of commented and non-commented source lines of code), but for a relatively large number of languages (currently, over two dozen languages are supported.) This section describes how to measure StackyHack's size using LOCC; the next section describes this process using SCLC.
To install LOCC for use in StackyHack, download the .zip file containing the latest release from the LOCC home page into a directory such as "java-lib", and unzip it. Then, define an environment variable called LOCC_HOME to point to the distribution directory. For example, "c:\java-lib\locc-5.1". (Note that the file path should have no embedded spaces in it.)
Example 4.4, “locc.build.xml” shows the locc.build.xml file, which defines the Ant targets used to invoke the LOCC tool and the LOCC sensor.
Example 4.4. locc.build.xml
<project name="stackyhack.locc" default="locc">
<description>
Provides the LOCC tool and the Hackystat LOCC sensor.
</description>
<import file="build.xml"/>
<property name="locc.dir" location="${build.dir}/locc" />
<target name="locc" depends="locc.tool, locc.sensor" description="Runs LOCC, followed by the LOCC sensor."/>
<target name="locc.tool" depends="compile" description="Compute size data on the source code using LOCC.">
<!-- Verify that LOCC is installed. -->
<available file="${env.LOCC_HOME}/build/locc-all.jar" property="locc.available"/>
<fail unless="locc.available" message="Error: LOCC_HOME not set or locc.jar not found, indicating LOCC is not installed."/>
<taskdef name="locc" classname="csdl.locc.tools.ant.LOCCTaskdef" classpath="${env.LOCC_HOME}/build/locc-all.jar" />
<!-- Generate total size data in XML format. -->
<mkdir dir="${locc.dir}" />
<locc sizetype="javaline" outformat="xml" outfile="${locc.dir}/size.xml">
<fileset dir="${src.dir}" includes="**/*.java" />
</locc>
</target>
<target name="locc.sensor" description="Sends size data to Hackystat.">
<!-- Define the LOCC sensor taskdef, failing the build if the sensor is not installed. -->
<available classname="org.hackystat.sensor.locc.LoccSensor" property="locc.sensor.available"/>
<fail unless="locc.sensor.available" message="Error: Locc Sensor not installed."/>
<taskdef name="hacky-locc" classname="org.hackystat.sensor.locc.LoccSensor" />
<!-- Run the LOCC sensor and send the size data to Hackystat. Add a runTime attribute -->
<hacky-locc verbose="${hackystat.verbose.mode}" createRunTime="runTime">
<fileset file="${locc.dir}/size.xml/">
</hacky-locc>
</target>
</project>
The locc.build.xml file defines the <locc.tool> target to invoke LOCC and produce size data in XML format in the build/locc directory. The <locc.sensor> target reads in the size data produced by <locc.tool> and sends it to Hackystat. The <locc> target simply invokes both of these targets in sequence. The "runTime" attribute is added so that this FileMetric data is suitable for Daily Project Summary and Telemetry analyses.
Example 4.5, “Invoking the locc target” shows the output from running the <locc.tool> target to obtain size data.
Example 4.5. Invoking the locc target
C:\svn-csdl\StackyHack>ant -f locc.build.xml locc.tool
Buildfile: locc.build.xml
compile:
locc.tool:
[locc] **************************************
[locc] LOCC statistics for batch:
[locc] **************************************
[locc] Total files processed = 5
[locc] Total successful files = 5
[locc] Total files with errors = 0
[locc] **************************************
[locc] List of successfully processed files:
[locc] **************************************
[locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\ClearStack.java
[locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\EmptyStackException.java
[locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\Stack.java
[locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\TestClearStack.java
[locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\TestStack.java
[locc] **************************************
[locc] List of files containing errors:
[locc] **************************************
[locc] No files containing errors in this batch.
[locc] **************************************
BUILD SUCCESSFUL
Total time: 1 second
This command produces a file called size.xml in the build/locc directory containing the size data. Here's a sample of the size data collected for one class.
<file name="C:\svn-csdl\StackyHack\src\edu\hawaii\stack\ClearStack.java" className="ClearStack" size="1017" package="edu.hawaii.stack">
<metric name="lastMod" value="1133210030264" />
<metric name="loc" value="11" />
<metric name="sloc" value="11" />
<metric name="cloc" value="3" />
<metric name="numClasses" value="1" />
<metric name="wmc" value="2" />
<class name="ClearStack">
<metric name="loc" value="8" />
<metric name="cloc" value="3" />
<metric name="wmc" value="2" />
</class>
<metric name="methodSizes" value="3-3" />
</file>
After LOCC has been invoked to generate size data, the LOCC sensor can be invoked to read in the size.xml file produced by LOCC and send the resulting data to Hackystat as FileMetric sensor data.
To accomplish this, you must first install the LOCC sensor. General instructions on installing sensors are provided in Chapter 2, Client-side configuration: Tool sensor installation; instructions for specific sensors are provided in Chapter 26, Sensors. After installation, your hackyInstaller LOCC configuration window should look something like the screen image in Figure 4.2, “ HackyInstaller configuration screen for LOCC sensor ”.
Example 4.6, “locc.sensor invocation” illustrates the invocation of the LOCC sensor.
Example 4.6. locc.sensor invocation
C:\svn-csdl\StackyHack>ant -f locc.build.xml locc.sensor Buildfile: locc.build.xml locc.sensor: [hacky-locc] Sensor enabled?: YES [hacky-locc] Processing file: C:\svn-csdl\StackyHack\build\locc\size.xml [hacky-locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\ClearStack.java [hacky-locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\EmptyStackException.java [hacky-locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\Stack.java [hacky-locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\TestClearStack.java [hacky-locc] C:\svn-csdl\StackyHack\src\edu\hawaii\stack\TestStack.java [hacky-locc] Hackystat data on 5 LOCC files sent to http://hackystat.ics.hawaii.edu/ (2 secs.) BUILD SUCCESSFUL Total time: 2 seconds
Once you've invoked the sensor, you can verify that this data was received at the server by using the List Sensor Data command. Figure 4.3, “ List Sensor Data with StackyHack data ” illustrates what this page might look like after receiving the StackyHack data.
The LOCC sensor sends a separate FileMetric entry for each Java file in the StackyHack system; two classes are displayed in this screen image. Several kinds of structural information is provided for subsequent analysis. For example, ClearStack contains 14 total lines of code, of which 11 are source lines and three are comment lines.