feat: %{cmt} and %{cmti} artifact variables

Signed-off-by: Ali Caglayan <alizter@gmail.com>

Author: Alizter

doc/advanced/variables-artifacts.rst

@@ -23,10 +23,18 @@ interpreted relative to the current directory:
   ``<path>`` should be the name of a module as specified in a ``(modules)``
   field.
 
-- ``cma:<path>`` and ``cmxa:<path>`` expands to the corresponding 
-  artifact's path for the library specified by ``<path>``. The basename of ``<path>``
+- ``cma:<path>`` and ``cmxa:<path>`` expands to the corresponding artifact's
+  path for the library specified by ``<path>``. The basename of ``<path>``
   should be the name of the library as specified in the ``(name)`` field of a
   ``library`` stanza (*not* its public name).
 
+- ``cmt:<path>`` and ``cmti:<path>`` expand to the corresponding compiled
+  annotation files for the module specified by ``<path>``. These files contain
+  the typed abstract syntax tree with precise location information and type
+  annotations, generated with the ``-bin-annot`` flag. They are particularly
+  useful for IDE tools to provide tooltips and type information.
+
+  .. versionadded:: 3.21
+
 In each case, the expansion of the variable is a path pointing inside the build
 context (i.e., ``_build/<context>``).

doc/changes/added/12634.md

@@ -0,0 +1,3 @@
+- Add support for `%{cmt:...}` and `%{cmti:...}` variables to reference
+  compiled annotation files (.cmt and .cmti) containing typed abstract syntax
+  trees with location and type information. (#12634, grants #12633, @Alizter)

src/dune_lang/lib_mode.ml

@@ -71,7 +71,7 @@ module Cm_kind = struct
 end
 
 let of_cm_kind : Cm_kind.t -> t = function
-  | Ocaml (Cmi | Cmo) -> Ocaml Byte
+  | Ocaml (Cmi | Cmo | Cmt | Cmti) -> Ocaml Byte
   | Ocaml Cmx -> Ocaml Native
   | Melange (Cmi | Cmj) -> Melange
 ;;

src/dune_lang/pform.ml

@@ -610,7 +610,13 @@ module Env = struct
     let macros =
       let macro (x : Macro.t) = No_info x in
       let artifact x =
-        String.drop (Artifact.ext x) 1, since ~version:(2, 0) (Macro.Artifact x)
+        let name = String.drop (Artifact.ext x) 1 in
+        let version =
+          match x with
+          | Mod Cmt | Mod Cmti -> 3, 21
+          | _ -> 2, 0
+        in
+        name, since ~version (Macro.Artifact x)
       in
       String.Map.of_list_exn
         ([ "exe", macro Exe

src/dune_rules/check_rules.ml

@@ -1,7 +1,7 @@
 open Import
 
 let dev_files =
-  [ Ml_kind.cmt_ext Impl; Ml_kind.cmt_ext Intf; Cm_kind.ext Cmi ]
+  [ Cm_kind.ext Cmt; Cm_kind.ext Cmti; Cm_kind.ext Cmi ]
   |> List.map ~f:(String.drop_prefix_if_exists ~prefix:".")
   |> Glob.matching_extensions
 ;;

src/dune_rules/compilation_context.ml

@@ -48,6 +48,8 @@ module Includes = struct
                 ])
              |> Resolve.Memo.args
              |> Command.Args.memo
+         ; cmt = cmi_includes
+         ; cmti = cmi_includes
          })
     ; melange =
         { cmi = make_includes_args ~mode:Melange [ Melange Cmi ]

src/dune_rules/module_compilation.ml

@@ -62,7 +62,7 @@ let copy_interface ~sctx ~dir ~obj_dir ~cm_kind m =
 
 let melange_args (cctx : Compilation_context.t) (cm_kind : Lib_mode.Cm_kind.t) module_ =
   match cm_kind with
-  | Ocaml (Cmi | Cmo | Cmx) | Melange Cmi -> []
+  | Ocaml (Cmi | Cmo | Cmx | Cmt | Cmti) | Melange Cmi -> []
   | Melange Cmj ->
     let melange_extension_version =
       let scope = Compilation_context.scope cctx in
@@ -188,15 +188,15 @@ let build_cm
               Command.Args.Hidden_targets
                 [ Obj_dir.Module.cm_file_exn obj_dir m ~kind:cmi_kind ]
           | (Ocaml Cmo | Melange Cmj), None, true
-          | (Ocaml (Cmo | Cmx) | Melange Cmj), _, _ ->
+          | (Ocaml (Cmo | Cmx | Cmt) | Melange Cmj), _, _ ->
             Memo.return (force_read_cmi ~obj_dir ~version:ocaml.version ~cm_kind ~src m)
-          | (Ocaml Cmi | Melange Cmi), _, _ ->
+          | (Ocaml (Cmi | Cmti) | Melange Cmi), _, _ ->
             let+ () = copy_interface ~dir ~obj_dir ~sctx ~cm_kind m in
             Command.Args.empty))
    in
    let other_targets =
      match cm_kind with
-     | Ocaml (Cmi | Cmo) | Melange (Cmi | Cmj) -> Command.Args.empty
+     | Ocaml (Cmi | Cmo | Cmt | Cmti) | Melange (Cmi | Cmj) -> Command.Args.empty
      | Ocaml Cmx ->
        (match phase with
         | Some Compile ->
@@ -215,6 +215,7 @@ let build_cm
    let cmt_args =
      match cm_kind with
      | Ocaml Cmx -> Command.Args.empty
+     | Ocaml (Cmt | Cmti) -> As [ "-bin-annot" ]
      | Ocaml (Cmi | Cmo) | Melange (Cmi | Cmj) ->
        if Compilation_context.bin_annot cctx
        then (

src/dune_rules/obj_dir.ml

@@ -90,7 +90,7 @@ module External = struct
     | Ocaml Cmi, Public, _ -> public_cmi_ocaml_dir t
     | Melange Cmi, Public, _ -> public_cmi_melange_dir t
     | Melange Cmj, _, _ -> t.melange_dir
-    | Ocaml (Cmo | Cmx), _, _ -> t.public_dir
+    | Ocaml (Cmo | Cmx | Cmt | Cmti), _, _ -> t.public_dir
   ;;
 
   let encode
@@ -165,7 +165,7 @@ module External = struct
   let cm_public_dir t (cm_kind : Lib_mode.Cm_kind.t) =
     match cm_kind with
     | Ocaml Cmx -> native_dir t
-    | Ocaml Cmo -> byte_dir t
+    | Ocaml (Cmo | Cmt | Cmti) -> byte_dir t
     | Ocaml Cmi -> public_cmi_ocaml_dir t
     | Melange Cmj -> melange_dir t
     | Melange Cmi -> public_cmi_melange_dir t
@@ -321,14 +321,14 @@ module Local = struct
   let cm_dir t (cm_kind : Lib_mode.Cm_kind.t) _ =
     match cm_kind with
     | Ocaml Cmx -> native_dir t
-    | Ocaml (Cmo | Cmi) -> byte_dir t
+    | Ocaml (Cmo | Cmi | Cmt | Cmti) -> byte_dir t
     | Melange (Cmj | Cmi) -> melange_dir t
   ;;
 
   let cm_public_dir t (cm_kind : Lib_mode.Cm_kind.t) =
     match cm_kind with
     | Ocaml Cmx -> native_dir t
-    | Ocaml Cmo -> byte_dir t
+    | Ocaml (Cmo | Cmt | Cmti) -> byte_dir t
     | Ocaml Cmi -> public_cmi_ocaml_dir t
     | Melange Cmj -> melange_dir t
     | Melange Cmi -> public_cmi_melange_dir t
@@ -513,7 +513,8 @@ module Module = struct
 
   let has_impl_if_needed m ~(kind : Lib_mode.Cm_kind.t) =
     match kind with
-    | Ocaml (Cmo | Cmx) | Melange Cmj -> Module.has m ~ml_kind:Impl
+    | Ocaml (Cmo | Cmx | Cmt) | Melange Cmj -> Module.has m ~ml_kind:Impl
+    | Ocaml Cmti -> Module.has m ~ml_kind:Intf
     | Ocaml Cmi | Melange Cmi -> true
   ;;
 
@@ -575,17 +576,20 @@ module Module = struct
 
   let cmt_file t m ~(ml_kind : Ml_kind.t) ~cm_kind =
     let file = Module.file m ~ml_kind in
-    let ext = Ml_kind.cmt_ext ml_kind in
+    let ext =
+      match ml_kind with
+      | Impl -> Cm_kind.ext Cmt
+      | Intf -> Cm_kind.ext Cmti
+    in
     let cmi_kind = Lib_mode.Cm_kind.cmi cm_kind in
     Option.map file ~f:(fun _ -> obj_file t m ~kind:cmi_kind ~ext)
   ;;
 
   let cmti_file t m ~cm_kind =
     let ext =
-      Ml_kind.cmt_ext
-        (match Module.file m ~ml_kind:Intf with
-         | None -> Impl
-         | Some _ -> Intf)
+      match Module.file m ~ml_kind:Intf with
+      | None -> Cm_kind.ext Cmt
+      | Some _ -> Cm_kind.ext Cmti
     in
     let cmi_kind = Lib_mode.Cm_kind.cmi cm_kind in
     obj_file t m ~kind:cmi_kind ~ext

src/ocaml/cm_kind.ml

@@ -4,6 +4,8 @@ type t =
   | Cmi
   | Cmo
   | Cmx
+  | Cmt
+  | Cmti
 
 let compare x y : Ordering.t =
   match x, y with
@@ -14,34 +16,54 @@ let compare x y : Ordering.t =
   | Cmo, _ -> Lt
   | _, Cmo -> Gt
   | Cmx, Cmx -> Eq
+  | Cmx, _ -> Lt
+  | _, Cmx -> Gt
+  | Cmt, Cmt -> Eq
+  | Cmt, _ -> Lt
+  | _, Cmt -> Gt
+  | Cmti, Cmti -> Eq
 ;;
 
-let all = [ Cmi; Cmo; Cmx ]
+let all = [ Cmi; Cmo; Cmx; Cmt; Cmti ]
 
-let choose cmi cmo cmx = function
+let choose cmi cmo cmx cmt cmti = function
   | Cmi -> cmi
   | Cmo -> cmo
   | Cmx -> cmx
+  | Cmt -> cmt
+  | Cmti -> cmti
 ;;
 
-let ext = choose ".cmi" ".cmo" ".cmx"
-let source = choose Ml_kind.Intf Impl Impl
+let ext = choose ".cmi" ".cmo" ".cmx" ".cmt" ".cmti"
+let source = choose Ml_kind.Intf Impl Impl Impl Intf
 
 module Dict = struct
   type 'a t =
     { cmi : 'a
     ; cmo : 'a
     ; cmx : 'a
+    ; cmt : 'a
+    ; cmti : 'a
     }
 
   let get t = function
     | Cmi -> t.cmi
     | Cmo -> t.cmo
     | Cmx -> t.cmx
+    | Cmt -> t.cmt
+    | Cmti -> t.cmti
   ;;
 
-  let of_func f = { cmi = f ~cm_kind:Cmi; cmo = f ~cm_kind:Cmo; cmx = f ~cm_kind:Cmx }
-  let make_all x = { cmi = x; cmo = x; cmx = x }
+  let of_func f =
+    { cmi = f ~cm_kind:Cmi
+    ; cmo = f ~cm_kind:Cmo
+    ; cmx = f ~cm_kind:Cmx
+    ; cmt = f ~cm_kind:Cmt
+    ; cmti = f ~cm_kind:Cmti
+    }
+  ;;
+
+  let make_all x = { cmi = x; cmo = x; cmx = x; cmt = x; cmti = x }
 end
 
 let to_dyn =
@@ -50,4 +72,6 @@ let to_dyn =
   | Cmi -> variant "cmi" []
   | Cmo -> variant "cmo" []
   | Cmx -> variant "cmx" []
+  | Cmt -> variant "cmt" []
+  | Cmti -> variant "cmti" []
 ;;

src/ocaml/cm_kind.mli

@@ -4,6 +4,8 @@ type t =
   | Cmi
   | Cmo
   | Cmx
+  | Cmt
+  | Cmti
 
 val compare : t -> t -> Ordering.t
 val all : t list
@@ -18,6 +20,8 @@ module Dict : sig
     { cmi : 'a
     ; cmo : 'a
     ; cmx : 'a
+    ; cmt : 'a
+    ; cmti : 'a
     }
 
   val get : 'a t -> cm_kind -> 'a