Examples we should have in the documentation

[gasche]

I'm creating this issue to keep track of various minimal self-contained examples we should have in the documentation, besides the one kindly contributed by @lindig in #13 , because they capture common use-cases. If someone is willing to contribute something to this documentation, please feel free to send a pull-request with one of those examples -- and a little text in the "Examples" section of the introduction.

[gasche]

First, the obvious: we could have an example of Oasis project that uses ocamlbuild under the hood. To be relevant, it should be a case where the user adds things to the _tags or myocamlbuild.ml file generated by Oasis (we should use the dynamic setup of oasis to avoid having generated files in this example).

[gasche]

It would also be nice to have an example of a project mixing OCaml and C code, with ocamlbuild as the main build system.

[lindig]

I think an example that builds a new toplevel with linking in some modules is an obvious candidate.

[gasche]

I would be interested in an example using another build system (than ocamlbuild or make) as the main build system, with a call to ocamlbuild to build a sub-part of the project. There was an example of this discussed recently on the caml-list, with CMake as the main compiler.

[lindig]

I would be interested in an example where OCaml code is generated by some tool under the control of oamlbuild. This could be a pre-processing step or some kind of generator. How could this be integrated using myocamlbuild.ml?

[gasche]

@lindig Creating a custom toplevel is a good idea, but I would favor an example creating a custom utop toplevel, keeping the spirit of exposing the alternative that I think is best for the user.

(I haven't played with building custom utop toplevels from OCamlbuild at all myself. It should probably be part of the main documentation as well, at the place where building custom toplevels is described.)

Re. generated code: I recently changed the small preprocessor we use in Batteries to work as an OCamlbuild rule instead of a make target: Move the prefiltering logic from Makefile to ocamlbuild. This might serve as inspiration for such an example.

[rleonid]

If possible, I'd really appreciate an example of how to dynamically set what a library depends on. Specifically, if you want the BuildDepends field in an _oasis to be variable. We have some code which builds several libraries with layered dependencies. The middle layer library has some pre-processing (ie. calls to sed) to generate code that might fail dynamically if the appropriate libraries at a lower level are missing.

I think that this requires some correct invocation in a plugin. But I'm at a loss as to how to accomplish this, as adding a tag use_special_library as a tag doesn't work.

[connorjacobsen]

:+1: to the example mixing C code and OCaml with OCamlbuild as the build system. Im having an extremely difficult time getting OCamlbuild to link a .o file I have. It is probably something simple, but an example would certainly be nice. For others too I would imagine.

:+1: to the Oasis example as well.

Would definitely like to see those.

[lindig]

I have a hunch that integrating simple C files is not properly supported by OCamlbuild. It should not require writing myocamlbuild.ml code that explicitly calls compilers and linkers. In any case, there is an example for integrating a simple C module in my fork of the repository. I'm not sure it is a good solution -- see the comment in the Makefile.

[connorjacobsen]

@lindig If nothing else, your example helped me figure out how to build my mixed C and OCaml executable, so thank you.

You could make that example simpler by adding

<src> or <lib>: include

to your _tags file.

That would allow you to remove the -I flags in the Makefile.