README

                             HOL LIGHT

HOL Light is an interactive theorem prover / proof checker. It is
written in Objective CAML (OCaml) and uses the toplevel from OCaml as
its front end. This is the HOL Light homepage:

        http://www.cl.cam.ac.uk/~jrh13/hol-light/index.html

and this is the root of the Github code repository:

        https://github.com/jrh13/hol-light

Basic installation instructions are below. For more detailed information
on usage, see the Tutorial:

        http://www.cl.cam.ac.uk/~jrh13/hol-light/tutorial.pdf

Refer to the reference manual for more details of individual functions:

        http://www.cl.cam.ac.uk/~jrh13/hol-light/reference.html (HTML files)
        http://www.cl.cam.ac.uk/~jrh13/hol-light/reference.pdf (one PDF file)

        *       *       *       *       *       *       *       *

                             INSTALLATION

If you use Debian Linux or some other Debian-based Linux distribution
(Knoppix, Mint, Ubuntu, etc.), there is actually a "hol-light" package,
thanks to Hendrik Tews, so installation of HOL Light and all its
prerequisites is as simple as

  sudo apt-get install hol-light

For other OSs, more work is involved. The Objective CAML (OCaml)
implementation is a prerequisite for running HOL Light. HOL Light
should work with any recent version of OCaml; I've tried it on at
least 3.04, 3.06, 3.07+2, 3.08.1, 3.09.3, 3.10.0, 3.11.2, 4.00,
4.05 and 4.14.
However, for versions >= 3.10 (in 3.10 there was an incompatible
change in the camlp4 preprocessor) you will also need to get camlp5
(version >= 4.07). For versions >= 4.14, you will need to get camlp5
8.00 and ocamlfind. Installing these items should not be
too difficult, depending on the platform.

 1. OCaml: there are packages for many Linux distributions. For
    example, on a debian derivative like Ubuntu, you may just need
    to do the following:

        sudo apt-get install ocaml

    Alternatively you can download binaries directly, or get sources
    and build them (which in my experience is usually trouble-free).
    See the OCaml Web page for downloads and other information.

        http://caml.inria.fr/ocaml/index.en.html

 2. num: The HOL Light system uses the OCaml "Num" library for rational
    arithmetic. As of OCaml 4.06, this is no longer included in
    the core system and will need to be added separately. You can
    do this using the OCaml package manager "opam" if you use it by

        opam install num

    Alternatively you can download the sources from here

        https://github.com/ocaml/num

    and build and install them following the instructions on that
    page, for example

        git clone https://github.com/ocaml/num mynums
        cd mynums
        make all
        sudo make install [assuming no earlier errors]

 3. camlp5: this is needed to run HOL Light under any OCaml >= 3.10.
    Somtimes you need a recent version of camlp5 to be compatible with
    your OCaml. For example, OCaml 4.05 is compatible with camlp5 7.10 and
    OCaml 4.14 is compatible with camlp5 8.02. I recommend downloading
    the sources for a recent version from

        https://github.com/camlp5/camlp5/releases ('tags' tab has full series)

    and building it in "strict" mode before installing it, thus:

        cd software/camlp5-rel701 [or wherever you unpacked sources to]
        ./configure --strict
        make
        sudo make install       [assuming no earlier errors]

    There are also packages for camlp5, so you may be able to get away
    with just something like

        sudo apt-get install camlp5

    or

        opam pin add camlp5 <version (e.g., 7.10 for ocaml 4.05)>

    However, you may get a version in "transitional" instead of
    "strict" mode (do "camlp5 -pmode" to check which you have).

Now for HOL Light itself. The instructions below assume a Unix-like
environment such as Linux [or Cygwin (see www.cygwin.com) under
Windows], but the steps automated by the Makefile are easy enough to
invoke manually. There's more detail on doing that in the Tutorial.

(0) You can download the HOL Light sources from the Github site.
    For example, the following will copy the code from the trunk of the
    Github repository into a new directory 'hol-light':

        git clone https://github.com/jrh13/hol-light.git

    The above is now the recommended way of getting HOL Light. There
    are also gzipped tar files on the HOL Light Web page, but they are
    only for quite old versions and will probably be difficult to use
    with recent versions of OCaml.

    You should next enter the 'hol-light' directory that has been
     created:

        cd ./hol-light

There are now two alternatives: launch the OCaml toplevel and directly
load the HOL Light source files into it, or create a standalone image
with all the HOL Light sources pre-loaded. The latter is more
convenient, but requires a separate checkpointing program, which may not
be available for some platforms. First the basic approach:

(1) Do 'make'. This ought to build the appropriate syntax extension
    file ('pa_j.cmo') for the version of OCaml that you're using. If you
    have the camlp4 or camlp5 libraries in a non-standard place rather
    than /usr/local/lib/ocaml/camlp4 or /usr/local/lib/ocaml/camlp5
    then you may get an error like this

      Error while loading "pa_extend.cmo": file not found in path.

    in which case you should add the right directory to CAMLP4LIB or
    CAMLP5LIB, e.g.

      export CAMLP5LIB=$HOME/mylib/ocaml/camlp5

(2) Do 'ocaml'. (Actually for OCaml >= 4.02 I prefer 'ocaml -safe-string'
    to avoid mutable strings, while you may need something else like
    'ocamlnum' on some platforms --- see [*] below.) You should see a
    prompt, something like:

                Objective Caml version 4.01.0

        #

    If you are using OCaml 4.14, you need to create a top-level OCaml
    using 'ocamlmktop -o ocaml-hol' and use 'ocaml-hol' because the default
    'ocaml' does not have 'compiler-libs' that is necessary to run HOL Light.

(3) At the OCaml prompt '#', do '#use "hol.ml";;' (the '#' is part of the
    command, not the prompt) followed by a newline. This should rebuild
    all the core HOL Light theories, and terminate after a few minutes
    with the usual OCaml prompt, something like:

        val search : term list -> (string * thm) list = <fun>
        - : unit = ()
        File "help.ml" already loaded
        - : unit = ()
        - : unit = ()
        - : unit = ()
                Camlp5 parsing version 7.03

        #

    HOL Light is now ready for the user to start proving theorems. You
    can also use the load process (2) and (3) in other directories, but
    you should either set the environment variable HOLLIGHT_DIR to point
    to the directory containing the HOL source files, or change the
    first line of "hol.ml" to give that explicitly, from

        let hol_dir = ref (try Sys.getenv "HOLLIGHT_DIR" with Not_found -> Sys.getcwd());;

    to, for example

        let hol_dir = "/home/johnh/hol-light";;

    or

        let hol_dir = "/usr/share/hol";;

Now for the alternative approach of building a standalone image.
The level of convenience depends on the checkpointing program you
have installed. As of 2024, there are three programs you can use.

(1) DMTCP: you can download from here:

        https://github.com/dmtcp/dmtcp/releases

    To build DMTCP, please refer to
    https://github.com/dmtcp/dmtcp/blob/master/INSTALL.md .
    HOL Light does not have convenient commands or scripts to exploit DMTCP,
    but you can proceed as follows:

        1. Start ocaml running under the DMTCP coordinator:

              dmtcp_launch ocaml

        2. Use ocaml to load HOL Light as usual, for example:

              #use "hol.ml";;

        3. From another terminal, issue the checkpoint command:

             dmtcp_command -kc

           This will kill the ocaml process once checkpointing is done.

        4. Step 3 created a checkpoint of the OCaml process and
           a shell script to invoke it, both in the directory in
           which ocaml was started. Running that should restore
           the OCaml process with all your state and bindings:

             ./dmtcp_restart_script.sh

(2) CRIU: CRIU is similar to DMTCP but faster. However, it requires sudo
    priviledge depending on your environment (e.g., WSL2).
    you can download from here:

        https://criu.org/Download/criu

    To build CRIU, please refer to https://criu.org/Installation .
    To checkpoint,

        1. Start ocaml process and load HOL Light.

        2. From another terminal, run

            criu dump -o dump.log -t <ocaml process id> --shell-job

        3. To restore, run

            criu restore -o restore.log --shell-job

    Please refer to https://criu.org/Simple_loop for details.

(3) selfie: This is a convenient OCaml checkpointing tool developed by
    Quentin Carbonneaux. Please git clone git://c9x.me/selfie.git and
    run `make selfie.cma` from the directory.
    Open ocaml and run

        # #load "selfie.cma";;
        # #use "selfie.ml";;

    Now you can use `snap "output.img";;` to checkpoint the process.


The directories "Library" and "Examples" may give an idea of the
kind of thing that might be done, or may be useful in further work.

Thanks to Carl Witty for help with Camlp4 porting and advice on
checkpointing programs.

        *       *       *       *       *       *       *       *

[*] HOL Light uses the OCaml 'num' library for multiple-precision
rationals. On many platforms, including Linux and native Windows, this
will be loaded automatically by the HOL root file 'hol.ml'. However,
OCaml on some platforms (notably Cygwin) does not support dynamic
loading, hence the need to use 'ocamlnum', a toplevel with the 'num'
library already installed. You can make your own with:

    ocamlmktop -o ocamlnum nums.cma