2.3. Command line usage

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

Synopsis

java emmarun [(1) EMMA options] -cp classpath... class [args...]

java emmarun [(1) EMMA options] -jar jarfile [args...]

(1) [-f] [-ix filter patterns...] [-r report types...] [-sp sourcepath...] [-raw] [-out session data file] [-merge boolean] [common options]

alternative form:

java emma run {same as above...}

Options

[common command line options]

-f, -fullmetadata

This flag indicates whether the entire classpath (-cp) should be added to the coverage metadata (default: false). Without this flag, only the classes explicitly loaded by the JVM will be in the instrumentation set.

-ix, -filter filter patterns...

This repeatable option adds a coverage 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. It is equivalent to the same option of instr tool.

-r, -report (txt|html|xml)...

This repeatable option selects the type of coverage report(s) to generate (default: txt). It is equivalent to the same option of report tool.

-sp, -sourcepath list of source directories...

This repeatable option can be used to point the HTML report generator in <emmajava>/emmarun to the location of your Java source files. Equivalent to the same option of report tool.

-raw, -sessiondata

This flag 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).

-out, -outfile session data file

If -raw flag is set, this option overrides the location to store session data (default: file coverage.es in the current directory). Ignored otherwise.

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

Indicates whether the session data should be merged into the destination outfile, if any (default: true). Any existing data is clobbered otherwise.

report generation options...

Unlike its ANT equivalent, emmarun command line tool does not have dedicated options for controlling coverage report generation. If necessary, they can be set using generic -D, -properties, and other mechanisms.

So, for example, to change the default location of the HTML report you would override the report.out.file property:

>java emmarun -Dreport.html.out.file=mycoveragedir/myfile.html ...

(report.html.out.file can be abbreviated to report.out.file if the command generates a single report type)

Examples

Run an application and generate plain text and XML reports with default parameters:
```
>java emmarun -r txt,xml -jar SwingSet2.jar
```
Run an application and generate an HTML report with some customization and linking to the application source code:
```
>java emmarun -r html -Dreport.columns=name,method,line -sp src/ -jar SwingSet2.jar
```
Run an application and don't generate any reports, just dump the raw coverage session data:
```
>java emmarun -raw -jar SwingSet2.jar
```

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.


2.2. ANT usage		3. <instr>/instr