jrh13/hol-light - Githubissues

                         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:

    https://hol-light.github.io/

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:

    https://hol-light.github.io/tutorial.pdf

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

    https://hol-light.github.io/references/HTML/reference.html (HTML files)
    https://hol-light.github.io/references/reference.pdf (one PDF file)

    *       *       *       *       *       *       *       *

                         INSTALLATION

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, 4.14, 5.1.0 and 5.2.0.

The easiest way to install HOL Light is through OPAM, an OCaml package manager. After installing OPAM (https://opam.ocaml.org/doc/Install.html), run the following command:

opam install hol_light
# To compile the core module of HOL Light and use, add hol_light_module
# opam install hol_light hol_light_module

This will build 'hol.sh' and copy it at the 'bin' path of your OPAM setting, making it executable at any location.

To manually build HOL Light, OCaml and a few packages that HOL Light depends on are necessary.

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
```
Dependencies: Using OPAM (OCaml package manager) is the easiest way to install dependent packages (https://opam.ocaml.org/doc/Install.html). If you have OPAM installed on your machine, running the following command inside this directory will create a local OPAM switch which uses the latest OCaml version that fully supports features of as well as all dependencies installed:
```
make switch # or 'make switch-5' for OCaml 5
eval $(opam env)
```
To manually install dependencies, the DEPENDENCIES chapter of this document explains it.

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) If you are using a Unix-like environment, simply run ./hol.sh. This should rebuild all the core HOL Light theories, and terminate after a few minutes with the usual OCaml prompt, something like:

            Camlp5 parsing version (HOL-Light) 8.03.00

    #

HOL Light is now ready for the user to start proving theorems.

If you are not using a Unix-like environment, 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.)
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.

At the OCaml prompt '#', do '#use "hol.ml";;' (the '#' is part of the
command, not the prompt) followed by a newline.

You can also use the load process (2) 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 hol.sh running under the DMTCP coordinator and wait until
       HOL Light is loaded:

          dmtcp_launch ./hol.sh

    2. From another terminal, issue the checkpoint command:

         dmtcp_command -kc

       This will kill the process once checkpointing is done.

    3. Step 2 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.

    *       *       *       *       *       *       *       *

                         DEPENDENCIES

zarith or num: The HOL Light system uses the OCaml "Num" library or "Zarith" library for rational arithmetic. If OCaml 4.14 or above is used, HOL Light will use Zarith. You can install it using the OCaml package manager "opam" by
```
opam install zarith
```
If OCaml 4.05 is used, HOL Light will use Num which is included in the core system. If you are using an OCaml version between 4.06 and 4.13, Num must be installed separately because it is no longer included in the core system. You can use "opam" 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]
```
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 and above is compatible with camlp5 8.02 and 8.03. 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).
```
*       *       *       *       *       *       *       *

                 COMPILING HOL LIGHT
```

Running 'HOLLIGHT_USE_MODULE=1 make' will compile hol_lib.ml and generate hol_lib.cmo/hol_lib.cmx. This will also create hol.sh which will configure hol.ml to use the compiled hol_lib.cmo (but not hol_lib.cmx). Compiling HOL Light will only work on OCaml 4.14 or above.

To compile an OCaml file that opens Hol_lib using OCaml bytecode compiler, use the following command. For OCaml native compiler, replace ocamlc with ocamlopt and .cmo with .cmx.

ocamlfind ocamlc -package zarith -linkpkg -pp "`./hol.sh -pp`" \
  -I (HOL dir) (HOL dir)/bignum.cmo (HOL dir)/hol_loader.cmo \
  (HOL dir)/hol_lib.cmo (input.ml) -o (output)

The load functions (loads/loadt/needs) are not available anymore in this approach. Please use 'ocaml inline_loads.ml ' to inline their invocations. For native compilation, if it raises the stack overflow error, either (1) try ocamlopt.byte with OCAMLRUNPARAM=l=(some large number), or (2) increase the stack size using ulimit.

NOTE: Compiling HOL Light with 'HOLLIGHT_USE_MODULE=1' extends the trusted base of HOL Light to include the inliner script, inline_loads.ml. inline_loads.ml is an OCaml program that receives an HOL Light proof and replaces the loads/loadt/needs function invocations with their actual contents. Please turn this flag on only if having this additional trusted base is considered okay.

    *       *       *       *       *       *       *       *

[*] 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

jrh13 / hol-light

readme