3.3. Command line usage

3.3. Command line usage
	3. <instr>/instr

Synopsis

java emma instr {-ip instrumentation path...} [-d directory] [-out metadata file] [-merge boolean] [-m output mode] [-ix filter patterns...]
[common options]

Options

[common command line options]

-ip, -cp, -instrpath instrumentation path...

This repeatable option sets the instrumentation path to use. Besides the OS-specific separator character, individual path segments can also be separated with commas.

-d, -dir, -outdir directory

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 -m is overwrite.

-out, -outfile metadata file

The location to store class coverage metadata (default: file coverage.em in the current directory). Neither particular file name nor extension are required.

-merge (y[es]|n[o])

This flag indicates whether the metadata should be merged into the destination -out file, if any (default: true). Any existing data is clobbered otherwise.

-m, -outmode (copy|overwrite|fullcopy)

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.

-ix, -filter filter patterns...

This repeatable option adds an instrumentation filter. See Section 6.2, “Coverage filters” for general description of EMMA coverage filters and Section 6.2.2, “filter syntax: command line” specifically for command line syntax.

Examples

In-place instrument a certain subset of already compiled classes using overwrite mode and several coverage filters:
```
>java emma instr -m overwrite -ip out/classes -ix -*Test* -ix @myfilters.txt
```
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:
```
>java emma instr -merge y -ip out/classes -d out/classes-instrumented
```
Take all jars already produced by the product build and make test (coverage-enabled) copies of them:
```
>java emma instr -m fullcopy -merge no -ip out/Product.jar -d out-instrumented/
```

Diagnostics

The default EMMA command line tool behavior is not to use System.exit() on exit unless an explicit -exit option is specified. If that is done, the error codes returned via System.exit() are as follows:

`0`	Successful completion.
`1`	Failure due to incorrect option usage. This error code is also returned when command line usage (`-h`) is requested explicitly.
`2`	All other failures.


3.2. ANT usage		4. <report>/report