From 99353c349878fdd6ae224a88440fec0b5be83960 Mon Sep 17 00:00:00 2001 From: Stephane Bailliez Date: Wed, 1 Aug 2001 10:32:27 +0000 Subject: [PATCH] documentation for metamata tasks MMetrics and MAudit git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@269424 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/OptionalTasks/maudit.html | 137 ++++++++++++++++++++++++ docs/manual/OptionalTasks/mmetrics.html | 128 ++++++++++++++++++++++ 2 files changed, 265 insertions(+) create mode 100644 docs/manual/OptionalTasks/maudit.html create mode 100644 docs/manual/OptionalTasks/mmetrics.html diff --git a/docs/manual/OptionalTasks/maudit.html b/docs/manual/OptionalTasks/maudit.html new file mode 100644 index 000000000..2ba41b2c6 --- /dev/null +++ b/docs/manual/OptionalTasks/maudit.html @@ -0,0 +1,137 @@ + + + + +MAudit Task + + + + +

MAudit

+

by

+ +

Requirements

+

This task requires Metamata Development environment 2.0/Webgain Quality Analyzer 2.0. +An evaluation version is available at Webgain. +, Jakarta Oro and a XML parser (via JAXP).

+

Description

+

+ Invokes the Metamata Audit/ Webgain Quality Analyzer on a set of Java files. +

+

+ maudit performs static analysis of the Java source code and byte code files to find and report + errors of style and potential problems related to performance, maintenance and robustness. +. As a convenience, a stylesheet is given in etc directory, so that an HTML report can be generated from the XML file. +

+ +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
tofileThe XML file to which the Audit result should be written to.Yes
metamatahomeThe home directory containing the Metamata distribution.Yes
fix + Automatically fix certain errors (those marked as fixable in the manual). + No.Default to false.
list + Creates listing file for each audited file. A .maudit file will be generated in the + same location as the source file. + No. Default to false.
unused + Finds declarations unused in search paths. It will look for unused global declarations + in the source code within a use domain specified by the searchpath element. + No. Default to false.
maxmemorySet the maximum memory for the JVM. this is a convenient + way to set the -mx or -Xmx argument.No
+

Nested elements

+

jvmarg

+

Additional parameters may be passed to the VM via nested <jvmarg> +attributes. <jvmarg> allows all attributes described in Command +line arguments.

+

classpath

+

Sets class path (also source path unless one explicitly set). Overrides +METAPATH/CLASSPATH environment variables. The classpath element represents a PATH like +structure.

+

sourcepath

+

Sets source path. Overrides the SOURCEPATH environment variable. The sourcepath element represents a PATH like +structure.

+

sourcepath

+

Sets the search path to use as the use domain when looking for unused global declarations. The searchpath element represents a PATH like +structure.

+

fileset

+

Sets the Java files to audit via a FILESET structure. +Whatever the filter is, only the files that ends with .java will be included for processing. +Note that the base directory used for the fileset MUST be the root of the source files otherwise +package names deduced from the file path will be incorrect. +

+

Example

+
  <maudit tofile="c:/metamata/examples/auditexamples/audit.xml"
+          metamatahome="c:/metamata" fix="yes">
+    <classpath>
+      <pathelement location="c:/metamata/examples/auditexamples"/>
+    </classpath>
+    <sourcepath>
+      <pathelement location="c:/metamata/examples/auditexamples"/>
+    </classpath>
+    <fileset dir="c:/metamata/examples/auditexamples">
+        <include name="*.java"/>
+    <fileset>
+  </maudit>
+

+ This invokes Metamata Audit installed in c:/metamata on the audit examples +and fix automatically the fixable errors. +

+

Generating a report

+As a convenience, there is an XSL file(maudit-frames.xsl) that allows you to generate a full framed HTML report of the metrics. +You can find it in the etc directory of Ant. As it uses the Xalan extensions, you will need +BSF, Xalan and Xerces to run it. The stylesheet takes an output.dir parameter (otherwise it will be generated +in the current directory), it can be run in Ant as follows: +
+<java classname="org.apache.xalan.xslt.Process">
+    <param value="-IN"/>
+    <param value="${metrics.xml}"/>
+    <param value="-XSL"/>
+    <param value="maudit-frames.xsl"/>
+    <param value="-PARAM"/>
+    <param value="output.dir"/>
+    <param value="&quot;'${report.dir}'&quot;"/>
+</java>
+
+ +
+ + + +
+ + diff --git a/docs/manual/OptionalTasks/mmetrics.html b/docs/manual/OptionalTasks/mmetrics.html new file mode 100644 index 000000000..14af8de2f --- /dev/null +++ b/docs/manual/OptionalTasks/mmetrics.html @@ -0,0 +1,128 @@ + + + + +MMetrics Task + + + + +

MMetrics

+

by

+ +

Requirements

+

This task requires Metamata Development environment 2.0/Webgain Quality Analyzer 2.0. +An evaluation version is available at Webgain. +(Though you will not be able to use Metrics from the command line if you do not have a registered version). +You also need a TRaX compliant processor(such as Xalan 2.x) via JAXP 1.1

+

Description

+

+ Invokes the Metamata Metrics / WebGain Quality Analyzer source code + analyzer on a set of Java files. +

+

+ mmetrics will compute the metrics of a set of Java files and write the results to an XML + file. As a convenience, a stylesheet is given in etc directory, so that an HTML report can be generated from the XML file. +

+ +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
metamatahomeThe home directory containing the Metamata distribution.Yes
tofileThe XML were the resulting metrics will be written to.Yes
granularityMetrics granularity of the source files. Must be either + files (compilation-units), types (types and compilation-units) or methods + (methods, types and compilation-units). + Yes
maxmemorySet the maximum memory for the JVM. this is a convenient + way to set the -mx or -Xmx argument.No
+

Nested elements

+For specifying the source code to analyze, you can either use a path or fileset elements (though a single path element is preferred, see note below). +

jvmarg

+

Additional parameters may be passed to the VM via nested <jvmarg> +attributes. <jvmarg> allows all attributes described in Command +line arguments.

+

classpath

+

Sets class path (also source path unless one explicitly set). Overrides +METAPATH/CLASSPATH environment variables. The classpath element represents a PATH like +structure.

+

sourcepath

+

Sets source path. Overrides the SOURCEPATH environment variable. The sourcepath element represents a PATH like +structure.

+ +

path

+

Sets the list of directories to analyze the code for metrics.;It represents a PATH structure.

+

fileset

+

Sets a set of files to analyze for metrics.source It represents a FILESET structure.

+ +

+ +Note: For the sake of readability, it is highly recommended to analyze for a single unique directory instead than +using filesets or several directories. Otherwise there will be multiple metrics outputs without any way to know +what metrics refers to what source. Chance are also that the XML handler that does some heuristic will be confused +by the different outputs. + +

+ +

Example

+
  <mmetrics target="mmetrics.xml"
+          metamatahome="c:/metamata"
+          granularity="methods">
+    <classpath>
+      <pathelement location="c:/metamata/examples/metricsexamples"/>
+    </classpath>
+    <sourcepath>
+      <pathelement location="c:/metamata/examples/metricsexamples"/>
+    </sourcepath>
+    <path>
+      <pathelement location="c:/metamata/examples/metricsexamples"/>
+    </path>
+  </mmetrics>
+

+ This invokes Metamata Metrics installed in c:/metamata on the metrics example. + (Note that here, classpath and sourcepath are not normally not needed) +

+ +

Generating a report

+As a convenience, there is an XSL file(mmetrics-frames.xsl) that allows you to generate a full framed HTML report of the metrics. +You can find it in the etc directory of Ant. As it uses the Xalan extensions, you will need +BSF, Xalan and Xerces to run it. The stylesheet takes an output.dir parameter (otherwise it will be generated +in the current directory), it can be run in Ant as follows: +
+<java classname="org.apache.xalan.xslt.Process">
+    <param value="-IN"/>
+    <param value="${metrics.xml}"/>
+    <param value="-XSL"/>
+    <param value="mmetrics-frames.xsl"/>
+    <param value="-PARAM"/>
+    <param value="output.dir"/>
+    <param value="&quot;'${report.dir}'&quot;"/>
+</java>
+
+ +
+ +