| 1 |
--- |
| 2 |
author: Etienne Marais, Arthur Wendling, Sudha Parimala, Shon Feder |
| 3 |
--- |
| 4 |
|
| 5 |
OxCaml Parameterised Libraries with Dune |
| 6 |
====================================== |
| 7 |
|
| 8 |
::: {warning} |
| 9 |
- This feature is experimental. |
| 10 |
- Parameterised libraries are only supported by the OxCaml branch of the OCaml |
| 11 |
compiler. You need to [install the OxCaml compiler][get-oxcaml] to use |
| 12 |
parameterised libraries with Dune. |
| 13 |
::: |
| 14 |
|
| 15 |
[get-oxcaml]: https://oxcaml.org/get-oxcaml/ |
| 16 |
|
| 17 |
This tutorial explains how to create and use a parameterized library in Dune. |
| 18 |
*Parameterised libraries* specify some of their dependencies as *library |
| 19 |
parameters*, without committing a concrete implementations. This is useful for |
| 20 |
build-time dependency injection and for generalizing over platform-specific |
| 21 |
implementations. It provides a more flexible alternative to dune's |
| 22 |
{doc}`/virtual-libraries`. |
| 23 |
|
| 24 |
By the end of the tutorial, you will know: |
| 25 |
|
| 26 |
- how to declare a library parameter, |
| 27 |
- how to implement a library parameter, |
| 28 |
- how to parameterise a library on a library parameter, |
| 29 |
- how to instantiate a parameterised library by supplying an implementation of |
| 30 |
its library parameters. |
| 31 |
|
| 32 |
## Getting Started |
| 33 |
|
| 34 |
Once you have checked that [OxCaml](https://oxcaml.org/) is installed and its |
| 35 |
`ocamlc` is available on your path, you can enable Dune's `oxcaml` extension in |
| 36 |
your `dune-project`: |
| 37 |
|
| 38 |
:::{literalinclude} parameter/dune-project |
| 39 |
:language: dune |
| 40 |
::: |
| 41 |
|
| 42 |
:::{important} |
| 43 |
Enabling the OxCaml extension by adding the `(use oxcaml 0.1)` stanza allows |
| 44 |
dune to use the stanzas and fields specific to OxCaml. This extension is only |
| 45 |
available since dune `3.20`. |
| 46 |
::: |
| 47 |
|
| 48 |
## Declare a Library Parameter |
| 49 |
|
| 50 |
Library parameters allow libraries to be generic over libraries they depend on. |
| 51 |
This is useful for dependency injection, testing, platform-specific code, etc. |
| 52 |
|
| 53 |
:::{note} |
| 54 |
The interface of a library parameter is specified using an OCaml `.mli` file and |
| 55 |
declared via the `library_parameter` dune stanza. The following analogy holds: |
| 56 |
|
| 57 |
| | module parameters | library parameters | |
| 58 |
|-----------------|-----------------------------------|-------------------------------------------| |
| 59 |
| *declaration* | `module type Intf = <sig>` | `(library_parameter (name intf))` stanza | |
| 60 |
| *specification* | a module signature: `sig ... end` | an interface file: e.g., `intf.mli` | |
| 61 |
::: |
| 62 |
|
| 63 |
|
| 64 |
First, we create an (arbitrarily named) `param/` directory where we are going to |
| 65 |
write our parameter definition. |
| 66 |
|
| 67 |
```{code-block} shell |
| 68 |
mkdir param |
| 69 |
``` |
| 70 |
|
| 71 |
We create a `param/dune` file containing a |
| 72 |
{doc}`/reference/dune/library_parameter` stanza that declares a new library |
| 73 |
parameter named `param`: |
| 74 |
|
| 75 |
:::{literalinclude} parameter/param/dune |
| 76 |
:language: dune |
| 77 |
::: |
| 78 |
|
| 79 |
To complete the declaration, we must provide an `.mli` file matching the given |
| 80 |
`name`, which will specify the interface of the library parameter. We create |
| 81 |
this in `param/param.mli`: |
| 82 |
|
| 83 |
:::{literalinclude} parameter/param/param.mli |
| 84 |
:language: ocaml |
| 85 |
::: |
| 86 |
|
| 87 |
This interface specifies the types, functions, and modules which must be |
| 88 |
provided by a library for it to implement the declared parameter. |
| 89 |
|
| 90 |
## Implement a Library Parameter |
| 91 |
|
| 92 |
:::{note} |
| 93 |
The implementation of a library parameter must satisfy the signature of the |
| 94 |
parameter it claims to implement. The following analogy holds: |
| 95 |
|
| 96 |
| | module implementation | library implementation | |
| 97 |
|------------------------|---------------------------------------|------------------------------------------------------------------------------------------| |
| 98 |
| *ascribed declaration* | `module Impl : Intf` | a library `stanza` with an `implements` field: `(library (name impl) (implements intf))` | |
| 99 |
| *implementation* | a module expression: `struct ... end` | a set of `.ml` files | |
| 100 |
::: |
| 101 |
|
| 102 |
We create an (arbitrarily named) directory `impl/` where we are going to |
| 103 |
write an implementation of our library parameter: |
| 104 |
|
| 105 |
```{code-block} shell |
| 106 |
mkdir impl |
| 107 |
``` |
| 108 |
|
| 109 |
An implementation of a declared library parameter named `param` is a normal dune |
| 110 |
library with the `(implements param)` annotation. We declare this `impl/dune`: |
| 111 |
|
| 112 |
:::{literalinclude} parameter/impl/dune |
| 113 |
:language: dune |
| 114 |
::: |
| 115 |
|
| 116 |
For the sake of simplicity, we give the example of a single-module library, |
| 117 |
defined in `impl/impl.ml`. This must satisfy the parameter interface ascribed by |
| 118 |
the `implements` field: |
| 119 |
|
| 120 |
:::{literalinclude} parameter/impl/impl.ml |
| 121 |
:language: ocaml |
| 122 |
::: |
| 123 |
|
| 124 |
## Define a Parameterised Library |
| 125 |
|
| 126 |
:::{note} |
| 127 |
A parameterised library must specify the parameters it requires. The following |
| 128 |
analogy holds: |
| 129 |
|
| 130 |
| | parameterised module (a "functor") | parameterised library | |
| 131 |
|---------------|------------------------------------|-------------------------------------------------| |
| 132 |
| *declaration* | `module M (P : Intf)` | a `(library (name m) (parameters intf))` stanza | |
| 133 |
::: |
| 134 |
|
| 135 |
We create an (arbitrarily named) directory `lib/` where we are going to write a |
| 136 |
library that is parameterised on our declared library parameter. |
| 137 |
|
| 138 |
```{code-block} shell |
| 139 |
mkdir lib |
| 140 |
``` |
| 141 |
|
| 142 |
We add a `lib/dune` file to declare the library, with the `(parameters param)` |
| 143 |
field, indicating that the library is generic over the library parameter `param`: |
| 144 |
|
| 145 |
:::{literalinclude} parameter/lib/dune |
| 146 |
:language: dune |
| 147 |
::: |
| 148 |
|
| 149 |
|
| 150 |
Within the modules comprising a parameterised library, we can then refer library |
| 151 |
parameters without having to decide on a concrete implementation of the |
| 152 |
libraries up front. In our example, we can directly use the functions from the |
| 153 |
declared `Param` in our library `lib/lib.ml`: |
| 154 |
|
| 155 |
:::{literalinclude} parameter/lib/lib.ml |
| 156 |
:language: ocaml |
| 157 |
::: |
| 158 |
|
| 159 |
## Instantiate a Parameterised Library |
| 160 |
|
| 161 |
:::{note} |
| 162 |
To instantiate a parameterised library, we must supply library arguments that |
| 163 |
implement all specified parameters. The following analogy holds: |
| 164 |
|
| 165 |
| | functor application | library instantiation | |
| 166 |
|-----------------|---------------------|----------------------------------------------------------------------------| |
| 167 |
| *instantiation* | `M (P)` | a `(instantiate m p)` expression in {doc}`/reference/library-dependencies` | |
| 168 |
::: |
| 169 |
|
| 170 |
A *library* can depend on parameterised Libraries if it is, either, |
| 171 |
parameterised with the same parameters as its dependencies, or, it |
| 172 |
**instantiates** its parameterised dependencies. An *executable*, however, must |
| 173 |
instantiate any parameterised libraries, otherwise we wouldn't be able to |
| 174 |
compile a complete program to execute. |
| 175 |
|
| 176 |
To conclude this tutorial, we define an executable target in the new folder |
| 177 |
`bin/`, that depends on an instantiation of our parameterised library. |
| 178 |
|
| 179 |
We create an (arbitrarily named) `bin` directory: |
| 180 |
|
| 181 |
```{code-block} shell |
| 182 |
mkdir bin |
| 183 |
``` |
| 184 |
|
| 185 |
Then we add a `bin/dune` file defining our executable: |
| 186 |
|
| 187 |
:::{literalinclude} parameter/bin/dune |
| 188 |
:language: dune |
| 189 |
::: |
| 190 |
|
| 191 |
In the `libraries` field, the syntax `(instantiate lib impl)` specifies that we |
| 192 |
want to use the concrete library resulting from applying the parameterised |
| 193 |
library `lib` to the library argument `impl`. Note that this application is only |
| 194 |
possible because we defined the `impl` library as an implementation of the |
| 195 |
library parameter, `param`. |
| 196 |
|
| 197 |
The code for our binary simply calls the library code, using the library's name, `Lib`: |
| 198 |
|
| 199 |
:::{literalinclude} parameter/bin/bin.ml |
| 200 |
:language: ocaml |
| 201 |
::: |
| 202 |
|
| 203 |
## Conclusion |
| 204 |
|
| 205 |
In this tutorial, we have learned how to declare a library parameter, define its |
| 206 |
implementation, define a parameterised library, and finally to use the latter by |
| 207 |
instantiating it for an executable target. |