Skip to content

Latest commit

 

History

History
126 lines (78 loc) · 4.63 KB

HACKING.jst.adoc

File metadata and controls

126 lines (78 loc) · 4.63 KB

Hacking on ocaml-jst

ocaml-jst has a dune-based build system which is different from upstream OCaml. To get started, you’ll need a working install of OCaml 4.14 and dune, e.g. via OPAM:

$ opam switch create 4.14.0
$ eval $(opam env)
$ opam install dune

You should also install merlin:

$ opam install merlin

and follow its instructions for how to set up your editor.

Once you have OCaml and dune, you can build and test ocaml-jst with:

$ ./configure --prefix=/where/to/install
$ make -f Makefile.jst runtest-upstream

Other useful Makefile targets are:

$ make -f Makefile.jst compiler

to build without running the testsuite, or:

$ make -f Makefile.jst hacking

to start a continuously polling build of the compiler.

Note that the dune-based build system is entirely separate from the main Makefile, and so you will need to use make -f Makefile.jst install to install after building.

Testing

As demonstrated above, you can

$ make -f Makefile.jst runtest-upstream

to run the entire testsuite. As a shorter synonym, you may also

$ make -f Makefile.jst test

If you want to run just one test or one test directory, you can

$ make -f Makefile.jst test-one TEST=<<test file here>>
$ make -f Makefile.jst test-one DIR=<<test dir here>>

where the test file or test dir are specified with respect to the testsuite/tests directory. For example:

$ make -f Makefile.jst test-one TEST=typing-local/local.ml
$ make -f Makefile.jst test-one DIR=typing-local

Likewise, you can use promote-one to accept the diff from a failed test:

$ make -f Makefile.jst promote-one TEST=typing-local/local.ml
$ make -f Makefile.jst promote-one DIR=typing-local

If you’ve run some series of tests and would like to accept the diff from all failed tests in that run, use promote-failed:

$ make -f Makefile.jst promote-failed

To run just one test without running a full dune build, you can use *-no-rebuild versions of test-one and promote-one. Note that these targets won’t pick up changes you’ve made to compiler code, though they will faithfully pick up changes you’ve made to test files.

$ make -f Makefile.jst test-one-no-rebuild TEST=typing-local/local.ml
$ make -f Makefile.jst promote-one-no-rebuild DIR=typing-local

Debugging

We make several custom printers available so that we can print more values in ocamldebug. Notable examples:

  • OCaml 4.14 makes type_expr abstract, and thus normal debug printing of types no longer works without a custom printer.

  • The debug printer for Ctypes.global_state lets you see the global mutable state maintained within the Ctypes module.

Here’s how to install the custom printers for a run of ocamldebug:

  1. Use the old Makefile, not the new Makefile.jst. This is an infelicity we hope to fix.

  2. In the tools directory, run make debug_printers.

  3. In the debugger, execute some instructions, with e.g. run or step. This forces the debugger to load the compiler code, required for the next step.

  4. From your debugging session, run source tools/debug_printers to install the printers.

To add a new printer, simply add a line of the form

let name = Some.Compiler.printer

to tools/debug_printers.ml, and then run make debug_printers in the tools directory to regenerate the printing script.

Benchmarking

A small but relatively comprehensive benchmark is to run our compiler against typing/typecore.ml. First we install the opam switch with FP (frame pointers) enabled; adjust the version number as needed:

$ opam switch create 4.14.1-fp --packages=ocaml-variants.4.14.1+options,ocaml-option-fp --repos=default

Remember to check that the newly installed switch is being used:

$ opam switch
#   switch     compiler                                         description
    4.14.1     ocaml-base-compiler.4.14.1                       4.14.1
->  4.14.1-fp  ocaml-option-fp.1,ocaml-variants.4.14.1+options  4.14.1-fp

Then build the compiler — the following command will build the compiler using the opam switch, then use the newly-built compiler to build itself.

$ make -f Makefile.jst compiler

We can now benchmark our compiler against typecore.ml. The following _bootinstall is built using the opam switch and has FP enabled.

$ cd _build/main
$ perf stat -r 5 ../_bootinstall/bin/ocamlc.opt -strict-sequence -principal -w +a-4-9-40-41-42-44-45-48-66-70 -warn-error A -bin-annot -safe-string -strict-formats -w -67 -g -bin-annot -I .ocamlcommon.objs/byte -I ../runtime_stdlib_install/lib/ocaml_runtime_stdlib/  -intf-suffix .ml -no-alias-deps -o .ocamlcommon.objs/byte/typecore.cmo -c -impl typecore.ml