instantiations.metrics Ant Task

The instantiations.metrics Ant task analyzes the resources in one or more projects and computes the values of one or more code metrics. It is based on the Metrics feature found in CodePro AnalytiX™, an automated software quality tool from Instantiations, Inc.

The set of projects to be measured is specified using nested fileset elements. Specifics on how to use these elements is given below.

The set of metrics to be computed are represented by an metric set. All of the information about which resources to measure within each project, which metric set to use, and other parameters controlling the metrics computation can be configured as attributes and nested elements in the instantiations.metrics Ant task.

Installation

Download and unzip CodePro Server for Ant in a directory of your choice (e.g. /CodeProServer). To use the instantiations.metrics Ant task you must add the following lines near the top of your Ant build script...

<property name="CodeProServer.install.dir" location="install-dir"/>
<import file="${CodeProServer.install.dir}/ant-tasks.xml" /> ...

where install-dir is the directory into which you installed CodePro Server for Ant.

Attributes

The following is a list of the attributes supported for the instantiations.metrics task.

Attribute Description Required
buildNumber The build number to be associated with the results of the analysis. This attribute is only useful if the results are to be stored in a data store. See the dataStore attribute for more information. No
classpath The classpath used for resources that exist outside of the projects contained by the current Eclipse workspace. No
configurationDir The location of the Eclipse configuration directory used when computing the metrics. If not specified, then the configuration defaults to a newly created directory within the temporary directory. This directory will be deleted and recreated from <install-dir>/eclipse/configuration-backup.zip as necessary. No
dataStore The directory containing the data store. If this attribute is specified then the results of the metrics computation will be saved in the data store so that they can be used by the instantiations.dashboard task to create a code quality dashboard. No
eclipseDir The directory containing the installation of Eclipse that should be used to compute the metrics. If not specified this attribute will default to ${CodeProServer.install.dir}/eclipse. No
failOnError A flag indicating whether the build should fail if an error prevents the metrics from being computed. If not specified, then defaults to true. No
jreDir The installation directory for the JRE used to run Eclipse. No
metricSetFile The absolute or relative path to the file that contains the metric set to be used. If the metricSetName attribute is specified (see above) then the metric set located in the specified file with the specified name is used, otherwise the first metric set in the file is used. If the metricSetFile attribute is not specified, then a metric set from the workspace is used. Either the export preferences command or the export button on the metrics preference page can be used to generate a file containing metric sets. No
metricSetName The name of the metric set that will be used to compute metrics. If the metricSetFile attribute is specified (see below) then the named metric set in the specified file is used, otherwise the named metric set in the workspace is used. If no metric set name is specified then either the first metric set in the file or the default metric set in the workspace is used depending upon whether or not the metricSetFile attribute is specified. No
projectName The name of the project containing the files for which metrics were computed. This attribute is only useful if the results are to be stored in a data store. See the dataStore attribute for more information. No
storageLocation

A designation of the storage location in which the metric result set will be stored. It can be either workspace (the default) or project: followed by the name of a project. Storage locations are discussed here.

No
tempDir

The absolute path of the temporary directory that can be used by this task. If not specified this attribute will default to the system temp directory.

No
workspaceDir The location of the Eclipse workspace directory used when computing the metrics. If not specified, then the configuration defaults to a newly created directory within the temporary directory. No

Nested Elements

The following elements can be nested within the instantiations.metric task.

<metricSet>

The metricSet element is used to define a metric set to be used when computing metrics. If multiple metric sets are specified then they are all used. It has two attributes:

file
The absolute or relative path to the file that contains the metric set to be used. If the name attribute is specified (see below) then the metric set located in the specified file with the specified name is used, otherwise the first metric set in the file is used. If the file attribute is not specified, then a metric set from the workspace is used. Either the export preferences command or the export button on the metrics preference page can be used to generate a file containing metric sets.
name
The name of the metric set that will be used to compute metrics. If the file attribute is specified (see above) then the named metric set in the specified file is used, otherwise the named metric set in the workspace is used. If no metric set name is specified then either the first metric set in the file or the default metric set in the workspace is used depending upon whether or not the file attribute is specified.

<classpathVariable>

The classpathVariable element is used to define a classpath variable within the (possibly newly created) Eclipse workspace. It has two attributes:

name
The name of the classpath variable
value
The value of the classpath variable

<fileset>

The standard Ant fileset structure is used to specify which projects metrics are to be computed for. The directory specified should be the root directory of the project (the directory containing the .project file).

If the code to be audited is not in an Eclipse project, the directory attribute should reference the root of the source folder containing the source to be audited (typically src).

Note: only the dir attribute of the fileset element is used; all other attributes and children will be ignored. In particular, that means that inclusion and exclusion patterns cannot be used to include only a portion of a directory.

<report>

The report element is used to generate a report based on the results of the metrics computation. Multiple reports will be generated if the report element is included multiple times.

Examples

The following examples show how to use the instantiations.metrics task in a variety of ways.

Compute Metrics for an Existing Workspace

Compute Metrics for Existing Projects