-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME-STELLA
250 lines (190 loc) · 9.69 KB
/
README-STELLA
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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
-*- Mode: Text -*-
STELLA INSTALLATION GUIDE
Version: README,v 1.16 2006/05/21 07:15:31 hans Exp
This document describes STELLA 3.3 or later.
For more documentation on STELLA, please see the STELLA manual.
This is available from the STELLA web site:
http://www.isi.edu/isd/LOOM/Stella/
and included with the release, in the directory `sources/stella/doc/'.
System Requirements
===================
To install and use STELLA you'll approximately need the following
amounts of disk space:
* 8 MB for the tar-red or zip-ped archive file
* 35 MB for the untarred sources, tanslations, compiled Java files
and documentation
* 8 MB to compile a Lisp version
* 11 MB to compile the C++ version (without -g)
* 3 MB to compile the Java version (already included)
This means that you will need approximately 55 MB to work with one
Lisp, one C++ and one Java version of STELLA in parallel. If you also
want to experiment with the Lisp translation variant that uses
structures instead of CLOS instances to implement STELLA objects, then
you will need an extra 8 MB to compile that.
The full STELLA development tree is quite large, since for every
STELLA source file there are three to four translated versions and as
many compiled versions thereof. The actual STELLA libraries that you
have to ship with an application, however, are quite small. For
example, the Java jar file `stella.jar' is only about 1.3 MB in size.
The dynamic C++ library `libstella.so' compiled on a Linux platform is
about 4 MB. Additionally, if you don't need all the different
translations of STELLA, you can delete some of the versions to keep your
development tree smaller (*Note Removing Unneeded Files::).
To run the Lisp version of STELLA you need an ANSI Common-Lisp (or at
least one that supports CLOS and logical pathnames). We have
successfully tested STELLA with Allegro-CL 4.2, 4.3, 5.0, 6.0 and 7.0,
Macintosh MCL 3.0, 4.0 and 5.1, OpenMCL 1.0, SBCL 0.9.4, CMUCL 19c,
LispWorks 4.4.6, CLisp 2.37, Lucid CL 4.1 (plus the necessary ANSI
extensions and Mark Kantrowitz's logical pathnames implementation) and
various others. Our main development platform is Allegro CL running
under Sun Solaris and Linux, so, the closer your environment is to ours,
the higher are the chances that everything will work right out of the
box. Lisp development under Windows should also be no problem.
To run the C++ version of STELLA you need a C++ compiler such as g++
that supports templates and exception handling. We have successfully
compiled and run STELLA with g++ 3.2 and later under Linux Redhat 8.0 &
9.0, SunOS and MacOS X, and with CygWin 5.0 and MinGW 5.0 under Windows
2000 and XP. Both CygWin and MinGW provide a GNU Unix environment, but
MinGW can generate Windows executables that are fully standalone. We've
also managed to compile STELLA under MS Visual C++, however, we never
got the Boehm garbage collector to work. The GC claims to be very
portable, so this should be solvable for somebody with good knowledge of
MS Visual C++.
For the Java version you will need Java JDK 1.2 or later. To get
reasonable performance, you should use J2SDK 1.4 or 1.5. We've run the
Java version of STELLA on a variety of platforms without any problems.
Any one of the Lisp, C++ or Java implementations of STELLA can be
used to develop your own STELLA code and translate it into all three
languages, but the most convenient development environment is the one
based on Lisp. If you use the C++ or Java version, translating and
using your own STELLA macros is possible but not yet very well
supported.
Unpacking the Sources
=====================
Uncompress and untar the file `stella-X.Y.Z.tar.gz' (or unzip the file
`stella-X.Y.Z.zip') in the parent directory of where you want to
install STELLA (`X.Y.Z' are place holders for the actual version
numbers). This will create the STELLA tree in the directory
`stella-X.Y.Z/'. All pathnames mentioned below will be relative to that
directory which we will usually refer to as the "STELLA directory".
Lisp Installation
=================
To install the Lisp version startup Lisp and load the file
`load-stella.lisp' with:
(CL:load "load-stella.lisp")
The first time around this will compile all Lisp-translated STELLA
files before they are loaded. During subsequent sessions the compiled
files will be loaded right away.
If you want to use the version that uses Lisp structs instead of CLOS
objects to implement STELLA objects do the following:
(CL:setq cl-user::*load-cl-struct-stella?* CL:t)
(CL:load "load-stella.lisp")
Alternatively, you can edit the initial value of the variable
`*load-cl-struct-stella?*' in the file `load-stella.lisp'. Using
structs instead of CLOS objects greatly improves slot access speed,
however, it may cause problems with incremental re-definition of STELLA
classes. It is therefore recommended to only use this for systems that
are in or near the production stage.
Once all the files are loaded, you should see a message like this:
Initializing STELLA...
STELLA 3.4.0 loaded.
Type `(in-package "STELLA")' to execute STELLA commands.
USER(2):
To reduce startup time, you might want to create a Lisp image that
has all of STELLA preloaded.
Now type
(in-package "STELLA")
to enter the `STELLA' Lisp package where all the STELLA code resides.
*IMPORTANT*: All unqualified Lisp symbols in this document are
assumed to be in the `STELLA' Lisp package. Moreover, the `STELLA'
package does *NOT* inherit anything from the `COMMON-LISP' package (see
the file `sources/stella/cl-lib/cl-setup.lisp' for the few exceptions),
hence, you have to explicitly qualify every Lisp symbol you want to use
with `CL:'. For example, to get the result of the previous evaluation
you have to type `CL:*' instead of `*'.
C++ Installation
================
To compile the C++ version of STELLA change to the native C++ directory
and run `make':
% cd native/cpp/stella
% make
This will compile all STELLA files, the garbage collector and
generate a static or dynamic `libstella' library file in the directory
`native/cpp/lib' which can later be linked with your own C++-translated
STELLA (or other) code. To test whether the compilation was successful
you can run STELLA from the top-level STELLA directory using the
`stella' script (or `stella.bat' under a Windows command prompt):
% stella c++
Running C++ version of STELLA...
Welcome to STELLA 3.4.0
Running kernel startup code...
Initializing symbol tables...
Initializing quoted constants...
Initializing global variables...
Creating class objects...
Finalizing classes...
Creating method objects...
Finalizing methods...
Running non-phased startup code...
Starting up translators...
Bye!
This will simply run various STELLA startup code and exit. *Note
Hello World in C++::, to see how you can use the STELLA C++ executable
to translate STELLA code. The `c++' argument tells the script to run
the C++ version of STELLA. If the argument is omitted and the C++
version is installed, it will be run automatically. Otherwise, the Java
version will be run.
Java Installation
=================
Nothing needs to be done to install the Java version. Since Java class
files are platform independent, they are already shipped with the STELLA
distribution and can be found in the directory `native/java' and its
subdirectories. Additionally, they have been collected into the file
`native/java/lib/stella.jar'. To try out the Java version of STELLA
run the `stella' script in the STELLA directory:
% stella java
Running Java version of STELLA...
Welcome to STELLA 3.4.0
Running kernel startup code...
Initializing symbol tables...
Initializing quoted constants...
Initializing global variables...
Creating class objects...
Finalizing classes...
Creating method objects...
Finalizing methods...
Running non-phased startup code...
Starting up translators...
Bye!
Similar to the C++ executable, this will simply run various STELLA
startup code and exit. *Note Hello World in Java::, to see how you can
use the STELLA Java executable to translate STELLA code.
X/Emacs Setup
=============
STELLA development is very similar to Lisp development, and it is best
done in an X/Emacs-based Lisp development environment such as the
Allegro-CL Emacs interface plus Allegro Composer, or ILISP. If you do
use X/Emacs with the Allegro CL interface, add the following to your
`.emacs' or `.xemacs/init.el' file:
(setq auto-mode-alist
(cons '("\\.ste$" . fi:common-lisp-mode) auto-mode-alist))
If you are using the Allegro CL interface, you might want to install
the file `emacs/fi-stella.el', since it sets up proper indentation for
STELLA code and makes looking up STELLA definitions via the `C-c .' or
`M-.' commands work better. Look at the file `emacs/fi-stella.el' for
specific installation instructions.
Removing Unneeded Files
=======================
To save disk space you can remove files that you don't need. For
example, if you are not interested in the C++ version of STELLA, you can
delete the directory `native/cpp'. Similarly, you can remove
`native/java' to eliminate all Java-related files. You could do the
same thing for the Lisp directory `native/lisp', but (in our opinion)
that would make it less convenient for you to develop new STELLA code.
Finally, if you don't need any of the STELLA sources, you can delete
the directory `sources/stella'. If you don't need local copies of the
STELLA documentation, you can delete parts or all of the
`sources/stella/doc' directory.
Questions and Comments
======================
Please send mail to Hans Chalupsky <[email protected]> or Tom Russ <[email protected]>.