2.2. ANT usage

2.2. ANT usage
	2. <emmajava>/emmarun

<emmajava> task is an implicit combination of <instr> and <report> tasks and most of its attributes and nested elements are the same as for those two tasks combined.

Parameters specified as attributes

Attribute	Description	Required
[`stock ANT <java> task attributes`]
[`common EMMA task attributes`]		No
`libclasspath`	A path-like structure containing EMMA core (`emma.jar`).	Yes, unless EMMA is installed as the JRE extension
`libclasspathref`	Same as `libclasspath`, but given as a reference to a path defined elsewhere.	Yes, unless EMMA is installed as the JRE extension
`fullmetadata`	Indicates whether the entire classpath should be added to the coverage metadata (default: `false`).	No
`dumpsessiondata`	Indicates whether the session (metadata+coverage) data resulting from this coverage run should be dumped to a file. Useful for post-run coverage report generation (default: `false`).	No
`sessiondatafile`, `outfile`	If `dumpsessiondata='true'`, overrides the location to store session data (default: file `coverage.es` in the current directory). Ignored otherwise.	No
`merge`	Indicates whether the session data should be merged into the destination `sessiondatafile`, if any (default: `true`). Any existing data is clobbered otherwise.	No
`filter`	Adds a coverage filter. See Section 6.2, “Coverage filters” for general description of EMMA coverage filters and Section 6.2.1, “filter syntax: ANT” specifically for ANT syntax. This attribute plays a role equivalent to the same attribute of <instr>.	No
`sourcepath`	A path-like structure that can be used to point the HTML report generator in <emmajava>/emmarun to the location of your Java source files. 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. This attribute is equivalent to the same attribute of <report> task.	No
`sourcepathref`	Same as `sourcepath`, but given as a reference to a path defined elsewhere.	No
`units`	Equivalent to the same attribute of <report>.	No
`depth`	Equivalent to the same attribute of <report>.	No
`columns`	Equivalent to the same attribute of <report>.	No
`sort`	Equivalent to the same attribute of <report>.	No
`metrics`	Equivalent to the same attribute of <report>.	No
`encoding`	Equivalent to the same attribute of <report>.	No

Parameters specified as nested elements

Element	Description	Required
[`stock ANT <java> task nested elements`]
[`common EMMA task nested elements`]		No
`<filter>`	Adds a coverage filter. See Section 6.2, “Coverage filters” for general description of EMMA coverage filters and Section 6.2.1, “filter syntax: ANT” specifically for ANT syntax. This nested element plays a role equivalent to the same element of <instr>.	No
`<sourcepath>`	A path-like structure that can be used to point the HTML report generator in <emmajava>/emmarun to the location of your Java source files. This element is equivalent to the same nested element of <report> task.	No
`<txt>`	Equivalent to the same nested element of <report>.	No
`<html>`	Equivalent to the same nested element of <report>.	No (`<txt>` implied by default)
`<xml>`	Equivalent to the same nested element of <report>.	No (`<txt>` implied by default)

<txt>, <html>, and <xml> nested elements. These nested elements create plain text, HTML, and XML coverage reports, respectively. If none is specified, the plain text report is implied (at most one configurator of any given report type can be nested inside a given <emmajava> call). Configuration of these elements is described in the equivalent section of <report> task reference page.

Examples

Generate plain text and HTML reports with the default parameters:

    <emmajava enabled="${emma.enabled}" libclasspathref="emma.lib" 
              filter="${emma.filter}" sourcepath="${src.dir}"
              classname="Main" classpathref="run.classpath"
    >
      <!-- since this task is an extension of stock <java>, normal <java>
           options are still available: -->
      <arg value="someargvalue" />

      <txt outfile="${coverage.dir}/coverage.txt" />
      <html outfile="${coverage.dir}/coverage.html"  />
    </emmajava>

Do a full metadata scan (of run.classpath), generate an HTML report with some customization, use a <dirset> to set the sourcepath:

    <emmajava enabled="${emma.enabled}" libclasspathref="emma.lib" 
              fullmetadata="yes"
              classname="Main" classpathref="run.classpath"
    >
      <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"
      />
    </emmajava>

Don't generate any reports, just dump the raw coverage session data for now:

    <emmajava enabled="${emma.enabled}" libclasspathref="emma.lib" 
              fullmetadata="yes" dumpsessiondata="yes"
              classname="Main"
              classpathref="run.classpath"
    />


2. <emmajava>/emmarun		2.3. Command line usage