3.2. ANT usage

3.2. ANT usage
	3. <instr>/instr

Parameters specified as attributes

Attribute	Description	Required
[`common EMMA task attributes`]		No
`instrpath`	A path-like structure specifying the instrumentation path to use.	Either this attribute, or `instrpathref` attribute, or at least one nested `<instrpath>` element must be present.
`instrpathref`	Same as `instrpath`, but given as a reference to a path defined elsewhere.	Either this attribute, or `instrpath` attribute, or at least one nested `<instrpath>` element must be present.
`destdir`, `outdir`	The location to store instrumented class files (in `fullcopy` mode instrumented classes are stored in `destdir/classes` and instrumented archives are stored in `destdir/lib` subdirectories, respectively). Ignored if `mode='overwrite'`.	Yes, unless `mode='overwrite'`
`metadatafile`, `outfile`	The location to store class coverage metadata (default: file `coverage.em` in the current directory). Neither particular file name nor extension are required.	No
`merge`	Indicates whether the metadata should be merged into the destination `metadatafile`, if any (default: `true`). Any existing data is clobbered otherwise.	No
`mode`	Specifies the instrumentation output mode. Valid values for this property are: `copy` (default): copy only instrumented class files and archive entries into `destdir` directory. `overwrite`: overwrite input class files and archives. `fullcopy`: copy all (instrumented or not) class files and archives to `destdir/classes` and `destdir/lib`, respectively. See Section 3.1, “Description” for more details.	No
`filter`	Adds an instrumentation filter. See Section 6.2, “Coverage filters” for general description of EMMA's instrumentation filters and Section 6.2.1, “filter syntax: ANT” specifically for ANT syntax.	No

Parameters specified as nested elements

Element	Description	Required
[`common EMMA task nested elements`]		No
`<instrpath>`	A path-like structure that specifies the instrumentation path to use.	Either `instrpath` attribute, or `instrpathref` attribute, or at least one nested `<instrpath>` element must be present.
`<filter>`	Adds an instrumentation filter. See Section 6.2, “Coverage filters” for general description of EMMA's instrumentation filters and Section 6.2.1, “filter syntax: ANT” specifically for ANT syntax.	No

<instrpath> nested elements. <instrpath> is a path-like structure used to select class files and archives to be processed for instrumentation. If a duplicate class name is encountered during a single instrumentation pass, only the first class definition will be added to the class metadata emitted during this instrumentation path. See Class metadata merging. for more details.

Examples

In-place instrument a certain subset of already compiled classes using overwrite mode and several coverage filters:

    <emma enabled="${emma.enabled}" >
      <instr instrpathref="${out.dir}/classes"
             mode="overwrite"
      >
        <!-- always exclude every class with a "Test" in the name: -->
        <filter excludes="*Test*" />
        <!-- don't instrument everything in "${out.dir}/classes",
             only the stuff I am working on now: -->
        <filter file="myincludes.txt" />
        <!-- additional ANT command line hook: -->
        <filter value="${emma.filter}" />
      </instr>
    </emma>

Don't overwrite compiled classes that later need to go into official release jars (stay in copy mode). However, use incremental instrumentation for fast personal testing:

    <emma enabled="${emma.enabled}" >
      <instr instrpathref="${out.dir}/classes"
             outdir="${out.dir}/classes-instrumented"
             merge="yes"
             filter="${emma.filter}"
      />
    </emma>

Take all jars already produced by the product build and make test (coverage-enabled) copies of them:

    <emma enabled="${emma.enabled}" >
      <instr mode="fullcopy"
             outdir="${out.instr.dir}"
             merge="no"
             filter="${emma.filter}"
      >
        <instrpath>
          <fileset dir="${out.dir}" includes="**/*.jar" />
        </instrpath>
      </instr>
    </emma>