4.2. ANT usage

4.2. ANT usage
	4. <report>/report

Parameters specified as attributes

Attribute	Description	Required
[`common EMMA task attributes`]		No
`sourcepath`	An optional source path to use for report generation (a path-like structure). It is interpreted as a list of directories (separated by the OS-specific classpath separator or comma) containing `.java` source files. The local path names within each directory should reflect class package names. (Currently, only the HTML report generator uses this data, and only at `method` report depth.)	No
`sourcepathref`	Same as `sourcepath`, but given as a reference to a path defined elsewhere.	No
`units`	Specifies whether weighted or unweighted coverage metrics are calculated. Valid values are: `instr` (default): use metrics weighted by bytecode instruction count; `count`: use traditional metric definitions (each basic block has equal weight).	No
`depth`	Specifies the amount of detail to be included in the generated coverage reports, as described in Report depth.. Valid values (in order of increasing level of detail) are: `all` `package` `source` `class` `method` (default values are report type-specific, see below)	No
`columns`	Specifies which report columns and in which order to use for report generation, as a comma-separated list of column ids. Valid column ids are the name of the item reported on and various types of coverage: `name`, `class`, `method`, `block`, and `line`. Coverage types that are not available for a given item type and debug info level are automatically ignored. Reports can use only a subset of all possible columns (and different report types can use different subsets). Duplicate column names are ignored. Setting this attribute is the same as setting the report.columns property for all report types (default values are report type-specific, see below).	No
`sort`	Specifies report column sorting order, as a comma-separated list of column ids prefixed with “+” for ascending or “-” for descending directions. The first column id is the primary sort and subsequent column ids are secondary sorts, in the order given. Only the column ids specified by `columns` attribute are considered. Setting this attribute is the same as setting the report.sort property for all report types (default: `+block,+name,+method,+class`).	No
`metrics`	Specifies the threshold coverage metric values for a given set of columns (all coverage percentages that are below a given threshold are marked up in the report types that support this). The value is a comma-separated list of column id-value pairs, with the value being the minimum required coverage percentage. Setting this attribute is the same as setting the report.metrics property for all report types (default: `method:70,block:80,line:80,class:100`).	No
`encoding`	Sets the charset id for report output files (this is best done at the individual report type level). Setting this attribute is the same as setting the report.out.encoding property for all report types (default values are report type-specific, see below).	No

Parameters specified as nested elements

Element	Description	Required
[`common EMMA task nested elements`]		No
`<infileset>`, `<fileset>`	A FileSet that selects a set of metadata and coverage data files that form the basis of coverage calculations in the generated report(s). It is an error not to include any metadata or any coverage data within this set of files.	Yes
`<sourcepath>`	A path-like structure that specifies an optional source path to use for HTML report generation.	No
`<txt>`	Instructs <report> to generate a plain-text coverage report. The report can be further customized as shown below.	At least one of `<txt>`, `<html>`, `<xml>` is required
`<html>`	Instructs <report> to generate an HTML coverage report. The report can be further customized as shown below.	At least one of `<txt>`, `<html>`, `<xml>` is required
`<xml>`	Instructs <report> to generate an XML coverage report. The report can be further customized as shown below.	At least one of `<txt>`, `<html>`, `<xml>` is required

<infileset> nested elements. <infileset> nested elements are configured as any other FileSet data type in ANT. Additionally, EMMA's version of FileSet data type allows file attribute in ANT versions earlier than 1.5.x (which is useful for selecting a single file by its known name without using an explicit PatternSet).

<sourcepath> nested elements. <sourcepath> is a path-like structure that can be used to point <report>/report to the location of your Java source files. If the HTML report depth is set to method and the instrumented classes were compiled with enough debug information, the report generator will embed whichever source files it can find inside the HTML report pages and highlight covered/not covered lines.

<txt>, <html>, and <xml> nested elements. These nested elements create plain text, HTML, and XML coverage reports, respectively. At least one report type must be specified (at most one configurator of any given report type can be nested inside a given <report>). All of them accept the same set of report configuration attributes (if a particular attribute is not specified for an element, its value is inherited from the <report> parent. If the parent task does not specify an attribute value either, the usual EMMA property inheritance rules determine the eventual value):

Attribute	Description	Required
`units`	Overrides the coverage metric units for a given report type. It is perhaps best to set this at the parent <report> level, so that all generated reports use consistent units.	No
`depth`	Overrides the report depth for a given report type. The default values are: `txt` report: `all` `html` report: `method` `xml` report: `method`	No
`columns`	Overrides the report column selection and order for a given report type.The default values are: `txt` report: `class,method,block,line,name` `html` report: `name,class,method,block,line` `xml` report: `name,class,method,block,line`	No
`sort`	Overrides the report column sort order for a given report type.	No
`metrics`	Overrides the report coverage metrics thresholds for a given report type. It is perhaps best to set this at the parent <report> level, so that all generated reports use consistent metrics.	No
`outfile`	Overrides the default report output file location. The default settings are: `txt` report: file `coverage.txt` in the current directory `html` report: file `coverage/index.html` (note that the HTML report is usually split over multiple files, so it is best to specify a file pathname that is inside a dedicated subdirectory) `xml` report: file `coverage.xml` in the current directory	No
`encoding`	Overrides the output file charset encoding used for a given report type. The default values are: `txt` report: mirrors the `file.encoding` JRE system property `html` report: `ISO-8859-1` `xml` report: `UTF-8`	No

Examples

Generate plain text and XML report types, all with default settings:

    <emma enabled="${emma.enabled}" >
      <report >
        <!-- collect all EMMA data dumps (metadata and runtime): -->
        <infileset dir="${coverage.dir}" includes="*.em, *.ec" />

        <txt />
        <xml />
      </report>
    </emma>

Generate three report types, with common metrics and column sorting, but with different report depth and column orderings:

    <emma enabled="${emma.enabled}" >
      <report sourcepath="${src.dir}"
              sort="+block,+name,+method,+class"
              metrics="method:70,block:80,line:80,class:100"
      >
        <infileset dir="${coverage.dir}" includes="*.em, *.ec" />

        <!-- for every type of report desired, configure a nested
             element; various report parameters
             can be inherited from the parent <report>
             and individually overridden for each report type:
        -->
        <txt outfile="${coverage.dir}/coverage.txt"
             depth="package"
             columns="class,method,block,line,name"
        />
        <xml outfile="${coverage.dir}/coverage.xml"
             depth="package"
        />
        <html outfile="${coverage.dir}/coverage.html"
             depth="method"
             columns="name,class,method,block,line"
        />
      </report>
    </emma>

Generate an HTML report with some customization, load metadata and runtime coverage data from a single session file, use a <dirset> to set the sourcepath:

    <emma enabled="${emma.enabled}" >
      <report >
        <infileset file="${coverage.dir}/coverage.es" />

        <sourcepath>
          <dirset dir="${basedir}" >
            <include name="**/src" /> 
          </dirset>
        </sourcepath>

        <html outfile="${coverage.dir}/index.html"
              columns="name, method, line"
              sort="+line, +name"
              metrics="line:80"
        />
      </report>
    </emma>


4. <report>/report		4.3. Command line usage