Installing JoCaml on a Unix machine
            -----------------------------------

CONTEXT
  The JoCaml system is a modification of the Objective Caml system.
  As such, JoCaml installation is derived from Objective Caml installation.

  This distribution includes the 'INSTALL' file of Objective Caml under
  the name 'INSTALL_OCAML'. Here we focus on differences with Objective
  Caml installation.


* They are the same as the ones of Objective Caml,

* plus: the POSIX threads library 'phreads' is required.


INSTALLATION INSTRUCTIONS

1- Configure the system. From the top directory, do:

        ./configure

With respect to Objective Caml the "configure" script options are modified
as follows.

Suppressed options.

* All option relative to labltk are suppressed, since labltk is not supported.

* The -with-pthread and -no-pthread options are suppressed, JoCaml cannot
  be build without the native POSIX thread library.

Added options.

   JoCaml may have a 'companion' Objective Caml, so as to allow
   object level compatibility beetween JoCaml and OCaml. There are
   severe restructions: the version numbers of both systems should match.

-ocamlc <ocamlc bytecode compiler>
   If <ocamlc bytecode compiler> is executable, then the script runs it,
   to check version number and, when it matches with JoCaml version number,
   to extract the location of the Objective Caml library.
     By default, this option is activated with value 'ocamlc'

-ocamllib <dir>
   The Objective Caml library is <dir>. No version check is performed. Use
   this option at your own risk.

2- From the top directory, do:

        make world

This builds the JOCaml bytecode compiler for the first time.  This
phase is fairly verbose; consider redirecting the output to a file:

        make world > log.world 2>&1     # in sh
        make world >& log.world         # in csh

3- (Optional) To be sure everything works well, you can try to
bootstrap the system --- that is, to recompile all OCaml sources with
the newly created compiler. From the top directory, do:

        make bootstrap

or, better:

        make bootstrap > log.bootstrap 2>&1     # in sh
        make bootstrap >& log.bootstrap         # in csh

The "make bootstrap" checks that the bytecode programs compiled with
the new compiler are identical to the bytecode programs compiled with
the old compiler. If this is the case, you can be pretty sure the
system has been correctly compiled. Otherwise, this does not
necessarily mean something went wrong. The best thing to do is to try
a second bootstrapping phase: just do "make bootstrap" again.  It will
either crash almost immediately, or re-re-compile everything correctly
and reach the fixpoint.

4- If your platform is supported by the native-code compiler (as
reported during the autoconfiguration), you can now build the
native-code compiler. From the top directory, do:

        make opt

5- Compile fast versions of the OCaml compilers, by compiling them
with the native-code compiler (you have only compiled them to bytecode
so far).  Just do:

        make opt.opt

6- You can now install the JoCaml system. This will create the
JoCaml commands (in the binary directory selected during
autoconfiguration).

An alternative, and faster approach to steps 2 to 5 is

        make world.opt          # to build using native-code compilers

The result is equivalent to "make world opt opt.opt", but this may
fail if anything goes wrong in native-code generation.

6- You can now install the OCaml system. This will create the
following commands (in the binary directory selected during
autoconfiguration):

        jocamlc           the batch bytecode compiler
        jocamlopt         the batch native-code compiler (if supported)
        jocamlrun         the runtime system for the bytecode compiler
        jocamlyacc        the parser generator
        jocamllex         the lexer generator
        jocaml            the interactive, toplevel-based system
        jocamlmktop       a tool to make toplevel systems that integrate
                         user-defined C primitives and Jocaml code
        jocamldep         generator of "make" dependencies for Jocaml sources

and also, if you built them during step 5,

        jocamlc.opt       the batch bytecode compiler compiled with jocamlopt
        jocamlopt.opt     the batch native-code compiler compiled with jocamlopt
        jocamllex.opt     the lexer generator compiled with jocamlopt

From the top directory, become superuser and do:

        umask 022       # make sure to give read & execute permission to all
        make install

The JoCaml commands are Ocaml commands prefixed by 'j'.
That is jocamlc, jocamlopt, jocamlrun, jocamlyacc, jocamllex, jocaml,
jocamlmktop, jocamlmklib, jocamldep.
Plus some of those suffixed by .opt, if you performed step 5.


Some of OCaml commands have no JoCaml equivalent: ocamldebug,
ocamlprof, ocamlcp, ocamldoc.

8- (Optional) The emacs/ subdirectory contains Emacs-Lisp files for an
OCaml editing mode and an interface for the debugger.  To install
these files, change to the emacs/ subdirectory and do

        make EMACSDIR=<directory where to install the files> install
or
        make install

In the latter case, the destination directory defaults to the
"site-lisp" directory of your Emacs installation.

9- After installation, do *not* strip the ocamldebug and ocamlbrowser
executables.  (These are mixed-mode executables, containing both
compiled C code and OCaml bytecode; stripping erases the bytecode!)
Other executables such as ocamlrun can safely be stripped.

IF SOMETHING GOES WRONG:

Refer to the same section in file INSTALL_OCAML.