Skip to content

feat: dune shell for debugging rules - #15597

Draft
Alizter wants to merge 1 commit into
ocaml:mainfrom
Alizter:dune-shell
Draft

feat: dune shell for debugging rules#15597
Alizter wants to merge 1 commit into
ocaml:mainfrom
Alizter:dune-shell

Conversation

@Alizter

@Alizter Alizter commented Jul 24, 2026

Copy link
Copy Markdown
Collaborator

Intro

Suppose I was interested in the linking step for the dune binary:

[ali:~/dune]$ ./dune.exe shell %{bin:dune}
dune shell session commands:              
  run            replay the prepared action
  show_action    print or edit the expanded action ($DUNE_SHELL/action.sexp)
  show_command   print the exact direct program, args, and env
  help           show this message

sandbox mode none: this is the real _build directory; commands and run write there directly.
This is not an isolation boundary; commands can modify your source tree.
run clears the action's declared targets and replays only the action; it does not rebuild dependencies or pick up 
edits made after entry.

[ali:~/dune/_build/default]$ time run

real    0m0.860s
user    0m0.597s
sys     0m0.254s

If the rule was sandboxed, the interactive shell starts there:

[ali:~/dune]$ ./dune.exe shell --sandbox=symlink %{bin:dune}
dune shell session commands:              
  run            replay the prepared action
  show_action    print or edit the expanded action ($DUNE_SHELL/action.sexp)
  show_command   print the exact direct program, args, and env
  help           show this message

sandbox mode symlink: dependencies may point at shared build artifacts.
This is not an isolation boundary; commands can modify your source tree.
run clears the action's declared targets and replays only the action; it does not rebuild dependencies or pick up 
edits made after entry.

[ali:~/dune/_build/.sandbox/6af6aec5e6e5addeea316f9bdb9540af/default]$ 

Here run is a shell script wrapping a way for dune to run the action of the rule to check its performance etc.

Summary

  • add dune shell TARGET to open an interactive shell or run a command at a prepared rule action boundary
  • preserve the selected sandbox, execution directory, environment, live build, and locks for the session
  • expose the expanded action as an editable file with run and dune-run replay helpers
  • preserve raw process statuses and direct-process metadata for debugging tools
  • reject action shapes and execution modes whose session semantics are not yet faithful

Testing

  • ./dune.exe build @check @fmt
  • ./dune.exe runtest test/blackbox-tests/test-cases/dune-shell

Closes #3961

Add `dune shell TARGET` to prepare the rule producing TARGET up to its
action boundary, then open an interactive shell in the action execution
directory and environment. Preserve the selected sandbox and keep the
initiating build and its locks alive for the session. A command after `--`
runs non-interactively in the same prepared environment.

Expose the expanded action as an editable file and provide `run` and
`dune-run` helpers to replay it through the Dune action interpreter without
rebuilding dependencies or applying normal build post-processing such as
caching, promotion, sandbox extraction, or patch-back. Preserve direct
process metadata and raw exit statuses for debugging tools and scripts.

Document the sandbox and replay semantics in the interactive help. Reject
aliases, dynamic and concurrent actions, universe dependencies, action
extensions, patch-back rules, external action runners, watch mode, and
native Windows until faithful session semantics are defined for them.

Signed-off-by: Ali Caglayan <alizter@gmail.com>
@Alizter Alizter changed the title feat(shell): add prepared rule-action sessions Add dune shell for debugging rule actions Jul 24, 2026
@Alizter
Alizter marked this pull request as draft July 24, 2026 17:44
@Alizter Alizter changed the title Add dune shell for debugging rule actions feat: dune shell for debugging rules Jul 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[RFC] Use dune shell for testing failing command

1 participant