A library in the bantorra framework is a tree of units that can be accessed via unit paths from the root. A unit path is a list of strings, such as lib/num/types
. The purpose of the bantorra framework is to provide a flexible mechanism to map each unit path to some underlying file path. For example, the unit path lib/num/types
might be mapped to the file path /usr/lib/cool/number/types.data
, and the resolution process takes in both what is set up by the application and what is provided by its users.
In the simplest case, there is a one-to-one correspondence between units and files under a directory: the unit path a/b/c
corresponds to the file a/b/c.data
where .data
is the extension specified by the application. The root directory is marked by a special file called anchor, which is a file with a fixed name again specified by the application. For example, the existence of a dune
file means there is an OCaml library in the eyes of the dune
building tool. An anchor in the bantorra framework marks the root of a library. If the anchor file name is anchor.json
, the file at /usr/lib/cool/number/anchor.json
indicates that there is a library containing files under /usr/lib/cool/number
.
It is common for units within a library to access units in another library. To do so, an anchor file may mount another library in the tree, in a way similar to how partitions are mounted in POSIX-compliant systems. Here is a sample anchor file:
{ "format": "1.0.0", "mounts": { "lib/num": ["local", "/usr/lib/cool/number"] } }
The above anchor file presumably mounts the library number
at lib/num
. With this, the unit path lib/num/types
will be routed to the unit types
within the library number
. The resolution is recursive because the mounted library may mount yet another library. The JSON array ["local", "/usr/lib/cool/number"]
specifies where the location of the library, and the application has full control of how to interpret the location specification ["local", "/usr/lib/cool/number"]
. The example assumes that ["local", path]
refers to path
in a local file system, but the application can choose to use any OCaml function from JSON data to directory paths. A few basic routing functions are provided in Bantorra.Router
.
As mentioned earlier, an anchor file looks like this:
{ "format": ...version of the anchor format..., "mounts": { "path/to/lib1": ...(spec of lib1)... "path/to/lib2": ...(spec of lib2)... ... "path/to/libn": ...(spec of libn)... } }
The format
version string is decided by the application; it can help detect outdated anchor files. As for the mounts
property, if it is missing, then the library has no dependencies. Each dependency is specified by a key/value pair, where the key is the mount point and value is the parameter for locating the library. During the resolution, the entire parameter is passed to the router. See Bantorra.Router.t
and Bantorra.Router.param
. The order of entries in mounts
does not matter because the dispatching is based on longest prefix match. If no match can be found, then it means the unit path refers to a local unit. The same library can be mounted at multiple points. However, to keep the resolution unambiguous, there cannot be two libraries mounted at the same point. Here is an example demonstrating the longest prefix match:
{ "format": "1.0.0", "mounts": { "lib": "stdlib", "lib/bantorra": ["git", {url: "https://github.com/RedPRL/bantorra"}] } }
The unit path lib/orntorra
will be routed to the unit orntorra
within the stdlib
library, pending further resolution (as the stdlib
library might further mount other libraries), while the unit path lib/bantorra/shisho
will be routed to the git repo https://github.com/RedPRL/bantorra
, not the unit bantorra/shisho
in the stdlib
library, because lib/bantorra
matches lib/bantorra/shisho
better than lib
does.
Note that, if some library is mounted at world/towitorra
, then the original local unit with the unit path world/towitorra
will no longer be accessible. As an analogy using the POSIX-compliant mount
, the original files within /mnt
will not be accessible after mounting a file system at /mnt
.
test/Example.ml
).