Documentation on compiling with Oasis needs an update

[shepard8]

If I try to compile the first step from the widget tutorial using Oasis, I run into lots of undocumented problems. I try to summarize them here. I followed the steps of the workflow-compilation manual page.

• First of all it is not clear which parts of the ocamlbuild section have to be followed, and which are not. I think it could be useful to repeat information so that those interested in using Oasis (I use Oasis because it usually makes things easier) do not have to guess what is the useful information.
• It is unclear what the sentence "Main file. It should refer to all the modules used for this program (including .eliom files)" means. I did just write open Main in some src/client/app.ml file, but I am not even sure this is what is intended ...
• When running oasis setup with the _oasis example given, whence directions in the comments have been applied, warnings are issued:

W: Cannot find source file matching module 'server/Main' in library server. W: Use InterfacePatterns or ImplementationPatterns to define this file with feature "source_patterns".

I think it should at least be mentioned so that users do not think they are doing something wrong.

• It is not said that the existing dispatcher has to be removed in myocamlbuild.ml.
• Running ocaml setup.ml -build also issues these warnings (twice).
• Even when adding

<.eliom>: eliom_ppx <.eliomi>: eliom_ppx

as suggested by the manual when PPX is used (which is the case with the widget tutorial), the following error is issued when building (ocaml setup.ml -build):

+ /home/shepard/.opam/4.02.3/bin/ocamlfind ocamldep -package eliom.server -package eliom.syntax.predef -package eliom.syntax.type -syntax camlp4o -modules src/type/main.ml > src/type/main.ml.depends File "src/main.eliom", line 15, characters 0-1: Parse error: [semi] expected after [str_item] (in [implem]) File "src/type/main.ml", line 1: Error: Error while running external preprocessor Command line: camlp4 '-I' '/home/shepard/.opam/4.02.3/lib/ocaml/camlp4' '-I' '/home/shepard/.opam/4.02.3/lib/js_of_ocaml' '-I' '/home/shepard/.opam/4.02.3/lib/ocaml' '-I' '/home/shepard/.opam/4.02.3/lib/deriving' '-I' '/home/shepard/.opam/4.02.3/lib/js_of_ocaml' '-I' '/home/shepard/.opam/4.02.3/lib/lwt' '-I' '/home/shepard/.opam/4.02.3/lib/lwt' '-I' '/home/shepard/.opam/4.02.3/lib/bytes' '-I' '/home/shepard/.opam/4.02.3/lib/tyxml' '-I' '/home/shepard/.opam/4.02.3/lib/eliom/syntax' '-I' '/home/shepard/.opam/4.02.3/lib/eliom/syntax' '-I' '/home/shepard/.opam/4.02.3/lib/eliom/syntax' '-parser' 'o' '-parser' 'op' '-printer' 'p' 'pa_js.cmo' 'unix.cma' 'pa_deriving_common.cma' 'pa_deriving_Json.cmo' 'lwt-syntax-options.cma' 'lwt-syntax.cma' 'pa_tyxml.cma' '-ignore' 'dummy' 'pa_eliom_seed.cmo' 'pa_eliom_type_filter.cmo' 'src/type/main.ml' > /tmp/ocamlpp8c0e26

Command exited with code 2.

I fixed this problem by adding the following line in the _tags file:

true: eliom_ppx

• Once this is fixed, the following error is issued, still when building (ocaml setup.ml -build), even with the <server/*>: (...), thread line in _tags:

+ /home/shepard/.opam/4.02.3/bin/ocamlfind ocamlc -I src -I src/server -I src/type -i -package eliom.server -package eliom.ppx.type src/type/main.ml > src/type/main.inferred.mli ocamlfind: Error from package `threads': Missing -thread or -vmthread switch Command exited with code 2.

I fixed this by adding the following line in the _tags file:

true: thread

• Once this is fixed, still when building:

+ /home/shepard/.opam/4.02.3/bin/ocamlfind ocamlc -c -g -annot -bin-annot -thread -package eliom.client -package eliom.ppx.client -ppxopt eliom.ppx.client,-type,src/type/main.inferred_gen.mli -I src -I src/client -o src/client/main.cmo src/client/main.ml File "src/main.eliom", line 19, characters 32-34: Error: '##' is not a valid value identifier. Command exited with code 2.

I added js_of_ocaml.ppx to the BuildDepends section of the executable.

• Then:

+ /home/shepard/.opam/4.02.3/bin/ocamlfind ocamlc -c -g -annot -bin-annot -thread -package eliom.client -package eliom.ppx.client -ppxopt eliom.ppx.client,-type,src/type/main.inferred_gen.mli -I src -I src/client -o src/client/main.cmo src/client/main.ml File "src/main.eliom", line 25, characters 6-9: Uninterpreted extension 'lwt'. Command exited with code 2.

I added lwt.ppx to the executable BuildDepends.

• Then it compiles with the following warning:

+ js_of_ocaml --no-runtime --pretty --debug-info --source-map +js_of_ocaml/runtime.js -o src/client/app.js src/client/app.byte There are some missing primitives Dummy implementations (raising 'Failure' exception) will be used if they are not available at runtime. You can prevent the generation of dummy implementations with the commandline option '--disable genprim' Missing primitives provided by +weak.js: caml_weak_blit caml_weak_check caml_weak_create caml_weak_get caml_weak_get_copy caml_weak_set

I added src/client/app.js": package(eliom.client) to _tags.

At this point (and I want to add, finally!), it compiles and works as expected. My point is surely not to blame whoever wrote the documentation, which helped to get a good starting point, but rather that in my humble opinion, it needs a deep rewrite. I'm sure there are better ways to solve issues than globally enable thread and eliom_ppx, and I guess the warnings can be cleanly avoided.

I hope this helps in some way. I'm not against the idea of improving the documentation myself if updating this part is not at all a priority for you.

Oh and the file concerned is eliom/doc/manual-wiki/workflow-compilation.wiki ...