Merge pull request #11963 from maiste/library_parameter

 Support the library_parameter stanza

Author: maiste

doc/changes/11963.md

@@ -0,0 +1,4 @@
+## Added
+
+- (Experimental): Introduce the `library_parameter` stanza. It allows users to declare a parameter when
+  using the OxCaml compiler (#11963, implements #12084, @maiste) 

doc/reference/dune/index.rst

@@ -75,6 +75,12 @@ The following pages describe the available stanzas and their meanings.
       ocamllex
       ocamlyacc
 
+    .. toctree::
+      :caption: Experimental
+      :maxdepth: 1
+
+      library_parameter
+
     .. toctree::
       :caption: Deprecated
       :maxdepth: 1

doc/reference/dune/library_parameter.rst

@@ -0,0 +1,109 @@
+library_parameter
+-----------------
+
+.. warning::
+
+   This feature is experimental and requires the compiler you are using to
+   support parameterized 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
+</reference/dune-project/using>` in your ``dune-project`` file.
+
+.. describe:: (library_parameter ...)
+
+  .. versionadded:: 3.20
+
+  Define a parameter.
+
+  .. describe:: (name <parameter-name>)
+
+    ``parameter-name`` is the name of the library parameter. It must be a valid
+    OCaml module name as for :doc:`/reference/dune/library`. 
+
+    This must be specified if no `public_name` is specified.
+
+  .. describe:: (public_name ...)
+
+    The name under which the library parameter can be referred as a dependency
+    when it's not part of the current workspace, i.e., when it is installed.
+    Without a ``(public_name ...)`` field, the library parameter won't be
+    installed by Dune. The public name must start with the package name it's
+    part of and optionally followed by a dot, then anything else you want. The
+    package name must also be one of the packages that Dune knows about, as
+    determined by the logic described in :doc:`/reference/packages`.
+
+  .. describe:: (package <package>)
+
+    Installs a private library parameter under the specified package. Such a
+    parameter is now usable by public libraries defined in the same project.
+
+  .. describe:: (synopsis <string>)
+
+    A one-line description of the library parameter.
+
+  .. describe:: (modules <modules>)
+
+    Specifies a specific module to select as a `library_parameter`.
+
+    ``<modules>`` uses the :doc:`/reference/ordered-set-language`, where
+    elements are module names and don't need to start with an uppercase letter.
+
+    The library parameter **must** only declare one ``mli`` file as part of its
+    modules.
+
+  .. describe:: (libraries <library-dependencies>)
+
+    Specifies the library parameter's dependencies.
+
+    See :doc:`/reference/library-dependencies` for more details.
+
+  .. describe:: (preprocesss <preprocess-spec>)
+
+    Specifies how to preprocess files when needed.
+
+    The default is ``no_preprocessing``, and other options are described
+    in :doc:`/reference/preprocessing-spec`.
+
+  .. describe:: (preprocessor_deps (<deps-conf list>))
+
+    Specifies extra preprocessor dependencies preprocessor, i.e., if the
+    preprocessor reads a generated file.
+
+    The specification of dependencies is described in
+    :doc:`/concepts/dependency-spec`.
+
+
+  .. describe:: (flags ...)
+
+    See :doc:`/concepts/ocaml-flags`.
+
+  .. describe:: (ocamlc_flags ...)
+
+    See :doc:`/concepts/ocaml-flags`.
+
+  .. describe:: (ocamlopt_flags ...)
+
+   See :doc:`/concepts/ocaml-flags`.
+
+  .. describe:: (optional)
+
+    If present, it indicates that the library parameter should only be built
+    and installed if all the dependencies are available, either in the
+    workspace or in the installed world.
+
+  .. describe:: (enabled_if <blang expression>)
+
+    Conditionally disables a library parameter.
+
+    A disabled library parameter cannot be built and will not be installed.
+
+    The condition is specified using the :doc:`/reference/boolean-language`, and
+    the field allows for the ``%{os_type}`` variable, which is expanded to the
+    type of OS being targeted by the current build. Its value is the same as the
+    value of the ``os_type`` parameter in the output of ``ocamlc -config``.
+
+  .. describe:: (allow_overlapping_dependencies)
+
+    Allows external dependencies to overlap with libraries that are present in
+    the workspace.

src/dune_lang/dune_lang.ml

@@ -59,6 +59,7 @@ module Js_of_ocaml = Js_of_ocaml
 module Menhir = Menhir
 module Rule_mode_decoder = Rule_mode_decoder
 module Mode_conf = Mode_conf
+module Oxcaml = Oxcaml
 
 (* CR-someday rgrinberg: perhaps wrap these under [Stanzas]? *)
 module Copy_files = Copy_files

src/dune_lang/lib_kind.ml

@@ -62,13 +62,15 @@ type t =
   | Normal
   | Ppx_deriver of Ppx_args.t
   | Ppx_rewriter of Ppx_args.t
+  | Parameter
 
 let equal = Poly.equal
 
 let to_dyn x =
   let open Dyn in
   match x with
   | Normal -> variant "Normal" []
+  | Parameter -> variant "Parameter" []
   | Ppx_deriver args -> variant "Ppx_deriver" [ Ppx_args.to_dyn args ]
   | Ppx_rewriter args -> variant "Ppx_rewriter" [ Ppx_args.to_dyn args ]
 ;;
@@ -77,6 +79,7 @@ let decode =
   let open Decoder in
   sum
     [ "normal", return Normal
+    ; "parameter", return Parameter
     ; ( "ppx_deriver"
       , let+ args = Ppx_args.decode in
         Ppx_deriver args )
@@ -90,6 +93,7 @@ let encode t =
   match
     match t with
     | Normal -> Dune_sexp.atom "normal"
+    | Parameter -> Dune_sexp.atom "parameter"
     | Ppx_deriver x -> List (Dune_sexp.atom "ppx_deriver" :: Ppx_args.encode x)
     | Ppx_rewriter x -> List (Dune_sexp.atom "ppx_rewriter" :: Ppx_args.encode x)
   with

src/dune_lang/lib_kind.mli

@@ -17,6 +17,7 @@ type t =
   | Normal
   | Ppx_deriver of Ppx_args.t
   | Ppx_rewriter of Ppx_args.t
+  | Parameter
 
 val to_dyn : t Dyn.builder
 val equal : t -> t -> bool

src/dune_rules/buildable_rules.ml

@@ -55,6 +55,7 @@ let with_lib_deps (t : Context.t) merlin_ident ~dir ~f =
 type kind =
   | Executables of Buildable.t * (Loc.t * string) list
   | Library of Buildable.t * Lib_name.Local.t
+  | Parameter of Buildable.t * Lib_name.Local.t
   | Melange of
       { preprocess : Preprocess.With_instrumentation.t Preprocess.Per_module.t
       ; preprocessor_deps : Dep_conf.t list
@@ -145,9 +146,22 @@ let modules_rules
 ;;
 
 let modules_rules sctx kind expander ~dir scope modules =
+  let* () =
+    match kind with
+    | Executables _ | Library _ | Melange _ -> Memo.return ()
+    | Parameter _ ->
+      let* ocaml = Super_context.context sctx |> Context.ocaml in
+      let ocaml_version = Ocaml_config.version_string ocaml.ocaml_config in
+      if Ocaml.Version.supports_parametrized_library ocaml_version
+      then Memo.return ()
+      else
+        User_error.raise
+          [ Pp.text "The compiler you are using is not compatible with library parameter"
+          ]
+  in
   let preprocess, preprocessor_deps, lint, empty_module_interface_if_absent =
     match kind with
-    | Executables (buildable, _) | Library (buildable, _) ->
+    | Executables (buildable, _) | Library (buildable, _) | Parameter (buildable, _) ->
       ( buildable.preprocess
       , buildable.preprocessor_deps
       , buildable.lint
@@ -158,12 +172,12 @@ let modules_rules sctx kind expander ~dir scope modules =
   let lib_name =
     match kind with
     | Executables _ | Melange _ -> None
-    | Library (_, name) -> Some name
+    | Library (_, name) | Parameter (_, name) -> Some name
   in
   let empty_intf_modules =
     match kind with
     | Executables (_, modules) -> Some modules
-    | Library _ | Melange _ -> None
+    | Library _ | Melange _ | Parameter _ -> None
   in
   modules_rules
     ~preprocess

src/dune_rules/buildable_rules.mli

@@ -23,6 +23,7 @@ val with_lib_deps
 type kind =
   | Executables of Buildable.t * (Loc.t * string) list
   | Library of Buildable.t * Lib_name.Local.t
+  | Parameter of Buildable.t * Lib_name.Local.t
   | Melange of
       { preprocess : Preprocess.With_instrumentation.t Preprocess.Per_module.t
       ; preprocessor_deps : Dep_conf.t list

src/dune_rules/gen_meta.ml

@@ -76,7 +76,7 @@ let gen_lib pub_name lib ~version =
   in
   let preds =
     match kind with
-    | Normal -> []
+    | Normal | Parameter -> []
     | Ppx_rewriter _ | Ppx_deriver _ -> [ Pos "ppx_driver" ]
   in
   let name lib =
@@ -127,7 +127,7 @@ let gen_lib pub_name lib ~version =
          ; ppx_runtime_deps ppx_rt_deps
          ])
     ; (match kind with
-       | Normal -> []
+       | Normal | Parameter -> []
        | Ppx_rewriter _ | Ppx_deriver _ ->
          (* Deprecated ppx method support *)
          let no_ppx_driver = Neg "ppx_driver"
@@ -139,7 +139,7 @@ let gen_lib pub_name lib ~version =
              ; requires ~preds:[ no_ppx_driver ] ppx_runtime_deps_for_deprecated_method
              ]
            ; (match kind with
-              | Normal -> assert false
+              | Normal | Parameter -> assert false
               | Ppx_rewriter _ ->
                 [ rule "ppx" [ no_ppx_driver; no_custom_ppx ] Set "./ppx.exe --as-ppx"
                 ; rule "library_kind" [] Set "ppx_rewriter"

src/dune_rules/install_rules.ml

@@ -79,7 +79,7 @@ module Stanzas_to_entries : sig
 end = struct
   let lib_ppxs ctx ~scope ~(lib : Library.t) =
     match lib.kind with
-    | Normal | Ppx_deriver _ -> Memo.return []
+    | Normal | Parameter | Ppx_deriver _ -> Memo.return []
     | Ppx_rewriter _ ->
       Library.best_name lib
       |> Ppx_driver.ppx_exe ctx ~scope
@@ -266,6 +266,7 @@ end = struct
     let { Lib_mode.Map.ocaml = { Mode.Dict.byte; native } as ocaml; melange } =
       Mode_conf.Lib.Set.eval lib.modes ~has_native
     in
+    let is_parameter = Library.is_parameter lib in
     let+ melange_runtime_entries = additional_deps lib.melange_runtime_deps
     and+ public_headers = additional_deps lib.public_headers
     and+ module_files =
@@ -297,16 +298,21 @@ end = struct
         fun m ->
           let cm_file kind = Obj_dir.Module.cm_file obj_dir m ~kind in
           let open Lib_mode.Cm_kind in
-          [ if_ (native || byte) (Ocaml Cmi, cm_file (Ocaml Cmi))
-          ; if_ native (Ocaml Cmx, cm_file (Ocaml Cmx))
-          ; if_ (byte && virtual_library) (Ocaml Cmo, cm_file (Ocaml Cmo))
-          ; if_
-              (native && virtual_library)
-              (Ocaml Cmx, Obj_dir.Module.o_file obj_dir m ~ext_obj)
-          ; if_ melange (Melange Cmi, cm_file (Melange Cmi))
-          ; if_ melange (Melange Cmj, cm_file (Melange Cmj))
-          ]
-          |> List.rev_concat
+          let cmi = if_ (native || byte) (Ocaml Cmi, cm_file (Ocaml Cmi)) in
+          let rest =
+            if is_parameter
+            then []
+            else
+              [ if_ native (Ocaml Cmx, cm_file (Ocaml Cmx))
+              ; if_ (byte && virtual_library) (Ocaml Cmo, cm_file (Ocaml Cmo))
+              ; if_
+                  (native && virtual_library)
+                  (Ocaml Cmx, Obj_dir.Module.o_file obj_dir m ~ext_obj)
+              ; if_ melange (Melange Cmi, cm_file (Melange Cmi))
+              ; if_ melange (Melange Cmj, cm_file (Melange Cmj))
+              ]
+          in
+          cmi :: rest |> List.rev_concat
       in
       let set_dir m = List.rev_map ~f:(fun (cm_kind, p) -> cm_dir m cm_kind, p) in
       let+ modules_impl =
@@ -348,11 +354,16 @@ end = struct
       [ sources
       ; melange_runtime_entries
       ; List.rev_map module_files ~f:(fun (sub_dir, file) -> make_entry ?sub_dir Lib file)
-      ; List.rev_map lib_files ~f:(fun (section, file) -> make_entry section file)
-      ; List.rev_map execs ~f:(make_entry Libexec)
-      ; dll_files
-      ; install_c_headers
-      ; public_headers
+      ; (match is_parameter with
+         | true -> []
+         | false ->
+           List.rev_concat
+             [ List.rev_map lib_files ~f:(fun (section, file) -> make_entry section file)
+             ; List.rev_map execs ~f:(make_entry Libexec)
+             ; dll_files
+             ; install_c_headers
+             ; public_headers
+             ])
       ]
   ;;