1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
<!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>
|
