Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
225 lines (165 sloc) 7.86 KB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Development Setup</title>
<link rel="stylesheet" href="http://cs.nyu.edu/rgrimm/bedrock.css"
type="text/css">
</head>
<!-- ================================================================== -->
<body>
<h1 class="title">Development Setup</h1>
<!-- ================================================================== -->
<p class="head centered" />
[ <a href="#tools">Tools</a> |
<a href="#dir">Directory Hierarchy</a> |
<a href="#env">Environment Variables</a> |
<a href="#make">Make Targets</a> |
<a href="#code">Coding Conventions</a> |
<a href="#pointers">Useful Pointers</a> ]
<!-- ================================================================== -->
<h2 class="title bar"><a name="tools">Tools</a></h2>
<p />We use the <a href="http://java.sun.com/javase/index.jsp">Java
Standard Edition</a> version 5 or higher and several Unix command line
tools, including GNU make, find (either the GNU or BSD version will
do), CVS,
<a
href="http://www.info-zip.org/">Info-ZIP</a>, <a
href="http://expect.nist.gov/">expect</a>,
and <a href="http://www.gnu.org/software/dejagnu/">DejaGnu</a>. On
Windows, we recommend using
the <a href="http://sources.redhat.com/cygwin">Cygwin</a> port of
these tools. Note that all these programs must be part of your local
path. Further note that, on Windows, <code>find</code> must be the
Unix version, <em>not</em> the version shipping with Windows.
<p />A complete development installation also
uses <a href="http://www.junit.org/index.htm">JUnit</a> for unit
testing, <a
href="http://www.kclee.com/clemens/java/javancss/">JavaNCSS</a> for
collecting source code statistics,
and <a href="http://www.antlr.org/">ANTLR</a> for comparing the
performance of different parsers. All these tools
(i.e., <code>junit.jar</code> from the JUnit
distribution, <code>javancss.jar</code>,
<code>ccl.jar</code>, and <code>jhbasic.jar</code> from the JavaNCSS
distribution, and <code>antlr.jar</code> from the ANTLR distribution)
need to be installed in the <code>bin</code> directory. To build the
classes or documentation, <code>junit.jar</code>
and <code>antlr.jar</code> should be in the Java class path.
<!-- ================================================================== -->
<h2 class="title bar"><a name="dir">Directory Hierarchy</a></h2>
<dl>
<dt>This directory</dt>
<dd>The root of the development tree, including global make files.</dd>
<dt><code>./src</code></dt>
<dd>Source files, using package name components for
subdirectories.</dd>
<dt><code>./classes</code></dt>
<dd>Class files, using package name components for subdirectories.</dd>
<dt><code>./doc</code></dt>
<dd>The class documentation generated by <code>javadoc</code>.</dd>
<dt><code>./bin</code></dt>
<dd>Binaries, notably JAR files.</dd>
<dt><code>./glr</code></dt>
<dd>Source files for SDF- and Elkhound-generated Java parsers.</dd>
<dt><code>./data</code></dt>
<dd>Files for running experiments.</dd>
</dl>
<!-- ================================================================== -->
<h2 class="title bar"><a name="env">Environment Variables</a></h2>
<dl>
<dt><code>JAVA_HOME</code></dt>
<dd>The JDK's root directory, e.g.,
<code>/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home</code> on Mac OS X or
<code>C:\j2sdk1.5.0</code> on Windows.</dd>
<dt><code>JAVA_RUNTIME</code></dt>
<dd>The JAR file with the Java platform classes, e.g.,
<code>/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Classes/classes.jar</code> on Mac OS X or
<code>C:\j2sdk1.5.0\jre\lib\rt.jar</code> on Windows. Only set this
environment variable when using
<a href="http://www-124.ibm.com/developerworks/oss/jikes/">Jikes</a>
as the Java compiler.</dd>
<dt><code>JAVA_DEV_ROOT</code></dt>
<dd>The root of the local directory hierarchy, i.e., this
directory. For example, <code>C:\user\xtc</code> on Windows or
<code>~/xtc</code> on Unix.</dd>
<dt><code>CLASSPATH</code></dt>
<dd>The class path,
e.g., <code>C:\user\xtc\classes;C:\user\xtc\bin\junit.jar;C:\user\xtc\bin\antlr.jar</code>
on Windows
or <code>~/xtc/classes:~/xtc/bin/junit.jar:~/xtc/bin/antlr.jar</code>
on Unix systems.</dd>
<dt><code>PATH_SEP</code></dt>
<dd>The path separator for the local operating system, e.g.,
"<code>;</code>" for Windows and "<code>:</code>" for Unix.</dd>
<dt><code>CVSROOT</code></dt>
<dd>The root directory for the CVS repository, e.g.,
<code>:ext:user@machine:/home/pervasive/vault</code>. Only set this
environment variable if you have access to xtc's CVS repository.</dd>
<dt><code>CVS_RSH</code></dt>
<dd><code>/usr/bin/ssh</code>. Only set this environment variable if
you have access to xtc's CVS repository.</dd>
</dl>
<p />A note on path segment separators: It is OK to use backslashes
'<code>\</code>' within environment variables on Windows, but all
paths in make files must use forward slashes '<code>/</code>' as the
path segment separator.
<p />Example shell scripts for both Unix (<code>setup.sh</code>) and
Windows (<code>setup.bat</code>) are contained in this directory. The
Windows shell script is targeted at the native command line prompt;
when running <code>bash</code> (which is part of Cygwin), it is
probably easier to adapt the Unix shell script.
<!-- ================================================================== -->
<h2 class="title bar"><a name="make">Make Targets</a></h2>
<p />The following make targets are supported:<ul>
<li><code>configure</code>, which configures the local system's C
limits and types.</li>
<li><code>classes</code>, which is the default and builds all
classes.</li>
<li><code>parsers</code>, which builds all parsers.</li>
<li><code>analyzers</code>, which builds all Typical type
checkers.</li>
<li><code>doc</code>, which builds embedded Javadoc
documentation.</li>
<li><code>clobber</code>, which removes all built classes, Javadoc
generated documentation, JAR files, and the source distribution ZIP
files.</li>
<li><code>clobber-parsers</code>, which removes the source code for
all parsers.</li>
<li><code>jars</code>, which builds the xtc JAR
files: <code>xtc.jar</code> contains all classes necessary for running
xtc and <code>rats-runtime.jar</code> contains only those classes
necessary for running <em>Rats!</em>-generated parsers.</li>
<li><code>dist</code>, which generates two ZIP
files: <code>xtc-core.zip</code> contains xtc's source distribution,
and <code>xtc-testsuite.zip</code> contains xtc's regression
tests.</li>
<li><code>stats</code>, which prints JavaNCSS generated source code
statistics.</li>
<li><code>check</code>, which runs all regression tests.</li>
</ul>
<!-- ================================================================== -->
<h2 class="title bar"><a name="code">Coding Conventions</a></h2>
<p />We generally follow
the <a
href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Java
code conventions</a>
(in <a
href="ftp://ftp.javasoft.com/docs/codeconv/CodeConventions.pdf">PDF</a>)
and make liberal use
of <a href="http://java.sun.com/j2se/javadoc/index.html">
<code>javadoc</code> </a> comments. Though, we use <em>two spaces</em>
as the unit of indentation.
<!-- ================================================================== -->
<h2 class="title bar"><a name="pointers">Useful Pointers</a></h2>
<ul>
<li class="tight"><a
href="http://developer.java.sun.com/developer/TechTips/2000/tt0124.html#tip2">HPROF</a>: a Java profiler.</li>
<li class="tight"><a
href="http://developer.java.sun.com/developer/technicalArticles/GUI/perfanal/">PerfAnal</a>:
a performance analysis tool.</li>
<li class="tight"><a
href="http://www.kclee.com/clemens/java/javancss/">JavaNCSS</a>: a
source measurement suite for Java.</li>
</ul>
</body></html>