OCaml earlybird debugger #1148

sim642 · 2023-06-23T10:04:45Z

Closes #534.

This is more-or-less a port of earlybird's own small VSCode extension to OCaml: https://github.com/hackwaly/ocamlearlybird/tree/271bdd877ae285c06df1d4e90bc1d11dbdf83fb5/integrations/vscode. Parts of this port are borrowed from the earlier attempt #650.

Unlike that earlier attempt, this contains no dune executable detection or anything of that sort. It simply allows the earlybird DAP server to be launched if it is installed in the opam switch. The only additional integration is that ocamlearlybird is launched from the switch chosen in this extension.

By the way, I have picked up maintaining and updating earlybird itself such that it works on newer OCaml versions, but that is not yet released (only available directly from https://github.com/hackwaly/ocamlearlybird). It would be nice if this PR was part of the revival of earlybird, such that its own extension could be deprecated.

Co-authored-by: 文宇祥 <hackwaly@qq.com>

tmattio · 2023-06-23T10:20:20Z

I'm thrilled to see this PR, thanks a lot for working on this @sim642!

Coincidentally, we've had a lot of discussions related to debugging with the OCaml Platform team recently. One thing that was blocking the adoption of earlybird was its license. I see that you've moved the code (I assume with the permission of the author) to be licensed under MIT. That's great, this is going to enable the use of earlybird in the Platform!

Before we consider using earlybird as a DAP in VSCode, it'd be great to incubate it in the Platform: the vscode extension is a driver for the tools of the OCaml Platform. Would you be ok to work together on an RFC for the incubation of early bird as part of your work to have earlybird used in VSCode?

tmattio · 2023-06-23T12:29:31Z

We discussed this further with @rgrinberg.

We agree that promoting an incubation too early doesn't make sense. At the same time, an integration in VSCode would help earlybird to get the user feedback and user testing it needs to demonstrate that it's ready for incubation in the Platform.

We'll still want to wait for it to be incubated to fully commit to maintaining an integration, but in the immediate term, we could merge a first integration behind an experimental flag.

sim642 · 2023-06-23T12:55:41Z

I see that you've moved the code (I assume with the permission of the author) to be licensed under MIT.

That was done by the original author in hackwaly/ocamlearlybird@a4398c4.

We'll still want to wait for it to be incubated to fully commit to maintaining an integration, but in the immediate term, we could merge a first integration behind an experimental flag.

Fair enough, although I'm not sure it's possible to put the debugger declaration behind a configuration option in package.json.

tmattio · 2023-06-23T13:04:56Z

I'm not sure it's possible to put the debugger declaration behind a configuration option in package.json.

We could maintain a staging branch for pre-release versions (https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions)

rgrinberg · 2023-06-23T13:14:25Z

I would personally lean towards just marking this feature as "experimental" in big letters and making it available without much hassle. At this point, the main advantage of integrating this feature would be to gather some user experience reports from using it. It would be counter productive to make people go through another step before they're able to use this.

sim642 · 2023-06-23T13:34:52Z

I would personally lean towards just marking this feature as "experimental" in big letters and making it available without much hassle.

Indeed as-is this isn't too visible: it just shows up in the list of debuggers when trying to add a a debug configuration and in the context menu for .bc files. Right now there aren't any messages suggesting to opam install earlybird either.

I'll append "experimental" to the registered debugger name, etc, which should be visible to anyone trying to activate it.

tmattio · 2023-06-23T13:55:30Z

Alright, as long as (1) we're comfortable we'll be able to remove support (without alienating users) in case we see that earlybird isn't ready for wide adoption just yet, or that the maintenance status becomes unclear in the future and (2) we have in mind that we should aim for incubation to commit to long term support - I'm happy to go with the integration you see fit.

mnxn

Nice work with the binding changes!
I added a comment about one more issue in the code that I overlooked.

I attempted to use the debugger yesterday on macOS, but wasn't able to get it to work. I'll try again soon, but I think that either my setup is broken or there might be a lack of feedback on invalid configurations.

src/earlybird.ml

mnxn

I got the debugging feature working on macOS. The only awkward behavior I noticed was that the debugger doesn't terminate if the a.out file (from the default launch configuration) doesn't exist. The integrated terminal will show a missing file error, but the VS Code debugging UI still stays active. I'm not sure there's a way to present an VS Code error in this case, but it might be worth looking into in the future.

I believe this PR is ready to merge in a experimental state.

sim642 · 2023-07-04T08:07:56Z

The only awkward behavior I noticed was that the debugger doesn't terminate if the a.out file (from the default launch configuration) doesn't exist. The integrated terminal will show a missing file error, but the VS Code debugging UI still stays active. I'm not sure there's a way to present an VS Code error in this case, but it might be worth looking into in the future.

Thanks for the feedback! As a quick improvement I changed that a.out path to something more suggestive.
In some further future it'd be nice if the extension could get a list of executables from dune and the debugging configurations would be suggested dynamically from them.

rgrinberg · 2023-07-08T09:17:46Z

src-bindings/vscode/vscode.ml

      -> ?column:ViewColumn.t
      -> ?preserveFocus:bool
      -> unit
      -> TextEditor.t Promise.t
      [@@js.global "vscode.window.showTextDocument"]

-    val showTextDocument2 :
+    val showTextDocument' :


Could you describe the issue this commit is fixing? I think also putting it in a separate PR would be valuable.

In VSCode extension API showTextDocument has a couple of overloads. Specifically the cases without TextDocumentShowOptions only take TextDocument arguments, not Uri: https://code.visualstudio.com/api/references/vscode-api#window.showTextDocument.

I think there wasn't a problem before because the Uri overload is not used by OCaml Platform.

src/earlybird.ml

mnxn · 2023-07-08T16:51:12Z

The debugging feedback is much better now when the file doesn't exist.
I'm still concerned that the initial configuration is invalid by default.

The VS Code debugger extension example shows a way to ask for a program name: https://code.visualstudio.com/api/extension-guides/debugger-extension#anatomy-of-the-package.json-of-a-debugger-extension

Maybe it would be better to ask for a path to the program to debug that way?

sim642 · 2023-07-08T17:00:15Z

I think I can give it a try although typing in a long path into _build into a pop-up dialog isn't super convenient either. The most convenient way is to use the "Start debugging" command from the file explorer context menu on a .bc file, although it's completely undiscoverable right now.
I should probably also add something to README about the debugging support, both for OCaml Platform and earlybird itself (if OCaml Platform becomes the new way to use it).

mnxn · 2023-07-08T17:09:22Z

I agree writing a long path isn't ideal, but I think having this behavior is the best option for now. In the future (depending on how the experiment progresses), the command could be changed to list executables built by dune like you mention.

In the meantime, you can describe the right-click workflow in the README so it's easier to find.

sim642 · 2023-07-09T10:26:49Z

I agree writing a long path isn't ideal, but I think having this behavior is the best option for now. In the future (depending on how the experiment progresses), the command could be changed to list executables built by dune like you mention.

I found a nice compromise using vscode.window.showOpenDialog and implemented it for the ask command.

In the meantime, you can describe the right-click workflow in the README so it's easier to find.

That and other information about earlybird is now in the README.

src/earlybird.ml

CHANGES: ### Added * Add OCaml 4.13, 4.14 and 5.0 support. * Add `--version` command line option. ### Changed * Relicense under MIT (from GPL). * Deprecate own VSCode extension in favor of VSCode OCaml Platform integration: ocamllabs/vscode-ocaml-platform#1148. ### Fixed * Fix being stuck if program doesn't exist (hackwaly/ocamlearlybird#49). ### Removed * Remove OCaml 4.11 support.

sim642 and others added 22 commits June 22, 2023 14:05

Add debug adapter to vscode bindings

a8377fe

Co-authored-by: 文宇祥 <hackwaly@qq.com>

Import metadata from earlybird

4f0cdc2

Co-authored-by: 文宇祥 <hackwaly@qq.com>

Port parts of earlybird extension

cc64062

Co-authored-by: 文宇祥 <hackwaly@qq.com>

Implement variableGotoClosureCodeLocation command in debugger

795b752

Implement startDebug command in debugger

9fff993

Rename debugger to ocaml.earlybird

c64e416

Rename Debugger -> Earlybird

7deac33

Refactor Earlybird

54ab258

Improve debug debug adapter types

e5f6ea9

Refactor earlybird code

89fe841

Simplify debugger configurations

8d9a205

Remove unused noDebug from debugger

4642df3

Use full language IDs for breakpoints

66a950a

Rename earlybird commands

5db1408

Remove unnecessary earlybird configuration options

a6034db

Simplify start-debugging configuration

8c35503

Make startDebugging type more precise

6c3e538

Clean up goto-closure-code-location

3eed2cc

Clean up start-debugging

6593ab4

Fix variableGetClosureCodeLocation decoding

d7a823a

Fix showTextDocument overloads

bc56b2d

Add earlybird to CHANGELOG

4b5ffd2

Mention earlybird integration being expermental

83c3799

sim642 requested a review from mnxn June 29, 2023 08:21

mnxn requested changes Jun 30, 2023

View reviewed changes

src/earlybird.ml Outdated Show resolved Hide resolved

Support custom sandbox in Earlybird

1f65a5a

mnxn approved these changes Jul 3, 2023

View reviewed changes

Replace a.out in default earlybird configuration

7a2f76a

sim642 mentioned this pull request Jul 4, 2023

Debugger stays active when program is missing hackwaly/ocamlearlybird#49

Closed

smorimoto added the type: feature New feature or request label Jul 7, 2023

rgrinberg reviewed Jul 8, 2023

View reviewed changes

src/earlybird.ml Show resolved Hide resolved

Add Earlybird module interface

da6b9be

sim642 force-pushed the earlybird branch from 98a6bad to da6b9be Compare July 8, 2023 16:29

sim642 added 3 commits July 9, 2023 12:45

Add ocaml.ask-debug-program command to initial debug configuration

10be2a5

Add earlybird configuration snippet

f4b5fb6

Add stopOnEntry to automatic debug configurations

bd5ba01

Add earlybird to README

13595c9

sim642 force-pushed the earlybird branch from b7ae065 to 13595c9 Compare July 9, 2023 10:45

rgrinberg reviewed Jul 9, 2023

View reviewed changes

src/earlybird.ml Outdated Show resolved Hide resolved

rgrinberg reviewed Jul 9, 2023

View reviewed changes

src/earlybird.ml Outdated Show resolved Hide resolved

sim642 added 2 commits July 9, 2023 21:19

Only leave .bc for earlybird

8e684e6

Add earlybird availability check

a205b96

rgrinberg added this to the 1.13.0 milestone Jul 11, 2023

rgrinberg merged commit 3d184cd into ocamllabs:master Jul 11, 2023

sim642 mentioned this pull request Jul 11, 2023

[new release] earlybird (1.2.0) ocaml/opam-repository#24095

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OCaml earlybird debugger #1148

OCaml earlybird debugger #1148

sim642 commented Jun 23, 2023

tmattio commented Jun 23, 2023

tmattio commented Jun 23, 2023

sim642 commented Jun 23, 2023

tmattio commented Jun 23, 2023

rgrinberg commented Jun 23, 2023

sim642 commented Jun 23, 2023

tmattio commented Jun 23, 2023

mnxn left a comment

mnxn left a comment

sim642 commented Jul 4, 2023

rgrinberg Jul 8, 2023

sim642 Jul 8, 2023

mnxn commented Jul 8, 2023 •

edited

Loading

sim642 commented Jul 8, 2023

mnxn commented Jul 8, 2023

sim642 commented Jul 9, 2023

OCaml earlybird debugger #1148

OCaml earlybird debugger #1148

Conversation

sim642 commented Jun 23, 2023

tmattio commented Jun 23, 2023

tmattio commented Jun 23, 2023

sim642 commented Jun 23, 2023

tmattio commented Jun 23, 2023

rgrinberg commented Jun 23, 2023

sim642 commented Jun 23, 2023

tmattio commented Jun 23, 2023

mnxn left a comment

Choose a reason for hiding this comment

mnxn left a comment

Choose a reason for hiding this comment

sim642 commented Jul 4, 2023

rgrinberg Jul 8, 2023

Choose a reason for hiding this comment

sim642 Jul 8, 2023

Choose a reason for hiding this comment

mnxn commented Jul 8, 2023 • edited Loading

sim642 commented Jul 8, 2023

mnxn commented Jul 8, 2023

sim642 commented Jul 9, 2023

mnxn commented Jul 8, 2023 •

edited

Loading