EMMA development process

In order to make changes directly to EMMA CVS repository you need to have a valid SourceForge ID and join EMMA as a project developer with full CVS access.

The main difference for EMMA committers is that to have write access to SourceForge's CVS you can no longer use CVS pserver protocol. SourceForge requires using SSH authentication for CVS write access.

If you don't want to be prompted for your password by each CVS command, you should set up SourceForge's authorized keys. Assuming you have set up CVS_RSH environment variable to point to your SSH authenticator program, the commands to create a trunk and a release branch sandboxes for emma module are (branch 2.0 is used as an example):

>cvs -d:ext:myusername@cvs.sf.net:/cvsroot/emma co -A -d mytrunksandbox emma
>cvs -d:ext:myusername@cvs.sf.net:/cvsroot/emma co -r BRANCH_2_0 -d my2.0sandbox emma

Note that it will usually make little sense for a committer to create a CVS sandbox tied to a particular stable or release build tag (since those tags are "sticky" the sandbox will be essentially read-only).

SourceForge's CVS is much easier to use via Eclipse, to a large extent because Eclipse's built-in extssh connection type offers built-in SSH support, eliminating the need for an external SSH authentication software.

To create a CVS-aware EMMA project in Eclipse you need to configure a CVS repository location with your SourceForge developer credentials and extssh connection type:

1. Open "CVS Repositories" view.
2. Configure a new repository location:
   • Host: cvs.sf.net
   • Repository path: /cvsroot/emma
   • User: <your SF username>
   • Password: <your SF password>
   • Connection type: extssh
3. After Eclipse connects to SourceForge's CVS, you can expand various nodes under the repository location object and do "Check Out As...". You can create a trunk and a release branch sandboxes for emma module as follows:
   • Use emma module under "HEAD" to create a trunk sandbox project.
   • Use emma module under "Branches" to create a sandbox for a given branch, e.g. BRANCH_2_0. You will need to rename the project so it's different from the trunk one. (To make Eclipse aware of the existing EMMA branch tags you need to choose "Refresh Branches..." and select emma module in the following dialog.)

Note that it will usually make little sense for a committer to create a CVS sandbox tied to a particular stable or release build tag (since those tags are "sticky" the sandbox will be essentially read-only).

At first, the way emma module is organized looks daunting:

+--core
|  +--data
|  +--res
|  +--java12
|  +--java13
|  \--java14
|
+--ant
|  +--data
|  +--res
|  +--ant14
|  \--ant15
|
+--test
|  +--data
|  +--res
|  \--java
|
+--tools
\--lib

The structure is a little more complex than for a typical open-source project, but there are reasons for everything (one of them is sheer insanity). The top-level directories are:

• core: contains resources for EMMA core tools and runtime.

• ant: contains resources for EMMA ANT task definitions. The reason this is separate from core is because we anticipate creating a separate CVS module for all EMMA plugins (Maven, Eclipse, etc) and the ANT tasks may migrate into that module in the future.

• test: all test-related resources. This is a separate directory to allow testcases in the same Java packages as the core code (for white-box testing via package-private accessors) while keeping the testsuite separate from core code.

• tools: Java sources for the internal tools used by the build (these are built as part of the build process itself).

• lib: this holds binary dependencies for the build that are checked into CVS.

Within several top-level directories, there are sub-directories following the same general pattern:

• res: this contains resources that get loaded via java.lang.ClassLoader API (anything placed into res is automatically picked up and packaged in one of build-generated jars just like it were a Java class).

• data: this contains supporting resources that are neither sources nor classloader resources.

• java*, ant*, etc: all other folders are source folders. There could be more than one for the following reason: at the moment EMMA sources are grouped by the minimum Java or ANT version they require. EMMA makes strong promises of being compatible with any Java 2 JVM, and the official build goes to great lengths compiling Java 1.2-compatible sources against J2SE 1.2, Java 1.3-compatible sources against J2SE 1.3, etc. (Time will tell whether this was worth the trouble. This organization builds on the ideas published in What version is your Java code?)

When you build EMMA via the default ANT target (build) you are making a private build out of the sources on your local drive (a version for personal use and testing). EMMA file releases at SourceForge are produced via a more rigorous process. The main differences here are:

• During an official build, the CVS trunk or the current release branch is "readied" (that is, tagged with the anticipated stable or release label as shown here) so that the build is reproducible from a known CVS tag.

• The offical build is made on a machine that has three known JDKs {1.2 (build JDK-1.2.2-W, native threads, symcjit), 1.3 (build 1.3.1-b24, mixed mode), and 1.4 (build 1.4.2_01-b06, mixed mode)} installed and with build.target.j2se.1{2,3,4}.home build properties set to point to those locations. This helps detect code that purports to be older Java versions-compatible but in reality isn't.

The combination of CVS build tagging and using a dedicated build machine with known JDK versions ensures that every publicly released EMMA build is reproducible down to .class binary content, if necessary.

Because build.xml defaults to building privately, usually only the project admin needs to worry about the complexities of the official build process.