![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to INSTALL 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 INSTALL CVS log | Up to [Research Unix] / researchv10no / cmd / sml / doc |
1.1 root 1: Installing Standard ML of New Jersey
2:
3: Standard ML of New Jersey currently runs on the following systems, subject
4: to the noted restrictions:
5:
6: Vaxes running 4.[2,3]BSD Unix, V9 Unix, or Ultrix:
7: The floating point functions will work only on Vaxes which support g_floats.
8: (This includes VAX-8xxx, MicroVAX II, and MicroVAX III machines)
9:
10: Sun 3 workstations:
11: The floating point functions will work only on Suns with the MC68881 chip,
12: but the floating point coprocessor is not required to install and run
13: the compiler.
14:
15: Sun 4 workstations
16:
17: NeXT workstations
18:
19: Encore Multimax
20:
21: [DECstation {2,3}100]
22:
23: If you have trouble installing the system, please send us a request for
24: help, including the version of the compiler (check the definition of the
25: "version" variable in src/boot/perv.sml if in doubt), hardware
26: configuration (machine type and memory size), operating system, and an
27: input/output script showing the problem.
28:
29: The compiler can be used both interactively and in "batch" mode. Batch
30: mode provides an insecure precursor of separate compilation that we use to
31: bootstrap the compiler. Most users will want to use the interactive
32: system, but a description of the batch system is provided in
33: src/doc/BATCHINSTALL for those expert users who wish to modify the
34: compiler, cross compile, or support a large program of their own. The rest
35: of this file tells you how to install the interactive version.
36:
37:
38: Installation script -- makeml
39:
40: The makeml shell script (src/makeml) is described by its man page, doc/makeml.1.
41: The most important options describe the hardware architecture, the operating
42: system, and the sharing mode.
43:
44: (1) machine -- the target machine:
45:
46: -sun3
47: -m68 Sun 3 workstations using the MC68020 processor (MC68881 assumed)
48:
49: -vax Vaxes supporting g_floats
50:
51: -sun4
52: -sparc Sun 4 workstations and SPARCstations
53:
54: -next NeXT machine
55:
56: -envcore Encore Multimax (NS32032 processor)
57:
58: (2) os -- the operating system of the target machine:
59:
60: -bsd various BSD-based Unix systems
61: -ultrix Ultrix on Vax or DECstations
62: -v9 a local Bell Labs Unix variety (Vax only)
63:
64: These options are only necessary for the Vax architecture. The other
65: architecture options imply -bsd.
66:
67: (3) sharing mode -- specifies whether compiler object code is sharable:
68:
69: -noshare minimize the size of the runtime system (for exportFn)
70:
71: By default the sml image will be built with the compiler object code
72: read-only and sharable (linked into the Unix text segment of the
73: runtime system, runtime/run). This helps save memory on systems
74: supporting several concurrent sml users, and also improves garbage
75: collector performance.
76:
77: However, there is a problem when "exportFn" is used to create an
78: executable image from within a sharable compiler: the exported image
79: will include the compiler object code and thus be considerably larger
80: than necessary. So when you are planning to create an image using
81: exportFn you should use an sml with a minimal runtime system. The
82: "-noshare" option creates such an sml, by loading the compiler object
83: code into the ML heap instead of linking it into the runtime system
84: text segment. [The batch loader can also be used to create stand-alone
85: ML programs. See doc/BATCHINSTALL.]
86:
87:
88: Building an sml [vax and mc680x0 versions]
89:
90: We assume that the Standard ML distribution is set up as a directory
91: mldist containing subdirectories src, mo.m68, and mo.vax. The following
92: instructions assume that mldist is the current directory.
93:
94: 1. Go to the src subdirectory of mldist:
95:
96: cd src
97:
98: 2. Run makeml with appropriate command line options, e.g.:
99:
100: makeml -sun3 -noshare (for Sun3 workstations, not sharing)
101: makeml -vax -bsd (for Vaxes running 4.2/4.3 BSD, shared object code)
102: makeml -vax -ultrix (for Vaxes running V9 Unix)
103:
104: NOTE: Make sure that the directories src and src/runtime are
105: writable by the user running the makeml script.
106:
107: The building of the sml system proceeds in three phases. First the
108: runtime system is compiled with the appropriate options. Then the sml
109: object files (from mo.vax or mo.m68 as appropriate) are loaded and
110: executed. Finally the files in src/boot are compiled to initialize
111: the static environment. Each of these phases prints characteristic
112: messages on the standard output. After the interactive sml has been
113: built, an image will be exported to a file named "sml" and the makeml
114: command will exit (the -i option allows one to specify a different name
115: for the exported image).
116:
117: 3. Install the executable image "sml" produced by step 2 in an
118: appropriate bin directory on your machine, e.g. /usr/local/bin:
119:
120: cp sml /usr/local/bin
121:
122: (You may need system administrator privileges for this step.) Once
123: installed, the interactive system can be run by executing the command
124: "sml". The system will start up by printing a version message, then
125: the top-level prompt "-", indicating that you can now start typing to
126: the interactive system.
127:
128:
129: Cross compiling objects for other architectures
130:
131: If you wish to install the system on architectures other than the Vax
132: or MC680x0, you will first have to build a directory containing the
133: object files for that architecture (mo.sparc, mo.ns32, etc.). The
134: batch compiler instructions in doc/BATCHINSTALL explain how to do
135: this.
136:
137:
138: Managing memory use
139:
140: ML provides automatic storage management through a garbage-collected
141: heap. Since the heap is used intensively, choice of heap size can
142: have a significant impact on performance. The compiler determines an
143: efficient heap size automatically on startup, resizes the heap up or
144: down as the amount of live data changes, and complains if it runs out
145: of memory (the interactive system can be booted in approximately 3
146: megabytes).
147:
148: There are three parameters of the runtime system that help determine the
149: size of the heap. They are defined by the -h, -r, and -m command line
150: options of makeml.
151:
152: The options are
153:
154: -h i set the initial heap size to i Kbytes (i a positive integer)
155:
156: -r j the desired ratio between the size of live data and the size
157: of the heap is set to j, a positive integer greater than or
158: equal to 3 (the default is j=5)
159:
160: -m k set the soft maximum heap size (softmax) to k Kbytes (k a
161: positive integer), with the default being k=100,000 (i.e. 100MB)
162:
163: -g l set the g.c. message level to l, where l is 0,1,2, or 3
164:
165: The -h option only has an effect on the initial phase of execution up
166: to the first major garbage collection, at which time the heap size
167: will be automatically resized as dictated by the ratio and softmax
168: parameters. Using a large -h value can speed up the building of the
169: system when lots of memory is available.
170:
171: The -g option specifies how much information is printed about garbage
172: collections. The value l=0 suppresses all garbage collection
173: messages, l=1 causes messages to be printed for major collections, l=2
174: adds messages for heap resizing, and l=3 adds messages for minor
175: collections and failure to maintain the desired ratio. The default is
176: l=2.
177:
178: In general, the larger the heap size, the lower the garbage collection
179: overhead. In principle, heap size is limited by the total virtual memory
180: available to a process. In practice, since heavy paging will slow down a
181: program drastically, it is desirable to keep heap size within the bounds of
182: available physical memory, taking into account the memory requirements of
183: other processes sharing the physical memory. Setting a high ratio will
184: cause the compiler to be aggressive in its use of memory, while setting a
185: reasonable limit on heap size can prevent excessive paging. The maximum
186: heap size can be controlled externally by using the "limit datasize"
187: command in the C shell. For instance, on an 8MB Sun 3 you might execute
188: the shell command
189:
190: limit datasize 6M
191:
192: before running sml. This would prevent the heap from growing larger
193: than 6 MB regardless of the value of the ratio. This is a hard limit,
194: so it might cause a program to run out of memory and fail even though
195: plenty of virtual memory is available.
196:
197: The soft maximum heap size (softmax) specified with the -m option is a
198: less drastic way of controlling the system's appetite for memory. The
199: heap will grow larger than softmax only when necessary to maintain a
200: ratio of 3. Thus when softmax is reached, the heap will not grow
201: until the size of live data is one third of softmax, and thereafter it
202: will grow more slowly than with the default ratio of 5 (or the user
203: defined ratio). A reasonable strategy is to set softmax to the
204: maximum amount of physical memory that you know will be available and
205: set ratio to a high value (e.g. 20), so that the heap size will tend
206: to stick at softmax, thereby taking advantage of available memory.
207:
208: The ratio and softmax parameters can also be changed at any time from
209: within sml since they are the values of the variables
210:
211: System.Control.Runtime.ratio: int ref,
212: System.Control.Runtime.softmax: int ref.
213:
214: For example,
215:
216: makeml ... -r 20 -m 4096
217:
218: might be appropriate at a site where most users are running small to
219: medium size programs on machines with 8MB physical memory. [We would
220: appreciate feedback concerning which settings seem to work best in
221: your situation.] The defaults can also be changed by editing their
222: definitions in the file src/runtime/run.c.
223:
224: The runtime system (src/runtime/run) can be exectuted directly,
225: without using the makeml script, and it accepts the -h, -r, and -m options
226: as well.. The command synopsis is
227:
228: run [-h i] [-r j] [-m k] [-g l] module
229:
230: The parameter "module" is the name of a module whose object file,
231: namely src/mo/<module>.mo, is to be loaded and executed (along with
232: any other modules on which it depends). IntVax and IntM68 are typical
233: module arguments; they define the interactive top level loops for the
234: Vax and MC68020 versions of the compiler, respectively.
235:
236:
237:
238: WARNING: recompile runtime for different OS versions
239:
240: When transferring the system between Sun 3's running different
241: versions of SunOS (say 3.x and 4.0), the sml object code files in
242: mo.m68 can be copied without change -- they do not need to be
243: regenerated. However, the runtime system *must* be recompiled
244: when moving the system to a different version of Unix, even if the
245: same arguments would be used with makeml. This remark also
246: applies to Vaxes running different versions of Unix (4.3BDS and
247: Ultrix, for instance). The best approach is to transfer at least
248: the runtime sources (src/runtime) and src/boot and run the makeml
249: script with appropriate arguments on the new system.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.