![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to BATCHINSTALL CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10no / cmd / sml / doc|
Return to BATCHINSTALL CVS log | Up to [Research Unix] / researchv10no / cmd / sml / doc |
1.1 root 1: Standard ML of New Jersey's Batch Compiler
2:
3: Description:
4:
5: The Standard ML of New Jersey batch compiler provides some (unsafe)
6: separate compilation and cross compilation capabilities. The batch system
7: compiles files containing signature, structure, and functor declarations,
8: i.e. only module level declarations are allowed. Compiling a module "Foo"
9: produces a corresponding object file "Foo.mo", which contains the names of
10: the other .mo files required to build the module, as well as the code of
11: the module itself. Modules are compiled separately, producing the
12: necessary .mo files.
13:
14: A program is executed by passing a module name to the run-time system
15: with the command (assuming src is current working directory):
16:
17: runtime/run [memory managment options] Module
18:
19: The run-time system starts a linker which loads in the module, finds
20: out what other modules it depends on, recursively loads them and
21: passes them to the original module. The module then "builds" itself,
22: by executing its top-level declarations and creating a run-time
23: structure. By convention, the loader looks for the module object
24: files in the directory src/mo. In this case it would look for an
25: object file named src/mo/Module.mo.
26:
27: For example, batch compiling the following module will create
28: a file named HelloWorld.mo.
29:
30: structure HelloWorld =
31: struct
32: val foo = print "hello world"
33: end
34:
35: When HelloWorld.mo is placed in the directory src/mo and the command
36:
37: runtime/run HelloWorld
38:
39: is executed, the runtime system will build a run-time record
40: containing foo, and as a side effect of building the record, "hello
41: world" will be printed.
42:
43: Thus a program consists of the collection of all modules on which a
44: given top-level structure (transitively) depends. The order in which
45: the modules will be executed/created is determined by a postorder
46: traversal of the (acyclic) dependence graph.
47:
48: Using the batch system for separate compilation is unsafe since the
49: .mo files contain no type information, only the names of the modules
50: on which they directly depend. However, as long as each module has
51: the correct signature, the run-time record will be type-correct; in
52: other words, it is safe to edit, re-compile, and re-link modules as long
53: their signatures do not change.
54:
55:
56: Installation:
57:
58: The compiler is composed of two parts: a run-time system written in C and
59: assembly language; and a number of ML object files which form the main part
60: of the compiler. The run-time system provides garbage collection, signal
61: handling, and system calls; the rest of the compiler, including the
62: standard library, is written in ML. The .mo files for the compiler
63: reside in the mo.vax and mo.m68 subdirectories of the ML distribution.
64: The source for the compiler resides in the src subdirectory, and these
65: instructions assume that the current directory is src.
66:
67: To build a batch compiler:
68:
69: 1. Go to the src subdirectory of mldist:
70:
71: cd src
72:
73: 2. Run the makeml script with the -batch option, e.g.
74:
75: makeml -batch ...
76:
77: The other options for makeml have the same meaning as for the
78: interactive system. See the man page doc/makeml.1.
79:
80: As the command executes, you should see messages like "[Loading Foo]" and
81: "[Executing Bar]", which indicate the modules being linked in, and then
82: messages like "signature ASSEMBLY" and "functor CoreFunc", which
83: indicate that the standard library is being compiled.
84:
85: When the command successfully terminates, an executable image named
86: "batch" has been created in the current directory. This is the batch
87: ML compiler. If you wish to use a different name for this file, use
88: the -i option of makeml.
89:
90: Now you can run the batch compiler by typing "batch". You can give it
91: commands interactively, or by redirecting its input from a file, as is
92: done below with the command script "all".
93:
94:
95: Normally you will want to build a complete interactive or batch
96: system, but there are occasions when you may want to build just the
97: runtime system. The option -run of makeml will do this.
98:
99: When invoked, runtime/run takes the name of a module (say "Foo") as a
100: parameter. It looks for a file with path name mo/Foo.mo relative to
101: the current directory and loads that file, and then recursively loads
102: mo/Bar.mo for all modules Bar on which Foo depends. Finally the code
103: for creating the module Foo is executed. For instance, to run the
104: interactive system on a Vax, one could symbolically link mo to
105: mldist/mo.vax (or ../mo.vax if current directory is src) and execute
106: the command
107:
108: runtime/run IntVax
109:
110: This causes mo/IntVax.mo to be loaded, together with all the modules
111: on which it depends (essentially the whole compiler). IntVax.mo
112: (defined in src/build/glue.sml) causes the interactive top-level loop
113: to be executed when the functor Interactive is applied. Any program can
114: be directly loaded and executed by the runtime system in this manner,
115: not just the compiler.
116:
117: The runtime system accepts the option flags -h, -r, -m, and -g to
118: control heap sizing and garbage collection messages. These are
119: described in doc/INSTALL.
120:
121:
122: Using the batch compiler:
123:
124: The batch compiler accepts commands on its standard input. The list of
125: commands is:
126:
127: !file => compile the file.
128: *file => assemble the file.
129: <file => parse the file.
130: >file => export to a file.
131: % => print the last generated lambda (intermediate code).
132: #word => comment; ignored.
133: @directory => look for files in a directory. directory should end in /.
134: ~function => execute a function.
135: ^flag => toggle a flag.
136: ? => print this help message.
137:
138: There should be no space between the command character and the
139: argument string, which should not be quoted.
140:
141: The execute ("~") and toggle ("^") commands are mainly used to control
142: debugging facilities, which are not explained here. Typing "^" alone
143: on a line produces a list of possible flags.
144:
145: The compile command, "!", causes the named file to be compiled,
146: generating an object file A.mo for each module A defined in the file.
147: The assemble command, "*", generates an assembly listing A.s that can
148: be assembled to produce the corresponding .mo file. The parse
149: command, "<", causes the file to be parsed and type-checked, but
150: produces no output files. These three commands all update the symbol
151: table with the bindings defined in the file. The file must contain
152: only signature, structure, and functor declarations.
153:
154: The export command ">" exports the current state of the batch compiler
155: to an executable file with the given name. This is a way of
156: preserving the symbol table state of the compiler, and is useful for
157: separate compilation; if you change a module without changing its
158: signature, you can safely recompile it using the exported compiler
159: (which contains the symbol table information from other modules that
160: the modified module may require). For example, the file "all" in the
161: src directory is a batch command script for compiling the compiler.
162: The last command in the file exports to a file "upto.all", which can
163: recompile any module of the compiler.
164:
165: Once you have compiled all of your code, you only need to move it to the
166: mo directory and execute it in the same way as CompM68 or CompVax:
167:
168: runtime/run Foo
169:
170: for a module Foo. Note that the files CoreFunc.mo, Math.mo (for Vax),
171: Initial.mo, and Loader.mo must be in the mo directory, as they are
172: used in bootstrapping the system.
173:
174:
175: Recompiling the compiler
176:
177: NOTE: Recompiling the compiler will require a heap size of at least
178: 6MB, so it if possible it should be done on a machine with at least
179: 8MB of physical memory. Use the -m flag of runtime/run to set softmax
180: as high as reasonable (e.g. -m 6000 on an 8MB Sun 3).
181:
182: NOTE: Beware of using the sharable runtime system when recompiling the
183: compiler, since it has the effect of embedding old versions of the .mo
184: files into the system. Either use a nonsharable version of
185: runtime/run, or rebuild a sharable runtime/run after each iteration
186: of compiling the compiler to incorporate the latest .mo files.
187:
188: If you change the compiler, you can use the batch command script "all"
189: to recompile it with the batch system:
190:
191: batch < all
192:
193: or runtime/run {CompM68 | CompVax | CompSparc | CompNS32} < all
194:
195: This will generate new .mo files for all the modules in the compiler including
196: the "boot" modules (whose source files are found in src/boot):
197:
198: CoreFunc.mo [boot/core.sml]
199: Math.mo (used by Vax only) [boot/math.sml]
200: Initial.mo [boot/perv.sml]
201: Loader.mo [boot/loader.sml]
202:
203: These are generated by the "~mBoot" command in the all script rather
204: than using the "!" compile command. These files are treated
205: differently because of their role in bootstraping the pervasive (i.e.
206: built-in) environment.
207:
208: The newly generated .mo files should be moved into a new mo directory,
209: say mldist/mo.new:
210:
211: cd .. (to mldist)
212: mkdir mo.new
213: mv src/*.mo mo.new
214:
215: After generating new .mo files for the compiler (including the boot
216: modules if necessary), you should build a new batch compiler by
217: symbolically linking mldist/mo.new to mldist/src/mo and recompiling
218: the source code again (using the -mo option to makeml to designate the
219: object directory).
220:
221: cd src
222: makeml -batch -mo ../mo.new -vax -bsd ...
223: batch < all
224:
225: The resulting .mo files should be identical to the previous set of .mo
226: files in mo.new. Sometimes more than one iteration is necessary (for
227: example if the signature of one of the boot modules has changed). The
228: bootstrapping is successful when two successive iterations produce
229: identical .mo files.
230:
231: The last command in the all file causes an image of the batch compiler
232: to be saved in the file upto.all. This image contains the symbol
233: table information for all the modules in the compiler. It can be used
234: to recompile individual files in the compiler after they have been
235: modified (but beware of changes in signatures).
236:
237:
238: Cross compiling
239:
240: If you have, say, the Vax object files in mldist/mo.vax and need to build
241: the sparc object files, then you can build a batch compiler to generate
242: sparc object files by using the -target option of makeml:
243:
244: makeml -vax -bsd -target sparc
245:
246: (the -target option implies the -batch option).
247:
248: Then the resulting batch compiler can be used to generate the sparc mo
249: files by executing (in directory src):
250:
251: batch < all
252:
253: Then make a directory mldist/mo.sparc and move the new object files into
254: this directory. These object files can then be used to bootstrap the
255: compiler on a sparc machine in the usual way.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.