ocaml · rgrinberg · Nov 15, 2025 · Oct 27, 2025 · Nov 10, 2025 · Nov 12, 2025
diff --git a/doc/advanced/variables-artifacts.rst b/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>``).
diff --git a/doc/changes/added/12634.md b/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)
diff --git a/src/dune_lang/lib_mode.ml b/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
 ;;

diff --git a/src/dune_lang/pform.ml b/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

diff --git a/src/dune_rules/check_rules.ml b/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
 ;;

diff --git a/src/dune_rules/module_compilation.ml b/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 (

diff --git a/src/dune_rules/obj_dir.ml b/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

diff --git a/src/ocaml/cm_kind.ml b/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,18 +16,36 @@ 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
+
+let to_dyn =
+  let open Dyn in
+  function
+  | Cmi -> variant "cmi" []
+  | Cmo -> variant "cmo" []
+  | Cmx -> variant "cmx" []
+  | Cmt -> variant "cmt" []
+  | Cmti -> variant "cmti" []
+;;
 
 module Dict = struct
   type 'a t =
@@ -38,16 +58,12 @@ module Dict = struct
     | Cmi -> t.cmi
     | Cmo -> t.cmo
     | Cmx -> t.cmx
+    | (Cmt | Cmti) as cm_kind ->
+      Code_error.raise
+        "Cm_kind.Dict.get doesnt support this case"
+        [ "cm_kind", to_dyn cm_kind ]
   ;;
 
   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 }
 end
-
-let to_dyn =
-  let open Dyn in
-  function
-  | Cmi -> variant "cmi" []
-  | Cmo -> variant "cmo" []
-  | Cmx -> variant "cmx" []
-;;
diff --git a/src/ocaml/cm_kind.mli b/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

diff --git a/src/ocaml/ml_kind.ml b/src/ocaml/ml_kind.ml
@@ -15,11 +15,6 @@ let choose t ~impl ~intf =
 let to_string = choose ~impl:"impl" ~intf:"intf"
 let to_dyn t = Dyn.String (to_string t)
 
-let cmt_ext = function
-  | Impl -> ".cmt"
-  | Intf -> ".cmti"
-;;
-
 module Dict = struct
   type 'a t =
     { impl : 'a

diff --git a/src/ocaml/ml_kind.mli b/src/ocaml/ml_kind.mli
@@ -8,7 +8,6 @@ val all : t list
 val choose : t -> impl:'a -> intf:'a -> 'a
 val to_string : t -> string
 val to_dyn : t -> Dyn.t
-val cmt_ext : t -> string
 
 module Dict : sig
   type kind := t
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,8 @@ type t = @@
       | Cmi
       | Cmo
       | Cmx
+      | Cmt
+      | Cmti
     val compare : t -> t -> Ordering.t
     val all : t list
@@ Expand Down @@