Looking up paths to executables with dune which

gridbugs · gridbugs · commit 79e5ff21d413 · 2025-06-18T14:28:14.000+10:00
The "dune exec" command has three different ways of resolving the
names of executables to paths to executables:
 - public executables defined in the current project
 - executables in the "bin" directories of dependencies
 - executables in directories listed in $PATH

This can lead to unexpected shadowing, especially in the case of
executables from dependecies, as users may not be aware that one of
the packages in their project's dependency cone defines an executable
with the same name of an executable that's also insalled system-wide.

Short of fixing the problem for now, this change introduces a tool for
helping investigate specifically which executable will be run by "dune
exec". This adds a command "dune which" which prints the path to the
executable.

Signed-off-by: Stephen Sherratt &lt;stephen@sherra.tt&gt;
diff --git a/bin/exec.ml b/bin/exec.ml
@@ -111,19 +111,26 @@ let build_prog ~no_rebuild ~prog p =
     p
 ;;
 
-let get_path_and_build_if_necessary sctx ~no_rebuild ~dir ~prog =
+let expand ~sctx common cmd_arg = Cmd_arg.expand ~root:(Common.root common) ~sctx cmd_arg
+
+let get_path common ctx_name ~prog =
   let open Memo.O in
+  let* sctx = Super_context.find_exn ctx_name in
+  let dir =
+    let context = Dune_rules.Super_context.context sctx in
+    Path.Build.relative (Context.build_dir context) (Common.prefix_target common "")
+  in
   match Filename.analyze_program_name prog with
   | In_path ->
     Super_context.resolve_program_memo sctx ~dir ~loc:None prog
     >>= (function
      | Error (_ : Action.Prog.Not_found.t) -> not_found ~dir ~prog
-     | Ok p -> build_prog ~no_rebuild ~prog p)
+     | Ok p -> Memo.return p)
   | Relative_to_current_dir ->
     let path = Path.relative_to_source_in_build_or_external ~dir prog in
     Build_system.file_exists path
     >>= (function
-     | true -> build_prog ~no_rebuild ~prog path
+     | true -> Memo.return path
      | false -> not_found ~dir ~prog)
   | Absolute ->
     (match
@@ -140,19 +147,22 @@ let get_path_and_build_if_necessary sctx ~no_rebuild ~dir ~prog =
      | None -> not_found ~dir ~prog)
 ;;
 
-let step ~setup ~prog ~args ~common ~no_rebuild ~context ~on_exit () =
+let get_path_and_build_if_necessary common ctx_name ~no_rebuild ~prog =
   let open Memo.O in
-  let* sctx = setup >>| Import.Main.find_scontext_exn ~name:context in
-  let* env = Super_context.context_env sctx in
-  let expand = Cmd_arg.expand ~root:(Common.root common) ~sctx in
+  let* path = get_path common ctx_name ~prog in
+  match Filename.analyze_program_name prog with
+  | In_path | Relative_to_current_dir -> build_prog ~no_rebuild ~prog path
+  | Absolute -> Memo.return path
+;;
+
+let step ~prog ~args ~common ~no_rebuild ~ctx_name ~on_exit () =
+  let open Memo.O in
+  let* sctx = Super_context.find_exn ctx_name in
   let* path =
-    let dir =
-      let context = Dune_rules.Super_context.context sctx in
-      Path.Build.relative (Context.build_dir context) (Common.prefix_target common "")
-    in
-    let* prog = expand prog in
-    get_path_and_build_if_necessary sctx ~no_rebuild ~dir ~prog
-  and* args = Memo.parallel_map args ~f:expand in
+    let* prog = expand ~sctx common prog in
+    get_path_and_build_if_necessary common ctx_name ~no_rebuild ~prog
+  and* args = Memo.parallel_map args ~f:(expand ~sctx common) in
+  let* env = Super_context.context_env sctx in
   Memo.of_non_reproducible_fiber
   @@ Dune_engine.Process.run_inherit_std_in_out
        ~dir:(Path.of_string Fpath.initial_cwd)
@@ -166,7 +176,7 @@ let step ~setup ~prog ~args ~common ~no_rebuild ~context ~on_exit () =
 
 let term : unit Term.t =
   let+ builder = Common.Builder.term
-  and+ context = Common.context_arg ~doc:{|Run the command in this build context.|}
+  and+ ctx_name = Common.context_arg ~doc:{|Run the command in this build context.|}
   and+ prog = Arg.(required & pos 0 (some Cmd_arg.conv) None (Arg.info [] ~docv:"PROG"))
   and+ no_rebuild =
     Arg.(value & flag & info [ "no-build" ] ~doc:"don't rebuild target before executing")
@@ -182,30 +192,25 @@ let term : unit Term.t =
     Scheduler.go_with_rpc_server_and_console_status_reporting ~common ~config
     @@ fun () ->
     let open Fiber.O in
-    let* setup = Import.Main.setup () in
     let on_exit = Console.printf "Program exited with code [%d]" in
     Scheduler.Run.poll
     @@
     let* () = Fiber.return @@ Scheduler.maybe_clear_screen ~details_hum:[] config in
-    build @@ step ~setup ~prog ~args ~common ~no_rebuild ~context ~on_exit
+    build @@ step ~prog ~args ~common ~no_rebuild ~ctx_name ~on_exit
   | No ->
     Scheduler.go_with_rpc_server ~common ~config
     @@ fun () ->
     let open Fiber.O in
     let* setup = Import.Main.setup () in
     build_exn (fun () ->
       let open Memo.O in
-      let* sctx = setup >>| Import.Main.find_scontext_exn ~name:context in
-      let* env = Super_context.context_env sctx in
-      let expand = Cmd_arg.expand ~root:(Common.root common) ~sctx in
-      let* prog =
-        let dir =
-          let context = Dune_rules.Super_context.context sctx in
-          Path.Build.relative (Context.build_dir context) (Common.prefix_target common "")
-        in
-        let* prog = expand prog in
-        get_path_and_build_if_necessary sctx ~no_rebuild ~dir ~prog >>| Path.to_string
-      and* args = Memo.parallel_map ~f:expand args in
+      let* sctx = setup >>| Import.Main.find_scontext_exn ~name:ctx_name in
+      let* env = Super_context.context_env sctx
+      and* prog =
+        let* prog = expand ~sctx common prog in
+        get_path_and_build_if_necessary common ctx_name ~no_rebuild ~prog
+        >>| Path.to_string
+      and* args = Memo.parallel_map ~f:(expand ~sctx common) args in
       restore_cwd_and_execve (Common.root common) prog args env)
 ;;
 
diff --git a/bin/exec.mli b/bin/exec.mli
@@ -1,3 +1,17 @@
 open Import
 
+(** Returns the path to the executable [prog] as it will be resolved by dune:
+  - if [prog] is the name of an executable defined by the project then the path
+    to that executable will be returned, and evaluating the returned memo will
+    build the executable if necessary.
+  - otherwise if [prog] is the name of an executable in the "bin" directory of
+    a package in this project's dependency cone then the path to that executable
+    file will be returned. Note that for this reason all dependencies of the
+    project will be built when the returned memo is evaluated (unless the first
+    case is hit).
+  - otherwise if [prog] is the name of an executable in one of the directories
+    listed in the PATH environment variable, the path to that executable will be
+    returned. *)
+val get_path : Common.t -> Context_name.t -> prog:string -> Path.t Memo.t
+
 val command : unit Cmd.t
diff --git a/bin/main.ml b/bin/main.ml
@@ -11,6 +11,7 @@ let all : _ Cmdliner.Cmd.t list =
       ; Install_uninstall.install
       ; Install_uninstall.uninstall
       ; Exec.command
+      ; Which.command
       ; Subst.command
       ; Print_rules.command
       ; Utop.command
diff --git a/bin/which.ml b/bin/which.ml
@@ -0,0 +1,37 @@
+open Import
+
+let doc =
+  "Print the path to the executable using the same resolution logic as [dune exec]."
+;;
+
+let man =
+  [ `S "DESCRIPTION"
+  ; `P
+      {|$(b,dune which NAME) prints the path to the executable NAME using the same logic as:
+          |}
+  ; `Pre "$ dune exec NAME"
+  ; `P
+      "Dune will first try to resolve the executable within the public executables in \
+       the current project, then inside the \"bin\" directory of each package among the \
+       project's  dependencies (when using dune package management), and finally within \
+       the  directories listed in the $PATH environment variable."
+  ]
+;;
+
+let info = Cmd.info "which" ~doc ~man
+
+let term : unit Term.t =
+  let+ builder = Common.Builder.term
+  and+ ctx_name = Common.context_arg ~doc:{|Run the command in this build context.|}
+  and+ prog = Arg.(required & pos 0 (some string) None (Arg.info [] ~docv:"PROG")) in
+  let common, config = Common.init builder in
+  Scheduler.go_with_rpc_server ~common ~config
+  @@ fun () ->
+  build_exn
+  @@ fun () ->
+  let open Memo.O in
+  let+ path = Exec.get_path common ctx_name ~prog >>| Path.to_string in
+  Console.print [ Pp.verbatim path ]
+;;
+
+let command = Cmd.v info term
diff --git a/bin/which.mli b/bin/which.mli
@@ -0,0 +1,3 @@
+open Import
+
+val command : unit Cmd.t
diff --git a/doc/changes/11905.md b/doc/changes/11905.md
@@ -0,0 +1,2 @@
+- Add `dune which` command for printing the path to the executable that would
+  be run by `dune exec` (#11905, @gridbugs)
diff --git a/test/blackbox-tests/test-cases/which.t b/test/blackbox-tests/test-cases/which.t
@@ -0,0 +1,62 @@
+Exercise the various ways of resolving executable names with `dune which`.
+
+  $ cat > dune-project << EOF
+  > (lang dune 3.20)
+  > 
+  > (package
+  >  (name foo))
+  > EOF
+
+  $ cat > dune << EOF
+  > (executable
+  >  (public_name foo))
+  > EOF
+
+  $ cat > foo.ml << EOF
+  > let () = print_endline "hello foo"
+  > EOF
+
+An executable that would be installed by the current package:
+  $ dune which foo
+  _build/install/default/bin/foo
+
+An executable from the current project:
+  $ dune which ./foo.exe
+  _build/default/foo.exe
+
+Test that executables from dependencies are located correctly:
+  $ mkdir dune.lock
+  $ cat > dune.lock/lock.dune << EOF
+  > (lang package 0.1)
+  > EOF
+  $ cat > dune.lock/bar.pkg << EOF
+  > (version 0.1)
+  > (install
+  >  (progn
+  >   (write-file %{bin}/bar "#!/bin/sh\necho hello bar")
+  >   (run chmod a+x %{bin}/bar)))
+  > EOF
+
+  $ cat > dune-project << EOF
+  > (lang dune 3.20)
+  > 
+  > (package
+  >  (name foo)
+  >  (depends bar))
+  > EOF
+
+  $ dune which bar
+  _build/_private/default/.pkg/bar/target/bin/bar
+
+Test that executables from PATH are located correctly:
+  $ mkdir bin
+  $ cat > bin/baz << EOF
+  > #!/bin/sh
+  > echo hello baz
+  > EOF
+
+  $ chmod a+x bin/baz
+  $ export PATH=$PWD/bin:$PATH
+
+  $ dune which baz
+  $TESTCASE_ROOT/bin/baz

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+open Import`
	`2`	`+`
	`3`	`+val command : unit Cmd.t`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+- Add `dune which` command for printing the path to the executable that would
	`2`	+ be run by `dune exec` (#11905, @gridbugs)