How do dune libraries and library dependencies work?

[nojb]

@jake

does the archive file itself implicitly define the top-level module that dune makes available? Or is the top-level module in the archive file?

The latter. As far as the compiler is concerned, a library is an arbitrary collection of modules.

@jake

Is this public_name lookup specific to using modules from dune-built projects?

No, any package that has Findlib metadata (META) can appear in the libraries field as long as it is in the “search path” of Dune.

@jake

I imagine dune uses a dune-built opam package’s dune-package file to resolve what modules are available and how to make them available in compiled ocaml code.

Correct. dune-package is basically a richer version of the Findlib metadata META, and they are used whenever they are available. If dune-package is not available (ie for packages not built by Dune), Dune does its best just with the META file.

@jake

Is there a lower-level way to inspect what top-level modules are available in an installed opam package?

If you look in the installation directory of your package, every .cmi file corresponds to a top-level module. You should ignore the files with __ in their names. The double underscore is an artifact of Dune’s implementation of wrapped libraries; these files correspond conceptually to the the submodules of the (only) top-level module of the wrapped library.

Cheers,
Nicolas