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 ... .. code-block:: bash opam install utop dune ocaml-lsp-server ocamlformat Building Code ------------- The full build for ocaml 4.08.0 and 4.12.0 is: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash pip install pygments sphinx sphinx-rtd-theme rstcheck and OCaml like so: .. code-block:: bash opam install odoc Then you can build the documentation with: .. code-block:: bash make doc You can view the reStructuredText documentation with: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash dune utop Then within your ``dune utop`` session you can explore the ProScript AST: .. code-block:: ocaml #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 };;