Advanced topics¶
This section describes some details of Jbuilder for advanced users.
META file generation¶
Jbuilder uses META
files from the findlib library
manager in order
to interoperate with the rest of the world when installing libraries. It
is able to generate them automatically. However, for the rare cases
where you would need a specific META
file, or to ease the transition
of a project to Jbuilder, it is allowed to write/generate a specific
one.
In order to do that, write or setup a rule to generate a
META.<package>
file in the same directory as the <package>.opam
file. If you do that, Jbuilder will still generate a META
file but
it will be called META.<package>.from-jbuilder
. So for instance if
you want to extend the META
file generated by Jbuilder you can
write:
(rule
((targets (META.foo))
(deps (META.foo.from-jbuilder))
(action (with-stdout-to ${@}
(progn
(cat ${<})
(echo blah))))))
Additionally, Jbuilder provides a simpler mechanism for this scheme:
just write or generate a META.<package>.template
file containing a
line of the form # JBUILDER_GEN
. Jbuilder will automatically insert
its generated META
contents in place of this line.
Using a custom ppx driver¶
You can use a custom ppx driver by putting it as the last library in (pps
...)
forms. An example of alternative driver is ppx_driver. To use it instead of
ocaml-migrate-parsetree.driver-main
, simply write ppx_driver.runner
as
the last library:
(preprocess (pps (ppx_sexp_conv ppx_bin_prot ppx_driver.runner)))
Driver expectation¶
Jbuilder will invoke the executable resulting from linking the libraries
given in the (pps ...)
form as follows:
ppx.exe <flags-written-by-user> --dump-ast -o <output-file> \
[--cookie library-name="<name>"] [--impl|--intf] <source-file>
Where <source-file>
is either an implementation (.ml
) or
interface (.mli
) OCaml source file. The command is expected to write
a binary OCaml AST in <output-file>
.
Additionally, it is expected that if the executable is invoked with
--as-ppx
as its first argument, then it will behave as a standard
ppx rewirter as passed to -ppx
option of OCaml. This is for two
reason:
- to improve interoperability with build systems that Jbuilder
- so that it can be used with merlin