# 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:

- `configure`, which configures the local system's C limits and types.
- `classes`, which is the default and builds all classes.
- `parsers`, which builds all parsers.
- `analyzers`, which builds all Typical type checkers.
- `doc`, which builds embedded Javadoc documentation.
- `clobber`, which removes all built classes, Javadoc generated documentation, JAR files, and the source distribution ZIP files.
- `clobber-parsers`, which removes the source code for all parsers.
- `jars`, which builds the xtc JAR files: `xtc.jar` contains all classes necessary for running xtc and `rats-runtime.jar` contains only those classes necessary for running Rats!-generated parsers.
- `dist`, which generates two ZIP files: `xtc-core.zip` contains xtc's source distribution, and `xtc-testsuite.zip` contains xtc's regression tests.
- `stats`, which prints JavaNCSS generated source code statistics.
- `check`, which runs all regression tests.

## 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

- HPROF: a Java profiler.
- PerfAnal: a performance analysis tool.
- JavaNCSS: a source measurement suite for Java.