Why is my ocaml module undefined? - ocaml

Question

I've got a lexer and parser that I built with ocamllex and menhir, and they work when I #use them at top level, but the modules they constitute are still undefined.
~: ocamlbuild -clean
~: ocamlbuild PhoebeParser.cma PhoebeLexer.cma
ocamlopt.opt unix.cmxa -I /Users/Tim/.opam/system/lib/ocamlbuild /Users/Tim/.opam/system/lib/ocamlbuild/ocamlbuildlib.cmxa myocamlbuild.ml /Users/Tim/.opam/system/lib/ocamlbuild/ocamlbuild.cmx -o myocamlbuild
menhir --infer --raw-depend --ocamldep 'ocamldep.opt -modules' PhoebeParser.mly > PhoebeParser.mly.depends
ocamldep.opt -modules PhoebeAST.ml > PhoebeAST.ml.depends
ocamlc.opt -c -o PhoebeAST.cmo PhoebeAST.ml
menhir --ocamlc ocamlc.opt --infer PhoebeParser.mly
ocamldep.opt -modules PhoebeParser.mli > PhoebeParser.mli.depends
ocamlc.opt -c -o PhoebeParser.cmi PhoebeParser.mli
ocamldep.opt -modules PhoebeParser.ml > PhoebeParser.ml.depends
ocamlc.opt -c -o PhoebeParser.cmo PhoebeParser.ml
ocamlc.opt -a PhoebeAST.cmo PhoebeParser.cmo -o PhoebeParser.cma
ocamldep.opt -modules PhoebeLexer.mli > PhoebeLexer.mli.depends
ocamlc.opt -c -o PhoebeLexer.cmi PhoebeLexer.mli
ocamllex.opt -q PhoebeLexer.mll
ocamldep.opt -modules PhoebeLexer.ml > PhoebeLexer.ml.depends
ocamlc.opt -c -o PhoebeLexer.cmo PhoebeLexer.ml
ocamlc.opt -a PhoebeAST.cmo PhoebeParser.cmo PhoebeLexer.cmo -o PhoebeLexer.cma
~: cd _build/
~/_build: ocaml
OCaml version 4.04.0
# PhoebeParser.phoebe_spec;;
Characters -1--1:
PhoebeParser.phoebe_spec;;
Error: Reference to undefined global `PhoebeParser'
# PhoebeLexer.phoebe_lexer;;
Characters -1--1:
PhoebeLexer.phoebe_lexer;;
Error: Reference to undefined global `PhoebeLexer'
#
What am I doing wrong?

Answer 1

Your modules are compiled and archived in PhoebeLexer.cma and PhoebeParser.cma files. Each module also has an accompanying .cmi file, that describes its interface. To load a module to the top-level you can use #load or #load_rec directives. The #use directive is not useful, as it operates on a source level (it can be seen as a shortcut for copy-pasting).
So, in your case the top-level interaction should look like this (assuming that are starting the top-level in the _build folder):
# #load "PhoebeLexer.cma";;
# #load "PhoebeParser.cma";;
What's the difference between a module I can #load and a module I can Open?
I like concrete questions!
When you're opening a module M, the toplevel is searching for a file m.cmi in the current directory, in the directory where OCaml is installed, and in all directories added explicitly with the #directory directive. The cmi file contains a machine readable condensed module interface (you may think of it as a compiled module interface). This file defines a type of a loaded module. And you can access types of a module without even loading the module. To get the definitions of a module, you need to load the implementation. That is stored either in cmo (compiled module object file) or cma (compiled module archive). A cma file is just a container for multiple cmo. A cmo file contains actual code, that can be loaded and linked with the main program (with the toplevel program in this case).
As you may noticed, an interface and an implementation are completely different entities, that can be loaded independently. The interface is looked up implicitely, you do not need to load it manually, but sometimes you either need to change a directory (by loading the toplevel in a particular directory, or by using the #cd directive), or by adding a directory to the search paths with the #directory directive. Implementations should be always loaded explicitly with the #load directive.
If cmi is available, but an implementation is not loaded, then you will get some Undefined value error. If cmi is not available then an attempt to access to the value declared in the interface of a module with missing cmi file will yell an Unbound value error (even if you loaded the module archive itself).
To summarize: interface describes what is available, implementation defines where it is available. If the value is not in the interface, then it is unbound; if the value is in the interface, but the definition is not found, then it is undefined.