Source

HLVM / INSTALL

Full commit
Installing HLVM
===============

Dependencies
------------

. libsigsegv >=2.5.
. LLVM sources >=2.6.
. OCaml >=3.10.2.


Installation
------------

Configure, build and install LLVM 2.6 with:

$ ./configure --with-ocaml-libdir=`ocamlc -where`
$ make -j12
$ sudo make install

WARNING: If you are using Ubuntu then you may need to disable GCC's stack smashing tests by passing gcc the -fno-stack-protector flag. The stack smashing checks seem to conflict with libsigsegv's handling of stack overflows.


HLVM and its auxiliary LLVM OCaml bindings may be compiled using the script:

$ ./compile.sh

This creates an "hlvm" executable that, when run, incrementally JIT compiles and benchmarks a series of tests.


Debug mode
----------

Debug mode may be enabled with:

$ ./hlvm --debug

in which case extensive information is printed to the console describing the process of compilation (which is ideal for debugging when LLVM calls abort due to a type error in the generated code) and also from print statements injected into the generated code itself (e.g. to describe what the GC is doing as it runs).

The generated functions may also be visualized using LLVM by running HLVM with:

$ ./hlvm --view-functions


Run-time options
----------------

--compile         Just compile the generated code and don't run it.

--debug           Print verbose debug information both as HLVM is generating
                  code and injecting trace print statements into the generated
                  code to print debug information as the compiled program
                  runs.

--no-gc           Disable GC cycles but maintain the shadow stack.

--no-shadow-stack Disable both the shadow stack and GC.

--no-tco          Disable the elimination of tail calls by LLVM.

--view-functions  Visualize functions as HLVM generates them.


Standalone compilation and optimization
---------------------------------------

Running HLVM produces LLVM bitcode output in the aout.bc file. This may be compiled into an
optimized standalone executable with:

$ ./opt.sh

The resulting aout executable is the result of standalone compilation to
native code.

The aoutopt executable demonstrates what LLVM's IR optimization passes can accomplish. In this case, we find that the performance improvement is very small because HLVM already generates efficient LLVM IR.


-- Jon Harrop <jon@ffconsultancy.com>