Home My Page Projects Code Snippets Project Openings SML/NJ
Summary Activity Forums Tracker Lists Tasks Docs Surveys News SCM Files

SCM Repository

[smlnj] Annotation of /archive/mlsave.11/INSTALL
ViewVC logotype

Annotation of /archive/mlsave.11/INSTALL

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4054 - (view) (download)

1 : dbm 4054 Standard ML Compiler of New Jersey
2 :     Beta 1 Release, November 2, 1987
3 :    
4 :    
5 :     Installing and Booting SML
6 :    
7 :     Files:
8 :    
9 :     The distribution comes as a directory mlcomp.b1 (b1 stands for beta 1).
10 :     It includes source and object code for Sun3 workstations and Vaxes running
11 :     either 4.3BSD or V9 Unix. G_floating point is required for the Vax
12 :     version.
13 :    
14 :     The contents of this directory are as follows (as printed by ls -F):
15 :    
16 :     INSTALL all build/ m68/ print/ util/
17 :     README basics/ codegen/ mo.m68/ runtime/ vax/
18 :     VERSION bignums/ env/ mo.vax/ translate/
19 :     absyn/ boot/ lex/ parse/ typing/
20 :    
21 :    
22 :     INSTALL
23 :     This file.
24 :    
25 :     README
26 :     Description of this release.
27 :    
28 :     VERSION
29 :     This contains the version number and date, together with an incremental
30 :     log of of changes and a list of known bugs and omissions.
31 :    
32 :     all
33 :     This is a command script for the batch compiler. It is used to generate
34 :     new object files from the compiler source files.
35 :    
36 :     mo.m68, mo.vax
37 :     mo.m68 and mo.vax contain the object files for all the compiler's modules.
38 :     The compiler generates an object file for each module (structure or functor).
39 :     The object file for a module named A will be named A.mo.
40 :    
41 :     absyn/, basics/, etc
42 :     These directories contain the source code for the compiler, organized
43 :     as a collection of subsystems.
44 :    
45 :     runtime/
46 :     This directory contains the c and assembly source files for building
47 :     the runtime system.
48 :    
49 :    
50 :     The batch compiler:
51 :    
52 :     To support bootstrapping, we have been using an insecure precursor of separate
53 :     compilation. We have a "batch", or file-oriented, version of the compiler
54 :     that generates a ".mo" object file for each module compiled. The program
55 :     accepts commands on its standard input. The list of commands is:
56 :    
57 :     !file => compile the file.
58 :     *file => assemble the file.
59 :     <file => parse the file.
60 :     >file => export to a file.
61 :     % => print the last generated lambda (intermediate code).
62 :     #word => comment; ignored.
63 :     @directory => look for files in a directory. directory should end in /.
64 :     ~function => execute a function.
65 :     ^flag => toggle a flag.
66 :     ? => print this help message.
67 :    
68 :     There should be no space between the command character and the argument
69 :     string. Arguments should not be quoted.
70 :    
71 :     The compile command, "!", causes the named file to be compiled, generating an
72 :     object file A.mo for each module A defined in the file. The assemble
73 :     command, "*", generates an assembly listing A.s (this file can be assembled
74 :     to produce the corresponding .mo file). The parse command, "<", causes the
75 :     file to be parsed and type-checked, but produces no output files. These
76 :     three commands all update the symbol table with the bindings defined in the
77 :     file. The file must contain only signature, structure, and functor
78 :     declarations.
79 :    
80 :     The export command ">" exports the current state of the compiler to an
81 :     executable file with the given name. This is a way of preserving the
82 :     symbol table state of the compiler.
83 :    
84 :     The execute ("~") and toggle ("^") commands are mainly used to control debugging
85 :     facilities, which are not explained here. Typing "^" alone on a line produces
86 :     a list of possible flags.
87 :    
88 :     The command interpreter is defined in build/compile.sml.
89 :    
90 :    
91 :     To build the runtime system:
92 :    
93 :     Go to the runtime directory, which contains the source code for the runtime
94 :     system. Link the appropriate machine-specific makefile to "makefile".
95 :     makefile.m68 is for Sun3's, makefile.v9 is for Vaxes running V9 Unix, and
96 :     makefile.bsd is for Vaxes running 4.3BSD. Then make the runtime system,
97 :     which produces an executable program called (for no good reason) nml.
98 :    
99 :     1. cd .../mlcomp.b1/runtime
100 :    
101 :     2. ln makefile.{m68 | bsd | v9} makefile
102 :    
103 :     3. make
104 :    
105 :    
106 :     To build an interactive sml:
107 :    
108 :     Go the main ML directory (e.g. mlcomp.b1). Any implicit paths are relative
109 :     to this directory.
110 :    
111 :     1. cd .../mlcomp.b1
112 :    
113 :     Symbolically link mo to mo.m68 for Suns or mo.vax for Vaxes (by default,
114 :     the system loader looks for object files in a directory "mo" in its current
115 :     directory). WARNING: if the wrong object file directory is linked to
116 :     mo, then step 3 will immediately fail.
117 :    
118 :     2. ln -s mo.{m68 | vax} mo
119 :    
120 :     Run runtime/nml with either IntM68 (for the Sun) or IntVax (for Vax).
121 :     This will cause loading and linking of the appropriate object files,
122 :     followed by compilation of the boot files to create the initial static
123 :     environment. The <size> parameter is the size of the initial heap
124 :     semispace in kilobytes; the copy garbage collector uses two semispaces.
125 :     When recompiling the compiler, we use 5000, but much smaller sizes will
126 :     work (the default is 300 if no -h <size> is given). The garbage collector
127 :     will double the arena size if it starts to fill up.
128 :    
129 :     3. runtime/nml -h <size> {IntM68 | IntVax}
130 :    
131 :     The system should print the top-level prompt "-". Now create an executable
132 :     image of the system using the function "exportML" (here we use "sml" as
133 :     the name of the executable, but of course you are free to choose another
134 :     name).
135 :    
136 :     4. exportML "sml";
137 :    
138 :     The interactive system can now be exited by typing ^D. Then you can run ML
139 :     without having to load the initial environment just by typing "sml" to the
140 :     shell. If you want to add a startup message, just change step 4 to:
141 :    
142 :     4'. (exportML "sml"; print "your message here\n"; ());
143 :    
144 :    
145 :     To build a batch compiler:
146 :    
147 :     Go the main ML directory (e.g. mlcomp.b1). Symbolically link the
148 :     appropriate object directory, mo.m68 (for Sun3) or mo.vax (for Vax) to mo.
149 :    
150 :     1. cd .../mlcomp.b1
151 :    
152 :     2. ln -s mo.{m68 | vax} mo
153 :    
154 :     The object files will be loaded and linked as for compile, and the initial
155 :     environment will be loaded. As a byproduct of this step, a new PervFunc.mo
156 :     file is produced. This file is used by the runtime system to build the
157 :     runtime structure containing the initial environment during bootup.
158 :     Unless you have made changes to the Initial environment and are recompiling
159 :     the entire system, this file will be identical to the PervFunc.mo in
160 :     the mo directory, and can be discarded.
161 :    
162 :     3. runtime/nml -h <size> {CompM68 | CompVax}
163 :    
164 :     When this is successfully completed, the system will prompt with the message
165 :     "hello there". You are now talking to the batch command interpreter.
166 :     Dump an executable image of the batch compiler to a file named "batch"
167 :     (or whatever name you prefer).
168 :    
169 :     4. >batch
170 :    
171 :     5. type ^D to exit.
172 :    
173 :     Now you can run the batch compiler by typing "batch". You can give it
174 :     commands interactively, or by redirecting its input from a file, as is
175 :     done below with the command script all.
176 :    
177 :    
178 :     To boot ML (e.g. after changing some source files):
179 :    
180 :     Use an existing compiler (batch) to generate a new set of object files:
181 :    
182 :     1. go to the main directory (mlcomp.b1)
183 :    
184 :     2. batch < all >& diagnostics &
185 :    
186 :     This will compile all the source files, generating corresponding .mo
187 :     files in the main directory. It will also generate a number of checkpoint
188 :     images, from upto.absyn to upto.all (see the command script all). If there
189 :     are errors, one can use an edited version of all and restart using the last
190 :     checkpoint image preceding the error.
191 :    
192 :     Make a new mo directory, say mo.new, and move the new .mo files into it.
193 :     Also, make sure that the PervFunc.mo that was produced along with the
194 :     compiler batch is also moved or linked into this directory -- .mo files
195 :     compiled by a given instance of the compiler should be loaded together
196 :     with that compiler's PervFunc.mo.
197 :    
198 :     3. mkdir mo.new
199 :     mv *.mo new -- including last PervFunc.mo
200 :    
201 :     4. rm mo; ln -s mo.new mo
202 :    
203 :     5. make a new batch compiler and interactive system as above.
204 :    
205 :     6. As a check, it is suggested that you use the new compiler to
206 :     recompile the source code. The resulting .mo files should be
207 :     identical to previous set of .mo files. Sometimes more than
208 :     one iteration is necessary (for example if the INITIAL
209 :     signature in boot/perv.sml has changed). The bootstrapping is
210 :     successful when two successive iterations produce identical
211 :     .mo files.
212 :    
213 :     As a shortcut, if some files are changed in ways that do not affect
214 :     the relevant signatures, these files alone can be compiled using the
215 :     upto.all checkpoint image and the resulting .mo files substituted for
216 :     the old versions. This avoids the time-consuming process of recompiling
217 :     the entire system.
218 :    
219 :    
220 :     Cross compiling:
221 :    
222 :     To cross-compile object code for the Vax on a Sun, for instance, make
223 :     a Vax compiler using
224 :    
225 :     runtime/nml -h <size> CompVax
226 :     ...
227 :     "hello there"
228 :     >mlc.vax
229 :    
230 :     Then use mlc.vax to generate .mo files and place them in a directory mo.vax,
231 :     along with the PervFunc.mo generated when building mlc.vax. These object
232 :     files can then be moved to a Vax and used to build a new batch compiler and
233 :     interactive system. To cross-compile Sun code on a Vax, use CompM68
234 :     to build a Sun compiler mlc.m68 on the vax and then use mlc.m68 to
235 :     produce the Sun object files, which are placed in mo.m68.

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0