Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
225 lines (165 sloc) 7.86 KB
<title>Development Setup</title>
<link rel="stylesheet" href=""
<!-- ================================================================== -->
<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="">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,
href="">Info-ZIP</a>, <a
and <a href="">DejaGnu</a>. On
Windows, we recommend using
the <a href="">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="">JUnit</a> for unit
testing, <a
href="">JavaNCSS</a> for
collecting source code statistics,
and <a href="">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>
<dt>This directory</dt>
<dd>The root of the development tree, including global make files.</dd>
<dd>Source files, using package name components for
<dd>Class files, using package name components for subdirectories.</dd>
<dd>The class documentation generated by <code>javadoc</code>.</dd>
<dd>Binaries, notably JAR files.</dd>
<dd>Source files for SDF- and Elkhound-generated Java parsers.</dd>
<dd>Files for running experiments.</dd>
<!-- ================================================================== -->
<h2 class="title bar"><a name="env">Environment Variables</a></h2>
<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>
<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="">Jikes</a>
as the Java compiler.</dd>
<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>
<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>
<dd>The path separator for the local operating system, e.g.,
"<code>;</code>" for Windows and "<code>:</code>" for Unix.</dd>
<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>
<dd><code>/usr/bin/ssh</code>. Only set this environment variable if
you have access to xtc's CVS repository.</dd>
<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></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
<li><code>parsers</code>, which builds all parsers.</li>
<li><code>analyzers</code>, which builds all Typical type
<li><code>doc</code>, which builds embedded Javadoc
<li><code>clobber</code>, which removes all built classes, Javadoc
generated documentation, JAR files, and the source distribution ZIP
<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></code> contains xtc's source distribution,
and <code></code> contains xtc's regression
<li><code>stats</code>, which prints JavaNCSS generated source code
<li><code>check</code>, which runs all regression tests.</li>
<!-- ================================================================== -->
<h2 class="title bar"><a name="code">Coding Conventions</a></h2>
<p />We generally follow
the <a
code conventions</a>
(in <a
and make liberal use
of <a href="">
<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>
<li class="tight"><a
href="">HPROF</a>: a Java profiler.</li>
<li class="tight"><a
a performance analysis tool.</li>
<li class="tight"><a
href="">JavaNCSS</a>: a
source measurement suite for Java.</li>