Return to INSTALL CVS log

Up to [Research Unix] / researchv10no / cmd / sml / doc

Annotation of researchv10no/cmd/sml/doc/INSTALL, revision 1.1

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.