Development Setup

[ Tools | Directory Hierarchy | Environment Variables | Make Targets | Coding Conventions | Useful Pointers ]

Tools

We use the Java Standard Edition version 5 or higher and several Unix command line tools, including GNU make, find (either the GNU or BSD version will do), CVS, Info-ZIP, expect, and DejaGnu. On Windows, we recommend using the Cygwin port of these tools. Note that all these programs must be part of your local path. Further note that, on Windows, find must be the Unix version, not the version shipping with Windows.

A complete development installation also uses JUnit for unit testing, JavaNCSS for collecting source code statistics, and ANTLR for comparing the performance of different parsers. All these tools (i.e., junit.jar from the JUnit distribution, javancss.jar, ccl.jar, and jhbasic.jar from the JavaNCSS distribution, and antlr.jar from the ANTLR distribution) need to be installed in the bin directory. To build the classes or documentation, junit.jar and antlr.jar should be in the Java class path.

Directory Hierarchy

This directory
The root of the development tree, including global make files.
./src
Source files, using package name components for subdirectories.
./classes
Class files, using package name components for subdirectories.
./doc
The class documentation generated by javadoc.
./bin
Binaries, notably JAR files.
./glr
Source files for SDF- and Elkhound-generated Java parsers.
./data
Files for running experiments.

Environment Variables

JAVA_HOME
The JDK's root directory, e.g., /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home on Mac OS X or C:\j2sdk1.5.0 on Windows.
JAVA_RUNTIME
The JAR file with the Java platform classes, e.g., /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Classes/classes.jar on Mac OS X or C:\j2sdk1.5.0\jre\lib\rt.jar on Windows. Only set this environment variable when using Jikes as the Java compiler.
JAVA_DEV_ROOT
The root of the local directory hierarchy, i.e., this directory. For example, C:\user\xtc on Windows or ~/xtc on Unix.
CLASSPATH
The class path, e.g., C:\user\xtc\classes;C:\user\xtc\bin\junit.jar;C:\user\xtc\bin\antlr.jar on Windows or ~/xtc/classes:~/xtc/bin/junit.jar:~/xtc/bin/antlr.jar on Unix systems.
PATH_SEP
The path separator for the local operating system, e.g., ";" for Windows and ":" for Unix.
CVSROOT
The root directory for the CVS repository, e.g., :ext:user@machine:/home/pervasive/vault. Only set this environment variable if you have access to xtc's CVS repository.
CVS_RSH
/usr/bin/ssh. Only set this environment variable if you have access to xtc's CVS repository.

A note on path segment separators: It is OK to use backslashes '\' within environment variables on Windows, but all paths in make files must use forward slashes '/' as the path segment separator.

Example shell scripts for both Unix (setup.sh) and Windows (setup.bat) are contained in this directory. The Windows shell script is targeted at the native command line prompt; when running bash (which is part of Cygwin), it is probably easier to adapt the Unix shell script.

Make Targets

The following make targets are supported:

Coding Conventions

We generally follow the Java code conventions (in PDF) and make liberal use of javadoc comments. Though, we use two spaces as the unit of indentation.

Useful Pointers