instantiations.audit Ant Task
The instantiations.audit Ant task analyzes the resources in
one or more projects for conformance to a set of coding standards. It is
based on the Code Audit feature found in CodePro AnalytiX™,
an automated software quality tool from
Instantiations, Inc.
The set of projects to be audited is specified using nested
fileset elements. Specifics on how to use these elements is
given below.
The coding standards are represented by an
audit rule set.
All of the information about which resources to audit within each project,
which audit rule set to use, and other parameters controlling the analysis
can be configured in the
project's
.audit file or as attributes and nested elements
in the instantiations.audit Ant task.
Download and unzip CodePro Server for Ant in a directory of your choice
(e.g. /CodeProServer). To use the instantiations.audit
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.audit task.
| Attribute |
Description |
Required |
| auditRuleSetFile |
The absolute or relative path to the file that contains the
audit rule set to be used. If the auditRuleSetName
attribute is specified (see above) then the audit rule set located
in the specified file with the specified name is used, otherwise
the first audit rule set in the file is used. If the
auditRuleSetFile attribute is not specified, then an
audit rule set from the workspace is used. Either the
export
preferences command or the
export
button on the audit preference page can be used to generate a
file containing audit rule sets.
|
No |
| auditRuleSetName |
The name of the
audit rule set that will be used to generate audit violations. If the
auditRuleSetFile attribute is specified (see below)
then the named audit rule set in the specified file is used,
otherwise the named audit rule set in the workspace is used. If no
audit rule set name is specified then either the first audit rule
set in the file or the default audit rule set in the workspace is
used depending upon whether or not the auditRuleSetFile
attribute is specified.
|
No |
| 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
performing the analysis. 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 audit will be saved in the data
store so that they can be used by the
instantiations.dashboard
task to create a code quality dashboard.
Also, if the dataStore attribute is specified, the projectName attribute must be specified. |
No |
| eclipseDir |
The directory containing the installation of Eclipse that should be
used to run the audit. 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 code audit from being completed. If not specified, then defaults
to true.
|
No |
| jreDir |
The installation directory for the JRE used to run Eclipse.
|
No |
| projectName |
The name of the project containing the files that were audited.
This attribute must be specified if the results are to be stored in a
data store or if the code being audited is not in an Eclipse project. See the dataStore attribute for
more information.
|
No |
| resultProperty |
The base name used to compose the names of properties that will be
given values after an audit has been run. The following is a list
of the properties that will be set (where "result" is assumed to be
the value of this property):
result.exceededThreshold-
"true" if the threshold specified by the
violationCountThreshold attribute is exceeded. The
property will not be set if the threshold is not exceeded or if
the threshold is not set.
result.resourceCount.total- The number of resources that were audited.
result.violationCount.high- The total number of high severity violations.
result.violationCount.low- The total number of low severity violations.
result.violationCount.medium- The total number of medium severity violations.
result.violationCount.total- The total number of violations.
|
No |
| storageLocation |
A designation of the storage location in which the audit result set
will be stored. It can be either workspace (the default)
or project: followed by the name of a project. This is
typically used to add the result set as a new data point to a
collection of result sets that comprise an audit series. 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 |
| violationCountThreshold |
The maximum number of violations that can be found by the audit before
the audit is considered to fail, as well as the list of severities that
are included in the count. If the audit fails, then the build will fail
as well.
These values are described by an expression composed of a plus ("+")
separated list of severity names ("high", "medium" and "low") and an
integer threshold value, with the list being separated from the
threshold by a greater than (">"). For example, if the audit should
fail if more than 200 high or medium level violations are found, the
attribute would be specified as:
violationCountThreshold="high+medium>200";
Multiple expressions of this form can be specified, separated by a
vertical bar ("|") to represent a condition that is the logical-or of
the individual subexpressions. For example, to specify that the audit
should fail if there are any high severity violations or more than 200
medium severity violations, the attribute would be specified as:
violationCountThreshold="high>0|medium>200"
If this parameter is not configured then the audit will not fail.
|
No |
| workspaceDir |
The location of the Eclipse workspace directory used when performing
the analysis. 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.audit task.
<auditRuleSet>
The auditRuleSet element is used to define an audit rule
set to be used when auditing the code. If multiple audit rule sets are
specified then they are all used. It has two attributes:
file-
The absolute or relative path to the file that contains the
audit rule set to be used. If the
name attribute is
specified (see below) then the audit rule set located in the
specified file with the specified name is used, otherwise the first
audit rule set in the file is used. If the file
attribute is not specified, then an audit rule set from the
workspace is used. Either the export preferences command or the
export
button on the audit preference page can be used to generate a
file containing audit rule sets.
name-
The name of the
audit rule set that will be used to generate audit violations.
If the
file attribute is specified (see above) then the
named audit rule set in the specified file is used, otherwise the
named audit rule set in the workspace is used. If no audit rule set
name is specified then either the first audit rule set in the file
or the default audit rule 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 are to be audited. 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).
The projectName attribute must also be specified.
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.
<mailAuthors>
The mailAuthors
element is used to send e-mail to the authors of the resources that contain
violations. The body of the e-mail is a report that is filtered to contain
only those violations associated with the declared author.
<report>
The report element
is used to generate a report based on the results of the audit. Multiple
reports will be generated if the report element is included
multiple times.
<seriesReport>
The seriesReport
element is used to generate a report based on the results of a series of
audits. Multiple reports will be generated if the seriesReport
element is included multiple times.
Examples
The following examples show how to use the instantiations.audit
task in a variety of ways.
Audit an Existing Workspace
Audit Existing Projects
CodePro User Guide
Overview
Overview