Chapter 1. Installation and System Requirements

Supported JRE versions. EMMA has been implemented to work in any J2SE runtime environment. For performance reasons, EMMA tools and runtime can benefit from (but do not require) J2SE APIs available in J2SE versions 1.3 and 1.4. EMMA command line tools, ANT tasks, and runtime have been tested in a variety of JREs from Sun Microsystem, IBM, and BEA.

Supported ANT versions. EMMA ANT tasks work with Apache ANT 1.4.1 and later versions.

External library dependencies. EMMA has no external Java or native library dependencies.

Operating system. EMMA is a pure Java application and does not use JVMPI or other profiling interfaces requiring native libraries. It should provide identical functionality on any operating system supported by J2SE v1.2+^[1].

EMMA distribution. EMMA is contained in two Java class archives (found in the lib subdirectory of EMMA distribution):

emma.jar: Contains the implementation of EMMA core components command line tools, and EMMA runtime classes (EMMA classes that are needed by Java application code that has been instrumented for coverage).
emma_ant.jar: Contains the implementation of EMMA ANT tasks (this archive depends on emma.jar and does not overlap with it in content).

General installation considerations. "Installing" EMMA simply implies making emma.jar and emma_ant.jar available to the Java Runtime Environment (JRE) and Apache ANT runtime, as appropriate.

There are two distinct runtime cases for EMMA:

Execution of an EMMA command line tool or ANT task.
Execution of some Java code that has been instrumented for coverage. Note that every EMMA-instrumented class becomes dependent on EMMA runtime classes (contained in emma.jar).

Installing EMMA core/runtime library. Accordingly, to run EMMA command line tools or EMMA-instrumented applications you need to add emma.jar to the appropriate JRE classpath. You can do it either via the -cp JVM option or by adding emma.jar as an installed JRE extension (by copying emma.jar to lib/ext subdirectory of your JRE or by setting the java.ext.dirs JVM system property to include the lib subdirectory of EMMA distribution. See Sun's documentation on Installed Extentions and java.ext.dirs property for more details).

The JRE extension option is preferred

It is highly recommended to install emma.jar as a JRE extension. This simplifies EMMA usage with application containers (IBM Websphere, BEA WebLogic, etc). Furthemore, installed JRE extensions are trusted by default: the instrumented application classes will automatically have the necessary runtime permissions for dumping coverage data files. Note that the JRE used by an application container may not necessarily be the same one you use from command line or ANT.

Setting up EMMA ANT tasks. To run EMMA ANT tasks, one additional configuration step inside build.xml is required:

  <!-- EMMA distribution directory: -->
  <property name='emma.dir' value='your EMMA install location' />

  <path id='emma.lib' >
    <fileset dir='${emma.dir}' includes='lib/*.jar' />
  </path>

  <taskdef resource='emma_ant.properties' classpathref='emma.lib' />

EMMA lib path

The build.xml snippet shown above defines a path element with emma.lib reference id. Although this is not strictly necessary (the <classpath> element nested inside the <taskdef> could have worked just as well), such a path element usually comes in handy elsewhere in the build.xml.

^[1]In a Sun Microsystems-compatible JRE prior to version 1.3 the runtime coverage data is dumped (in the offline coverage mode) only when the JVM is terminated via Ctrl-C or an equivalent signal.


EMMA Reference Manual		Chapter 2. EMMA Tool Reference