-
Notifications
You must be signed in to change notification settings - Fork 4
/
development.html
218 lines (162 loc) · 7.04 KB
/
development.html
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
<!DOCTYPE html>
<html>
<head>
<title>xtc Development Setup</title>
<link rel="stylesheet" href="http://cs.nyu.edu/rgrimm/bedrock2.css">
</head>
<body>
<h1>xtc Development Setup</h1>
<ul class="navigation">
<li><a href="#tools">Tools</a></li>
<li><a href="#dir">Directory Hierarchy</a></li>
<li><a href="#env">Environment Variables</a></li>
<li><a href="#make">Make Targets</a></li>
<li><a href="#code">Coding Conventions</a></li>
<li><a href="#pointers">Useful Pointers</a></li>
</ul>
<!-- ================================================================== -->
<h2 class="highlight" id="tools">Tools</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
<a href="http://www.gnu.org/software/make/">GNU make</a>,
find (either the GNU or BSD version will do),
<a href="http://www.gnu.org/software/bison/">bison</a>,
<a href="http://www.nongnu.org/cvs/">cvs</a>,
<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>. Note
that all these programs must be part of your local path.</p>
<p>xtc also includes several shell scripts, which may assume features
unique
to <a href="http://www.gnu.org/software/bash/bash.html">bash</a>.</p>
<p>A complete development installation also uses:</p>
<ul>
<li><a href="http://jflex.de/">JFlex</a> and
the <a href="http://javabdd.sourceforge.net/">JavaBDD</a> library for
our configuration-preserving C parser,</li>
<li><a href="http://www.junit.org/index.htm">JUnit</a> for unit
testing,</li>
<li><a href="http://www.kclee.com/clemens/java/javancss/">JavaNCSS</a>
for collecting source code statistics.</li>
</ul>
<p>All these tools need to be installed in the <code>bin</code>
directory:</p>
<ul>
<li><code>JFlex.jar</code> for JFlex,</li>
<li><code>javabdd.jar</code> for JavaBDD,</li>
<li><code>junit.jar</code> for JUnit,</li>
<li><code>ccl.jar</code>, <code>javacc.jar</code>, <code>javancss.jar</code>
and <code>jhbasic.jar</code> for JavaNCSS</li>
</ul>
<p>To build xtc’s classes, <code>javabdd.jar</code>
and <code>junit.jar</code> should be in the Java class path.</p>
<!-- ================================================================== -->
<h2 class="highlight" id="dir">Directory Hierarchy</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="highlight" id="env">Environment Variables</h2>
<dl>
<dt><code>JAVA_HOME</code></dt>
<dd>The JDK’s root directory, e.g.,
<code>/Library/Java/Home</code> on Mac OS X.</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. 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>~/xtc</code> on Unix.</dd>
<dt><code>CLASSPATH</code></dt>
<dd>The class path,
e.g., <code>~/xtc/classes:~/xtc/bin/junit.jar:~/xtc/bin/javabdd.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 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>An example shell script for Unix (<code>setup.sh</code>) is
contained in this directory.</p>
<!-- ================================================================== -->
<h2 class="highlight" id="make">Make Targets</h2>
<p>The following make targets are supported:</p>
<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>doc</code>, which builds embedded Javadoc
documentation.</li>
<li><code>clobber</code>, which removes all classes, Javadoc
documentation, jar files, and 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:
<ul>
<li><code>xtc.jar</code> contains all classes necessary for running
xtc.</li>
<li><code>rats-runtime.jar</code> contains only the classes necessary
for running <em>Rats!</em>-generated parsers.</li>
</ul>
</li>
<li><code>dist</code>, which generates two zip
files:
<ul>
</li><code>xtc-core.zip</code> contains xtc’s source code.</li>
<li><code>xtc-testsuite.zip</code> contains xtc’s regression
tests.</li>
</ul>
</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="highlight" id="code">Coding Conventions</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 (and <em>no</em> tab characters).
<!-- ================================================================== -->
<h2 class="highlight" id="pointers">Useful Pointers</h2>
<ul>
<li><a href="http://developer.java.sun.com/developer/TechTips/2000/tt0124.html#tip2">HPROF</a>:
a Java profiler.</li>
<li><a href="http://developer.java.sun.com/developer/technicalArticles/GUI/perfanal/">PerfAnal</a>:
a performance analysis tool.</li>
<li><a href="http://www.kclee.com/clemens/java/javancss/">JavaNCSS</a>:
a source measurement suite for Java.</li>
</ul>
</body></html>