Contributing

We consider and encourage pull requests that have signed off with a Developer Certificate of Origin. You’ll need to review the LICENSE* files in https://github.com/diskuv/dirsp-exchange.

If you are fine with that, please git clone https://github.com/diskuv/dirsp-exchange and read whichever sections of this internal development guide that interest you.

Visual Studio Code

Make sure you have opam installed. If you don’t have it, it is probably best to follow the Real World OCaml Installation Instructions.

The following is all you need to get Visual Studio Code working …

opam install utop dune ocaml-lsp-server ocamlformat

Building Code

The full build for ocaml 4.08.0 and 4.12.0 is:

opam install dune
opam install ppx_deriving_protobuf
opam install pcre menhirLib                     # proscript-messaging runtime dependencies
opam install ulex camlp4 ocamlformat            # proscript-messaging compile-time auto-translation
opam install alcotest ppx_inline_test           # test support
opam install cstruct                            # dirsp-proscript dependencies
opam install mirage-crypto-rng mirage-crypto-ec # dirsp-proscript-mirage dependencies
opam install iter                               # dirsp-proscript-mirage test dependencies
eval $(opam env)
make

-or- if you want a build for your current ocaml installation (ex. ocaml 4.08.0) that re-uses the autogenerated OCaml code that is already part of this source tree, do:

opam install dune pcre menhirLib alcotest ppx_inline_test cstruct mirage-crypto-rng mirage-crypto-ec iter
eval $(opam env)
make build-noautogen

In either case, after building you may install the package locally:

opam install .

Building Documentation

You will need Python on your machine to build parts of the documentation; Python 3.8 is the only version that has been tested.

Configure Python like so:

pip install pygments sphinx sphinx-rtd-theme rstcheck

and OCaml like so:

opam install odoc

Then you can build the documentation with:

make doc

You can view the reStructuredText documentation with:

open _build/html/index.html    # Most Linux distributions support "open"-ing a file in a web browser from the command line
wslview _build/html/index.html # or the equivalent command in Windows Subsystem for Linux

and the OCaml documentation with:

open _build/default/_doc/_html/index.html    # Linux
wslview _build/default/_doc/_html/index.html # WSL

Debugging

Enabling Stack Traces

Use OCAMLRUNPARAM=b dirsp-ps2ocaml

IDE Debugging

ocamlearlybird can sometimes work with Visual Studio Code (it is an early release). There is already a launch configuration available; just place a breakpoint in within the build directory (ex. _build/default/src-proscript/proscript-messaging/ps2pv/_build/ps2ocaml.ml)

utop

In your project directory (which holds the src-proscript/ subdirectory), run utop within Dune so that all the compiled libraries can be loaded:

dune utop

Then within your dune utop session you can explore the ProScript AST:

#directory "_build/default/src-proscript";;

let root_ast_t = Dirsp_ps2ocamlcore.parse "src-proscript/proscript-messaging/ps/sp.js" (Dirsp_ps2ocamlcore.init_parsing_options ());;

let sample_source_t = List.find_opt (Dirsp_ps2ocamlcore.is_Statement_of (Dirsp_ps2ocamlcore.is_Const_with_identifier "Type_iv") ) root_ast_t;;

let sample_expression_t = match sample_source_t with | Some (`Statement (`Const _c, _), _) -> List.assoc "Type_iv" _c;;

let sample_object_prop_t = match sample_expression_t with | Some (`Object obj_prop_l, _) -> List.find_opt (Dirsp_ps2ocamlcore.is_Property_with_identifier "fromBitstring") obj_prop_l;;

let sample_ast_t = match sample_object_prop_t with Some (`Property (_id, (`Function (_fname, _fargs, _f), _loc)), _) -> _f;;

print_string (Dirsp_ps2ocamlcore__.Ast2ocaml.translate sample_ast_t (Dirsp_ps2ocamlcore.init_translation_options ()));;

(* 1. Run something that may not work to your liking. In our example it is Astpredicates *)
#use "src-proscript/proscript-messaging/ps2pv/astpredicates.ml";;
characterize_ast_style sample_ast_t { skip_nested_functions=true };;

(* 2. Edit the source code (ex. place the following inside characterize_ast_style in astpredicates.ml: Printf.printf "Hello!\n"; *)

(* 3. Reload the source code *)
#use "src-proscript/proscript-messaging/ps2pv/astpredicates.ml";;

(* 4. Retest it *)
characterize_ast_style sample_ast_t { skip_nested_functions=true };;