Skip to content

Conversation

jsternberg
Copy link
Collaborator

@jsternberg jsternberg commented Jun 11, 2025

Adds a simple implementation of the debug adapter that supports the very
basics of a debug adapter.

It supports the launch request, the configuration done request, the
creation of threads, stopping, resuming, and disconnecting from server.

It does not support custom breakpoints, stack traces, or variable
inspection yet. These are planned to be added in the future.

close(d.initialized)

// Set capabilities.
resp.Body.SupportsConfigurationDoneRequest = true
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SupportsTerminateRequest and SupportsRestartRequest seem to be needed to allow the terminate request and the restart request (c.f. https://microsoft.github.io/debug-adapter-protocol//specification.html )

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't added the functionality for Terminate and Restart yet. We're capable of them but the DAP adapter implementation isn't quite there yet.


`docker build`, `docker builder build`, `docker image build`, `docker buildx b`

### Options
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how these options can be used by editors. Maybe these flags will be need to be moved to the launch config when this DAP plugin allows the editor to invoke the build through the launch request.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intention is the debug adapter implementation would translate these to command line arguments. It might be worth putting them into the launch config though just to keep things consistent.

Here's an example: https://github.com/docker/nvim-dap-docker/blob/27f73dae22a4be31caaacc37ce4ba8566a1fbcc5/lua/dap-docker.lua#L19-L29

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the example.

The intention is the debug adapter implementation would translate these to command line arguments. It might be worth putting them into the launch config though just to keep things consistent.

Sure. launch.json support can be following up.

dap/adapter.go Outdated
return nil
}

type LaunchConfig struct {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will this be used for build flags as well? (e.g. the user can write the build flags to launch.json instead of to the global editor config file) If so, the Launch handler will somehow need to be able to trigger the build.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't quite determined how that is. For neovim, the adapter is the one that reads the launch.json file and it can then invoke the tool with the correct arguments. My initial thought was to have the editor translate the JSON launch arguments to the appropriate CLI arguments. I have to see how the VSCode side works though to see what is better.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My initial thought was to have the editor translate the JSON launch arguments to the appropriate CLI arguments.

👍

I have to see how the VSCode side works though to see what is better.

IIUC, in all of nvim, VSCode(startDebugging API), and emacs (dap-mode), DAP plugin can receive launch.json contents from LaunchRequest.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've changed the method for how this works and it now supports a combination. Any arguments provided on the command line will be used (to facilitate direct usage or arbitrary args from a plugin/extension) but certain JSON arguments can be used to override any command line arguments. Options that are considered very common will go into JSON properties while the "args" can be a catch-all for everything else.

So launch.json would end up looking like this:

{
    "type": "dockerfile",
    "request": "launch",
    "dockerfile": "Dockerfile",
    "contextPath": "${workspacePath}",
    "target": "mytarget",
    "args": "--build-arg FOO=1"
}

@jsternberg jsternberg force-pushed the dap-handler branch 7 times, most recently from 74ec803 to b160d3d Compare June 13, 2025 20:16
@jsternberg
Copy link
Collaborator Author

After merging this, here are some proposed follow up issues.

  • Implement stack traces
  • Add breakpoint support
  • Add support for the restart request
  • Add support for the terminate request
  • Add build args and environment variables to stack traces
  • Add support for invoke through evaluate and a reverse request

@jsternberg jsternberg added this to the v0.26.0 milestone Jun 17, 2025
@jsternberg jsternberg force-pushed the dap-handler branch 4 times, most recently from baa8cdf to 829b6f3 Compare June 23, 2025 18:58
@jsternberg jsternberg force-pushed the dap-handler branch 4 times, most recently from 8147e0a to ffdd0bf Compare June 24, 2025 14:46
Copy link
Collaborator

@ktock ktock left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks.

Adds a simple implementation of the debug adapter that supports the very
basics of a debug adapter.

It supports the launch request, the configuration done request, the
creation of threads, stopping, resuming, and disconnecting from server.

It does not support custom breakpoints, stack traces, or variable
inspection yet. These are planned to be added in the future.

Signed-off-by: Jonathan A. Sternberg <jonathan.sternberg@docker.com>
Comment on lines +472 to +474
if len(args) > 0 {
options.contextPath = args[0]
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you encounter an exception without this change?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was mostly to allow the dap build command to reuse build but not require the required argument. Another portion of the code will catch that this is missing later but it allows calling buildx dap build and letting the context path to be sent later by the launch arguments.

It doesn't impact the normal build command because cobra will never let the code get there.

@tonistiigi tonistiigi merged commit 758ea75 into docker:master Jul 2, 2025
203 of 204 checks passed
@jsternberg jsternberg deleted the dap-handler branch July 2, 2025 20:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants