Skip to content

Files

Latest commit

c0bf25b · May 9, 2025

History

History
160 lines (89 loc) · 6.39 KB

UserGuide.md

File metadata and controls

160 lines (89 loc) · 6.39 KB

Debug Adapter Protocol

LSP4IJ provides Debug Adapter Protocol support. You can read the DAP Support overview, describing which DAP features are implemented, and how. If you need to customize the DAP support you can register your DAP server with extension point.

The DAP support is available with the Debug Adapter Protocol run/debug configuration type:

DAP Configuration Type

After configuring the DAP configuration type, you can debug your file.

Here is an example with JavaScript debugging, which uses the VSCode JS Debug DAP server:

DAP Configuration Type

DAP Configuration Type:

To configure debugging with DAP, you need to fill in:

Server tab

The Server tab to specify the DAP server:

DAP Configuration Type/Server

Mappings tab

The Mappings tab to specify the files which can be debugged to allow adding/removing breakpoints:

DAP Configuration Type/Mappings

Configuration tab

The Configuration tab to specify the working directory and the file you want to run/debug:

DAP Configuration Type/Configuration

Breakpoints

Adding breakpoint

When a file can be debugged using a DAP server specified in the Mappings tab, a breakpoint can be added.

DAP Breakpoint set

Verify breakpoint

When the DAP server starts, breakpoints are sent to it, and it responds with the status of those breakpoints — whether they are validated or not.

For example, when the DAP server VSCode JS Debug starts, it invalidates all breakpoints.:

DAP Breakpoint invalid

When the program starts, it checks and validates the breakpoints.

DAP Breakpoint invalid

Conditional breakpoint

Conditional breakpoints are also supported. Here is an example of a conditional breakpoint written in JavaScript:

DAP Conditional Breakpoint

Exception breakpoint

Some DAP servers support exception breakpoints. If so, you must first run the configuration process, which starts the DAP server and retrieves the list of available exception breakpoints. This list is accessible through the Exception Breakpoints menu:

DAP exception breakpoints

The first time, the selected exception breakpoints are based on the default configuration provided by the DAP server.

You can then select or deselect the exception breakpoints you want to use.

Take a sample JavaScript file containing an error:

DAP exception breakpoint / Syntax error

In this example, no breakpoints are defined. However, when you start the DAP server, it stops at the line with the line error:

DAP exception breakpoint / Syntax error

This happens because Caught Exceptions is selected.

Inline value

The values of the variables are displayed inline, but this is not perfect because a DAP server generally cannot handle variable positions (only their values). To retrieve the variable positions, LSP4IJ uses the syntax highlighting information from the editor (TextMate or others).

Here a de demo with JavaScript:

DAP inline value

Theoretically, inline values should be handled by a language server via textDocument/inlineValue but as no language servers seems implement this LSP request for the moment LSP4IJ doesn't use this strategy.

Evaluate expression

Evaluate expression is available by consuming the Evaluate request

Evaluate expression

Completion

If debug adapter supports the completions request, completion should be available in the expression editor by consuming the Completion request:

Completion

Set value

If debug adapter supports setting a variable to a value, the Set Value... contextual menu should be available:

Set Value/Menu

You should edit the variable:

Set Value/Edit

the edit apply will consume the SetVariable request:

Contextual Menu

Click on right button open existing / new DAP run configuration:

Run/Debug menu

DAP server traces

If you wish to show DAP request/response traces when you will debug:

Show DAP traces

you need to select Trace with verbose.

Set verbose traces

DAP settings

You can create/remove/update DAP servers with Debug Adapter Protocol entry:

DAP settings

Templates

LSP4IJ provides DAP templates that allow to initialize a given DAP server very quickly: