Development Setup
[ Tools |
Directory Hierarchy |
Environment Variables |
Make Targets |
Coding Conventions |
Useful Pointers ]
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.
- 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.
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.
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.
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.
- HPROF: a Java profiler.
- PerfAnal:
a performance analysis tool.
- JavaNCSS: a
source measurement suite for Java.