Perl Debug Adapter

This debug adapter invokes perl -d and handles communication with VS Code.

It should work out of the box on Linux, Windows and Mac using VS Code. It also works inside Microsofts Remote Extensions Remote-SSH, Remote-WSL and Remote-Containers.

Setup

VS Code

• Install the Perl5 Debug Adapter extension in VS Code.
• Perl needs to be installed and the path of the perl executable either needs to be available inside the $PATH environment variable or be provided via the launch.json configuration file.
• The PadWalker module needs to be available in your environment.
• OPTIONAL I recommend using this extension together with BSCANs Perl Navigator as it provides great language server features out of the box.

Forked Perl debugging requires the socket transport. The adapter now defaults to socket so perl5db can attach child debugger runtimes over TCP loopback.

When explicitly using stdio, forked Perl debugging is still unsupported by perl5db (it requires a separate TTY for child debuggers). In that mode, if perl5db reports that it cannot create a new TTY, the session is terminated to avoid corrupted debugger state.

On terminate/restart/error paths, the adapter also tears down detached Perl process trees to avoid leaving dangling interpreter sessions behind.

launch.json examples

Recommended (default): socket transport

{
  "type": "perl",
  "request": "launch",
  "name": "Perl Debug",
  "program": "${workspaceFolder}/${relativeFile}",
  "stopOnEntry": true,
  "transport": "socket"
}

Legacy/fallback: stdio transport

{
  "type": "perl",
  "request": "launch",
  "name": "Perl Debug (stdio)",
  "program": "${workspaceFolder}/${relativeFile}",
  "stopOnEntry": true,
  "transport": "stdio"
}

Variable expansion and chunking

Variables are loaded lazily in the debug view. Nested array/hash levels are not fetched until you expand them.

Large collections are split into chunk nodes in the Variables view:

• Arrays use maxArrayElements as chunk size ([0..99], [100..199], ...)
• Hashes use maxHashElements as chunk size ([keys 0..99], [keys 100..199], ...)

Chunk nodes remain expandable for very large collections.

For hash chunks, numeric keys are ordered numerically (1, 2, 10) while non-numeric keys are ordered lexicographically.

Setting variable values is supported for nested/chunked entries as well; repeated edits in the same expanded chunk now reuse/reload the correct expression context.

This keeps initial variable rendering responsive while still allowing deep inspection on demand.

Example configuration:

{
  "type": "perl",
  "request": "launch",
  "name": "Perl Debug",
  "program": "${workspaceFolder}/${relativeFile}",
  "transport": "socket",
  "maxArrayElements": 100,
  "maxHashElements": 100
}

Other Editors and IDEs

• NVIM

As this extension implements the Debug Adapter Protocol it should be usable with other editors and IDEs aswell. Feel free to try it out and report any bugs that may occur.

Manual Install

Build dependencies:

• npm

Runtime dependencies:

• Node.js
• Perl, with the following modules:
  • PadWalker
• a POSIX-compliant shell (sh), cat, chmod, find, rm,

Build

To build (on Linux), clone this repository and run the following in the root of the repository:

npm install
npm run compile

The adapter can then be invoked with

node -- out/debugAdapter.js

Install

To manually install this package, run the build steps above, then

prefix="/usr/local" # or wherever you want

npm install -g --install-links \
  --prefix "$prefix"
# Make sure that users can traverse to read the js being run
find "$prefix/lib/node_modules/perl-debug-adapter" \
  -type d -execdir chmod 755 '{}' +

# Replace the (broken) executable generated by npm with a wrapper script
rm "$prefix/bin/perl-debug-adapter"
cat <<EOF >"$prefix/bin/perl-debug-adapter"
#!/bin/sh
exec node -- "$prefix/lib/node_modules/perl-debug-adapter/out/debugAdapter.js" "$@"
EOF
chmod 755 "$prefix/bin/perl-debug-adapter"

then the adapter can be invoked with just

perl-debug-adapter

if $prefix/bin is in your PATH.