How to compile the Moscow ML compiler for Win32:

(1) Edit mosml/src/Makefile.inc, and compile the Linux version without
support for dynamically loadable libraries.

(2) In mosml/src/Makefile.inc, uncomment:

# For cross-compiling to Win 32 (from Linux) (development only)
CPP=/lib/cpp -P -traditional -Umsdos -Uunix -Dwin32

(3) Recompile libraries, lexer, compiler and tools:
	
	(cd mosmllib; make clean all)
	(cd lex; make clean all)
	(cd compiler; make clean all)
	(cd toolssrc; make clean all)

Now Win32 compatible executables are found in compiler/mosmlcmp,
compiler/mosmllnk, compiler/mosmltop, lex/mosmllex, toolssrc/mosmldep,
and toolssrc/cutdeps.

----------------------------------------------------------------------

How to compile the Moscow ML compiler for DOS (assuming the runtime
system is unmodified):

You will need: 
    * the Moscow ML sources
    * the djgpp compiler
    * the perl utility
    * a working runtime system (camlrun) version 0.7m1 for Moscow ML


Initial compilation:
 
(1) To initially compile the entire system (except the runtime
    system), execute
	make world 
    in directory mosml/src.  

(2) If you DO NOT have the binaries, then execute
	make install
    in directory mosml/src.  This installs mosmltop, mosmlcmp, and mosmllnk
    in directory mosml/lib, and the small C executables mosml and mosmlc
    in directory mosml/bin.  These executables invoke the runtime system 
    (camlrun) to read and execute the bytecode files mosmltop etc.

Recompilation:

(1) To recompile just the compiler (the top-level system mosmltop, the
    batch compiler mosmlcmp, and the batch linker mosmllnk), execute
	make clean all
    in mosml/src/compiler.

(2) [Do this only if you are quite certain that the new version works]
    To make the newly compiled version the current one, execute
	make install
    in mosml/src/compiler.  This copies the fresh mosmltop, mosmllnk, and
    mosmlcmp to mosml/lib.  It leaves the bytecode files in mosml/src
    unchanged.  This intentional.


There are two binding times in the making of the batch compiler:

	compilation mosmlc -c (bytecode)
	linking     mosmlc -o (C primitives and libraries)

	When compiling user source code, the compiler reads and uses
	the current libraries, not those that existed when the
	compiler itself was built.

There are three binding times in the making of the interactive system:

	compilation    mosmlc -c (bytecode)
	linking        mosmlc -o (C primitives, libraries used inside mosml)

	When compiling code entered at top-level, or compiling via 
	function compile, the interactive system reads and uses the
	current libraries, not those that existed when the top-level
	system itself was built.

Bytecode instructions: The set of bytecode instructions is defined in
runtime/interp.c and runtime/instruct.h, which must agree.  File
compiler/Opcodes.sml is derived automatically from runtime/instruct.h.
The bytecode generated by the compiler (mosmlcmp and mosmltop) depends
on Opcodes.sml.  The bytecode can run only on the runtime system for
which it is generated.

C primitives: The set of C primitives is defined by the collection of
runtime/ files listed in variable PRIMS in runtime/Makefile; the C
primitives are the functions annotated with /* ML */ in those files.
File runtime/primitives is derived automatically from PRIMS and those
files.  File compiler/Prim_c.sml is derived automatically from
runtime/primitives.  The linking performed by the linker mosmllnk and
the load function in mosmltop depends on Prim_c.sml.  A file linked
for a given runtime system can run only on that system.

Libraries: The batch compiler (mosmlcmp and mosmllnk) and the lexer
generator (mosmllex) are fully linked and independent of the libraries
at runtime.

The interactive system (mosmltop) depends on the libraries present at
runtime, not for its internal operation, but for the initial
environment seen by the user.  File compiler/Config.mlp determines
which libraries are loaded and which are open in the initial
environment in the interactive system.



Bytecode, exceptions and global arguments:

In src/runtime, files interp.c and instruct.h must agree on the
defined bytecode instructions; compiler/Opcodes.sml is derived from the
latter.  


The compiler back-end's internal representation of bytecode
instructions is defined in src/compiler/Prim.sml.  When adding a new
instruction, file src/compiler/Emitcode.sml must be updated to emit
code if the new primitive takes an argument; whereas file
src/compiler/Prim_opc.sml must be updated if the new primitive is
argumentless.  File src/compiler/Pr_lam.sml must be updated to print
the new primitive.  Finally, file src/compiler/Primdec.sml, which maps
string names to the internal representation, may be updated if the new
primitive needs to be externally visible (that is, usable in prim_val
declarations).

The compiler front-end's internal representation of SML primitives is
defined in src/compiler/Smlprim.sml; for binary primitives there are
usually two versions: MLPxxx and MLPxxx_c, where the latter is for a
fully applied version, which can be evaluated more efficiently.  The
mapping to the bytecode primitives is done in file
src/compiler/Front.sml, which also takes care of the optimization for
fully applied primitives.  The front-end primitives are usually used
when defining SML pervasives in src/compiler/Smlperv.sml.

Files src/compiler/Smlexc.sml and src/runtime/fail.h must agree on the
exceptions they define, since the latter is used to generate
src/compiler/Predef.sml, which is read by Symtable.sml and hence used
in the compiler.


Bootstrapping, after extending the set of C primitives
------------------------------------------------------

(1) Compile everything 
    and make a backup of camlrunm, mosmllnk, mosmlcmp, mosmllex
(2) Extend the set of primitives
(3) Recompile runtime
(4) Relink mosmllnk 
(5) Promote mosmllnk to src/
(6) Relink mosmllnk, mosmlcmp, mosmllex
(7) Promote mosmllnk, mosmlcmp, mosmllex to src/
(8) Promote camlrunm to src/
(9) Recompile everything again


Cross-compiling from Linux to DOS
---------------------------------

0. In mosml/src, 
	make clean world

1. In mosml/src/runtime, edit Makefile to have
	PRIMS=$(DOSPRIMS)

2. Do
	rm primitives prims.c
	make prims.c

3. In mosml/src/compiler, 
	make mosmllnk
	mv mosmllnk ../mosmllnk.dos

4. Edit mosml/src/Makefile.inc to have
	CPP=/lib/cpp -P -traditional -Uunix -Dmsdos

5. In mosml/src/mosmllib
	make clean all

6. In mosml/src/compiler
	make clean dos

7. Move files mosmllnk and mosmlcmp to DOS (/cdisk/mosml/src).
   These are now compatible with the DOS version of the runtime.

8. To bootstrap the DOS version, copy all sources to DOS, 
   copy compile/Lexer.{sig.sml} to DOS, 
   and do 
	make
   in mosmllib and compiler.
   Recompile mosmllex and toolssrc.
   Then promote the generated mosmllnk and mosmlcmp, 
   and do 
	make clean world
   in mosml/src.

