Merge pull request #12561 from art-w/instantiate-parameterized

feat(oxcaml): instantiate parameterised libraries

Author: Alizter

bin/describe/describe_external_lib_deps.ml

@@ -97,7 +97,7 @@ let resolve_lib_deps db lib_deps =
   let open Memo.O in
   Memo.parallel_map lib_deps ~f:(fun (lib : Lib_dep.t) ->
     match lib with
-    | Direct (_, name) | Re_export (_, name) ->
+    | Direct (_, name) | Re_export (_, name) | Instantiate { lib = name; _ } ->
       let+ v = resolve_lib db name Kind.Required in
       [ v ]
     | Select select ->

doc/changes/added/12561.md

@@ -0,0 +1,2 @@
+- Add support for instantiating OxCaml parameterised libraries.
+  (#12561, @art-w)

doc/reference/dune/library.rst

@@ -222,7 +222,7 @@ order to declare a multi-directory library, you need to use the
    List the library parameters used by the library and its dependencies.
 
    This feature is experimental and requires the compiler you are using to
-   support parameterized libraries.
+   support parameterised libraries.
    See :doc:`/reference/dune/library_parameter`.
 
 .. describe:: (js_of_ocaml ...)

doc/reference/dune/library_parameter.rst

@@ -4,7 +4,7 @@ library_parameter
 .. warning::
 
    This feature is experimental and requires the compiler you are using to
-   support parameterized libraries.
+   support parameterised libraries.
 
 The ``library_parameter`` stanza describes a parameter interface defined in a single ``.mli`` file. To enable this feature,
 you need to add ``(using oxcaml 0.1)`` :doc:`extension

doc/reference/library-dependencies.rst

@@ -68,3 +68,86 @@ be able to see ``foo`` independently of whether :doc:`implicit
 transitive dependencies<dune-project/implicit_transitive_deps>` are
 allowed or not. When they are allowed, which is the default, all transitive
 dependencies are visible, whether they are marked as re-exported or not.
+
+Instantiating Parameterised Dependencies
+----------------------------------------
+
+This feature requires OxCaml, see :doc:`/reference/dune/library_parameter`.
+
+A parameterised dependency ``foo`` can be instantiated with the arguments
+``bar``, ``qux`` using the syntax:
+
+.. code:: dune
+
+   (foo bar qux)
+
+For example:
+
+.. code:: dune
+
+   (library
+    (name test)
+    (libraries (foo bar qux)))
+
+The library ``foo`` must have declared the set of parameters it expects, and
+the arguments given to the instantiation must implement a subset of these
+parameters. The ordering of the arguments does not matter, as the instantiation
+relies on the implemented parameter to uniquely identify each argument.
+For executables, the parameterised dependencies must be fully instantiated.
+
+In the OCaml code, the instantiated library will be available under the module
+name ``Foo``. To avoiding overlapping module names when instantiating the same
+dependency multiple times, the syntax ``:as`` allows renaming the module. For
+example:
+
+.. code:: dune
+
+   (library
+    (name test)
+    (libraries
+     (foo a   b   :as foo_a_b)
+     (foo bar qux :as foo_bar_qux)))
+
+Then the instantiations will be available under the names ``Foo_a_b`` and
+``Foo_bar_qux``.
+
+Dependencies automatically inherit the parameters of their parent library.
+For example, assuming the parameterised library ``foo`` requires two
+parameters ``p`` and ``q``:
+
+.. code:: dune
+
+   (library
+    (name test)
+    (parameters p q)
+    (libraries
+     (foo :as foo_implicit)
+     (foo an_implementation_of_q :as foo_q)
+     (foo bar qux :as foo_bar_qux)
+     other_foo))
+
+Then ``foo_implicit`` is implicitly ``(foo p q)``,
+while ``(foo an_implementation_of_q)`` will only inherit the parameter ``p``.
+
+If ``other_foo``, which is not explicitly instantiated here, is also
+parameterised by the parameters ``p`` (and) or ``q``, it will also inherit
+its parent arguments. Dune will report an error if a dependency requires
+parameters which have neither been given explicitly given via an instantiation
+and are not listed in the parent library parameters.
+
+For unwrapped libaries, the instantiation of parameterised libraries is not
+currently generated. This is subject to change soon, but in the mean time,
+you'll need to manually declare the instantiations: If you depend on the
+instantiation ``(foo bar qux :as new_name)`` with ``bar`` an implementation of
+the parameter ``param_bar`` and ``qux`` an implementation of ``param_qux``,
+then you'll need to write the following:
+
+.. code:: ocaml
+
+   module New_name = Foo (Param_bar) (Bar) (Param_qux) (Qux) [@jane.non_erasable.instances]
+
+.. note::
+
+   While this reuses the OCaml functor application syntax, the attribute changes
+   the meaning: The ``(Param) (Impl)`` must go together as a pair, but the
+   ordering of the arguments otherwise does not matter.

src/dune_lang/lib_dep.ml

@@ -98,6 +98,12 @@ type t =
   | Direct of (Loc.t * Lib_name.t)
   | Re_export of (Loc.t * Lib_name.t)
   | Select of Select.t
+  | Instantiate of
+      { loc : Loc.t
+      ; lib : Lib_name.t
+      ; arguments : (Loc.t * Lib_name.t) list
+      ; new_name : Module_name.t option
+      }
 
 let equal = Poly.equal
 
@@ -107,6 +113,13 @@ let to_dyn =
   | Direct (_, name) -> Lib_name.to_dyn name
   | Re_export (_, name) -> variant "re_export" [ Lib_name.to_dyn name ]
   | Select s -> variant "select" [ Select.to_dyn s ]
+  | Instantiate { lib; arguments; new_name; loc = _ } ->
+    variant
+      "instantiate"
+      [ Lib_name.to_dyn lib
+      ; list (fun (_, arg) -> Lib_name.to_dyn arg) arguments
+      ; option Module_name.to_dyn new_name
+      ]
 ;;
 
 let direct x = Direct x
@@ -126,6 +139,16 @@ let decode ~allow_re_export =
            , let+ select = Select.decode in
              Select select )
          ]
+       <|> enter
+             (let+ () = Syntax.since Oxcaml.syntax (0, 1)
+              and+ loc, lib = located Lib_name.decode
+              and+ arguments, new_name =
+                until_keyword
+                  ":as"
+                  ~before:(located Lib_name.decode)
+                  ~after:Module_name.decode
+              in
+              Instantiate { loc; lib; arguments; new_name })
        <|> let+ loc, name = located Lib_name.decode in
            Direct (loc, name))
   in
@@ -144,11 +167,22 @@ let encode =
     Code_error.raise
       "Lib_dep.encode: cannot encode select"
       [ "select", Select.to_dyn select ]
+  | Instantiate { lib; arguments; new_name; loc = _ } ->
+    let as_name =
+      match new_name with
+      | None -> []
+      | Some new_name -> [ string ":as"; Module_name.encode new_name ]
+    in
+    list
+      sexp
+      ((Lib_name.encode lib :: List.map arguments ~f:(fun (_, arg) -> Lib_name.encode arg))
+       @ as_name)
 ;;
 
 module L = struct
   type kind =
     | Required
+    | Required_multiple
     | Optional
     | Forbidden
 
@@ -186,12 +220,21 @@ module L = struct
              [ Pp.textf
                  "library %S is present both as a forbidden and required dependency"
                  (Lib_name.to_string name)
+             ]
+         | Required_multiple, Required_multiple -> acc
+         | Required_multiple, _ | _, Required_multiple ->
+           User_error.raise
+             ~loc
+             [ Pp.textf
+                 "parameterised library %S is present in multiple forms"
+                 (Lib_name.to_string name)
              ])
     in
     ignore
       (List.fold_left t ~init:Lib_name.Map.empty ~f:(fun acc x ->
          match x with
          | Re_export (_, s) | Direct (_, s) -> add Required s acc
+         | Instantiate { lib = s; _ } -> add Required_multiple s acc
          | Select { choices; _ } ->
            List.fold_left choices ~init:acc ~f:(fun acc (c : Select.Choice.t) ->
              let acc = Lib_name.Set.fold c.required ~init:acc ~f:(add Optional) in

src/dune_lang/lib_dep.mli

@@ -22,6 +22,12 @@ type t =
   | Direct of (Loc.t * Lib_name.t)
   | Re_export of (Loc.t * Lib_name.t)
   | Select of Select.t
+  | Instantiate of
+      { loc : Loc.t
+      ; lib : Lib_name.t
+      ; arguments : (Loc.t * Lib_name.t) list
+      ; new_name : Module_name.t option
+      }
 
 val equal : t -> t -> bool
 val to_dyn : t -> Dyn.t

src/dune_lang/oxcaml.ml

@@ -1,9 +1,13 @@
 open Import
 
+let latest_version = 0, 1
+
 let syntax =
   Syntax.create
     ~name:"oxcaml"
     ~desc:"experimental support for OxCaml"
     ~experimental:true
     [ (0, 1), `Since (3, 20) ]
 ;;
+
+let parameterised_dir = ".parameterised"

src/dune_lang/oxcaml.mli

@@ -1,3 +1,5 @@
 open Import
 
 val syntax : Syntax.t
+val latest_version : Syntax.Version.t
+val parameterised_dir : string

src/dune_rules/compilation_context.ml

@@ -89,6 +89,7 @@ type t =
   ; requires_link : Lib.t list Resolve.t Memo.Lazy.t
   ; implements : Virtual_rules.t
   ; parameters : Module_name.t list Resolve.Memo.t
+  ; instances : Parameterised_rules.instances list Resolve.Memo.t option
   ; includes : Includes.t
   ; preprocessing : Pp_spec.t
   ; opaque : bool
@@ -162,6 +163,7 @@ let create
       ?modes
       ?bin_annot
       ?loc
+      ?instances
       ()
   =
   let project = Scope.project scope in
@@ -236,6 +238,7 @@ let create
   ; bin_annot
   ; loc
   ; ocaml
+  ; instances
   }
 ;;
 
@@ -256,6 +259,15 @@ let for_alias_module t alias_module =
       let profile = Super_context.context t.super_context |> Context.profile in
       Ocaml_flags.default ~dune_version ~profile)
   in
+  let flags =
+    match t.instances with
+    | None -> flags
+    | Some _ ->
+      (* If the alias file instantiates parameterised libraries,
+         the [misplace-attribute] warning is currently raised on
+         [@jane.non_erasable.instances] *)
+      Ocaml_flags.append_common flags [ "-w"; "-53" ]
+  in
   let sandbox =
     (* If the compiler reads the cmi for module alias even with [-w -49
        -no-alias-deps], we must sandbox the build of the alias module since the
@@ -342,3 +354,4 @@ let for_plugin_executable t ~embed_in_plugin_libraries =
 let without_bin_annot t = { t with bin_annot = false }
 let set_obj_dir t obj_dir = { t with obj_dir }
 let set_modes t ~modes = { t with modes }
+let instances t = t.instances