2 ocaml modules with same (file)name - ocaml

What I want is to have the following source tree layout:
src/
a.ml
b.ml
...
tests/
a.ml
b.ml
...
Is it possible to distinct these modules and access
src/a.ml module as A and tests/a.ml module as something like Tests.A ?
Actually, there also is a problem with ocamlfind (UPD: omake) it thinks that tests/a.ml depends on itself rather than on src/a.ml
Of course, I can just rename the tests as, like, tests/aTest.ml, but I would like to avoid having to do it. And I just don't believe that it's impossible to have any similarly-named files in the whole source tree (regarding distinction purposes -- isn't it what folders and the whole hierarchical file systems thing are for?)
Thank you very much!

-pack option can be used to group the set of compiled objects under the single module name.
Actually, there also is a problem with
ocamlfind: it thinks that tests/a.ml
depends on itself rather than on
src/a.ml
ocamlfind doesn't deal with deps between source files. ocaml compiler itself will not be able to resolve module names in such setup.
And yes, it is better to avoid similarily named files in source tree :)

Related

(Ocaml) unbound module error on visual code

I have just started to learn Ocaml.
I'm using visual code as my IDE on Ubuntu,
and I have OCaml extension and merlin installed.
and I have the following problem -
my workspace folder contains only 2 files:
a.ml and b.ml.
In the file a.ml I have defined a module named "COOL", and in the file b.ml I wrote:
~ b.ml ~
open COOL;;
I get an error that says "Unbound module COOL merlin"
Is there any way to make it see the module on file a.ml?
I tried searching for solution, I saw something with makefile and .merlin and B build
but I didn't understand it, I don't have anything but the 2 files I mentioned.
I would be happy if someone can tell me what exactly should be done in order for this little example to work.
tl; dr: do ocamlc -c a.ml (or whatever your compilation command is) in order to generate the a.cmi file that merlin will use to get the list of symbols defined in module A.
Apart the fact that in b.ml your module is indeed named A.COOL (unless you open A before open COOL) as mentioned by glennsl, the point is that merlin is, as far as I know, only watching the current file being edited, i.e. b.ml in your case. In order to have access to external symbols, you thus need to have compiled the other files (or at least their corresponding .mli if they exist), in order to have the relevant .cmi files available to merlin.
This is implicit in the paragraph of the documentation describing build paths, which says "[merlin] needs to know where to find the cmi files of the other modules of your project", i.e. those files need to exist in the first place.

Loading OCaml modules not in the current directory

I'm writing a large OCaml project. I wrote a file foo.ml, which works perfectly. In a subdirectory of foo.ml's directory, there is a file bar.ml.
bar.ml references code in foo.ml, so its opening line is:
open Foo
This gives me an error at compile time:
Unbound module Foo.
What can I do to fix this without changing the location of foo.ml?
The easy path is to use one of OCaml build system like ocamlbuild or oasis. Another option would be jbuilder but jbuilder is quite opiniated about file organization and does not allow for the kind of subdirectory structure that you are asking for.
The more explicit path comes with a warning: OCaml build process is complicated with many moving parts that can be hard to deal with.
After this customary warning, when looking for modules, OCaml compiler first looks for module in the current compilation environment, then looks for compiled interface ".cmi" files in the directories specified by the "-I" option flags (plus the current directory and the standard library directory).
Thus in order to compile your bar.ml file, you will need to add the parent directory in the list of included directories with the -I .. option.
After all this, you will discover that during the linking phase, all object files (i.e. .cmo or .cmx) need to be listed in a topological order compatible with the dependency graph of your project.
Consequently, let me repeat my advice: use a proper build system.

Creating an OCaml library

I am trying to create a library that I can use in other OCaml projects, and I'm totally lost.
I'm currently using ocamlbuild which is great for spitting out executables, but I don't know how to get a library out of it.
I've discovered the -a option in ocamlopt and ocamlc but I'm not really sure how to use it. The documentation I've found (for example, here), seems to assume some preexisting knowledge. I don't even know what a .a file is. After I run that, which of the outputted files do I need to build a project that depends on this library? Do I need the mli files so that the application knows the signatures of the library code, or is that included in the output somehow? Also, it would be nice to be able to package all the files together, something similar to a .jar file for Java.
In any case, I would love for ocamlbuild to do all of this for me, since if I have to invoke ocamlopt -a I will have to either manually specify dependencies or hack a script around ocamldep -- something that ocamlbuild was supposed to fix. However, I don't know how to tell it to build a library.
I'm willing to use oasis or OPAM or something if it's necessary, but I would like to learn how to do this using just the basic tools first.
OCamlbuild has some built-in functionality for building libraries, so you can get started with just ocamlbuild foo.cma foo.cmxa (assuming foo.ml is your entry point). This will invoke ocamlopt -a and ocamlc -a for you, handling all the dependency plumbing and leaving the generated files inside _build.
That should be enough to let you compile a library and link it from another program. Since this is just a test you can simply point at the aforementioned _build with -I when compiling the program that uses the library. For real use a library should be packaged - when you get to that point you'll want to look into ocamlfind, oasis, etc.
Have a look at the ocaml.org tutorial on compiling OCaml projects. Additionally the official manual for the bytecode and native code compilers contains useful detail on producing and using the various types of files.
The documentation for ocamlbuild archives seems to cover this pretty well.
In any case, here's one way to do ocaml libraries. Let's say you have a directory called foo containing your .ml, .mli, and .mllib files. Let's say it contained bar.ml, bar.mli, baz.ml, and baz.mli. To distribute all this as one library, you'd also have a foo.mllib in that directory, whose contents are
Bar
Baz
Then to compile, do
$ ocamlbuild -use-ocamlfind foo.cma foo.cmxa
Here is an example.
Then to use your library foo, let's say you had a sibling directory called main, and main contains main.ml, _tags, myocamlbuild.ml.
myocamlbuild.ml should have the following contents:
open Ocamlbuild_plugin
open Command
let () =
dispatch (
function
| After_rules ->
ocaml_lib
~extern:true
~dir:"/path/to/foo/_build"
"foo"
| _ -> ()
)
_tags should have the following contents:
<main.{ml,native,byte}>: use_foo
Compile main.ml with
$ ocamlbuild -use-ocamlfind main.byte main.native
run with
$ ./main.byte
$ ./main.native
More information here as well: https://ocaml.org/learn/tutorials/ocamlbuild/Using_an_external_library.html

Using ocamldoc with packs

I have an ocamlbuild project which includes some files in a subdirectory with an .mlpack file listing them.
e.g. I have a file support/logging.ml which defines the module Support.Logging. The _tags file says "support": for-pack(Support).
This all builds and runs fine. But how can I generate docs for this using ocamldoc?
The most recent post I found was ocamldoc generation and packed files from 2011, which suggests using ocp-pack to generate one large .ml file and pass that to ocamldoc. However, that doesn't take into account the build order, so the generated module doesn't work due to forward references.
What's the best way to handle this?
The problem is described in the following bugreport. Handling -pack inside ocamldoc requires an implementation effort that the maintainer is not motivated to perform, and so far nobody stepped up to contribute a patch for this feature.
In the meantime, you can easily copy your foo.mlpack file into a foo.odocl generating the documentation of the separate submodules. That's only an imperfect workaround as the doc will talk about X rather than Foo.X, but that's a least-effort solution.
Here's the solution I'm now using in my Makefile. It does work, and cross-references into the Support module work:
doc:
ocp-pack -o support.ml.tmp support/logging.ml support/common.ml support/utils.ml support/basedir.ml support/qdom.ml support/system.ml
echo '(** General support code; not 0install-specific *)' > support.ml
cat support.ml.tmp >> support.ml
rm support.ml.tmp
$(OCAMLBUILD) 0install.docdir/index.html
rm support.ml
It's hacky because:
You have to list the support.ml files in build order, by hand
The Makefile adds the doc comments for Support (otherwise, it takes the description of the first sub-module, which you don't want)

OCaml Project Directory Structure

I would like to give two .ml sources files the same name in different directories in my source tree, but the OCaml documentation states that the a file A.ml is exported as a toplevel module A = struct ... end. If I have two files X/A.ml and Y/A.ml, how can I refer to them both from B.ml?
Modules can contain modules, i.e. you can have a hierarchy of modules.
From the B.ml point of view, you can see two modules named X.A and Y.A .
They can even both have a function named foo, those functions would be seen as X.A.foo and Y.A.foo .
Beware that if you open both modules X and Y, the module A from Y will hide the module A from X.
That was from the namespace point of view. Now, about the source tree.
One way would be to have those files:
x.ml
X/a.ml
y.ml
y/a.ml
The file x.ml is automatically generated and contains just this:
module A = struct
(*The contents of x/a.ml is included here*)
end
Likewise for y.ml
There are several preprocessors able to include a file: cpp, camlp4, camlp5, camlmix...
This set of automatically generated files (and regenerated each time the source changes) is not very satisfiying, I will look at other answers.
You can also have a look at ocamlc -pack, but when I tried it a long time ago there was a problem with ocamldoc unable to have x/a.ml and y/a.ml . So check this before you settle on a tool.
You cannot link modules with the same name into the same program. For example, extensions to the standard library, such as Batteries and Core, are forced to give standard modules a different name. In Batteries, the List module is called BatList. Then, they provide a wrapper module Batteries, within which the module is renamed with by doing module List = BatList. The overall path to this module is Batteries.List, so there is no clash with the Standard Library's top level List. Finally, the recommended way of using Batteries and Core is to do open Batteries and open Core, thereby giving you access to their additional list functions under the module name List.
Thus the only option is to rename your modules, but you can do this in two ways:
Change the base names of the modules, e.g. call them A and B.
Put the modules under another module, e.g. name them X.A and Y.A. If you want to keep your current directory structure, you can use OCaml's -pack option. Personally, I find this option too restrictive and always end up doing manual packing, i.e. the technique described above used by Batteries and Core.