xtc 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), bison, cvs, Info-ZIP, expect, and DejaGnu. Note that all these programs must be part of your local path.

xtc also includes several shell scripts, which may assume features unique to bash.

A complete development installation also uses:

• JFlex and the JavaBDD library for our configuration-preserving C parser,
• JUnit for unit testing,
• JavaNCSS for collecting source code statistics.

All these tools need to be installed in the bin directory:

• JFlex.jar for JFlex,
• javabdd.jar for JavaBDD,
• junit.jar for JUnit,
• ccl.jar, javacc.jar, javancss.jar and jhbasic.jar for JavaNCSS

To build xtc’s classes, javabdd.jar and junit.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., /Library/Java/Home on Mac OS X.

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. 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, ~/xtc on Unix.

CLASSPATH

The class path, e.g., ~/xtc/classes:~/xtc/bin/junit.jar:~/xtc/bin/javabdd.jar on Unix systems.

PATH_SEP

The path separator for the local operating system, e.g., “:” 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.

An example shell script for Unix (setup.sh) is contained in this directory.

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.
• doc, which builds embedded Javadoc documentation.
• clobber, which removes all classes, Javadoc documentation, jar files, and 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.
  • rats-runtime.jar contains only the classes necessary for running Rats!-generated parsers.
• dist, which generates two zip files:
  xtc-core.zip contains xtc’s source code.
  • 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 (and no tab characters).

Useful Pointers

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