Debian Codegraph @

doc/tutorials/oxcaml-parameterized-library/index.md

raw
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.