Skip to content
Perl debugger extension for visual studio code
TypeScript Other
Branch: master
Clone or download
raix Merge pull request #120 from raix/greenkeeper/monorepo.commitlint-201…
…90916200742

Update commitlint to the latest version 🚀
Latest commit 95c8955 Sep 18, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode * compile before starting debug Feb 18, 2019
images add icon Nov 20, 2016
src fix(ci): increase timeout for test debugClient Sep 16, 2019
.gitignore
.nvmrc chore(ci): travis read node version from .nvmrc Sep 14, 2019
.travis.yml fix(ci): increase timeout in adapter tests Sep 16, 2019
.vscodeignore chore(upgrades): upgraded dev deps Feb 9, 2018
CHANGELOG.md Add changelog Mar 4, 2017
DEBUGGING.md feat(fork): support for multi-session/multi-process/fork debugging Mar 10, 2019
LICENSE.md merge Nov 27, 2016
ThirdPartyNotices.txt
appveyor.yml fix(ci): remove berry perl 5.16.x from test matrix Sep 14, 2019
package.json chore(package): update @commitlint/config-conventional to version 8.2.0 Sep 16, 2019
readme.md Update readme.md Aug 27, 2019
tsconfig.json chore(dependencies): update all dependencies Sep 14, 2019
yarn.lock fix(package): update semantic release and vsce Sep 16, 2019

readme.md

VS Code Perl Debug

Build Status Build status Greenkeeper semantic-release Visual Studio Marketplace Installs - Azure DevOps Extension

A debugger for Perl in Visual Studio Code.

Perl Debug

Features

  • Breakpoints (continue, step over, step in, step out)
  • Function breakpoints (for now functions have to be loaded at launch)
  • Process control (pause, resume, restart)
  • Stacktrace
  • Variable inspection (support for objects, arrays, strings, numbers and boolean)
  • Variable watching (for now we don't create actual watch breakpoints - figuring out how to maintain it)
  • Setting new values of variables (works inside of arrays and objects too)
  • Debug console for writing expressions (write Perl expressions in the debug console)
  • Variable values on hover in code
  • Loaded modules view (including source code retrieval from remote)
  • Multi-session/multi-target debugging (including support for fork where available)

Settings

  • exec Can be set to a specific perl binary defaults to "perl"
  • execArgs Arguments that is passed to the binary Perl executable
  • inc Can be an array of strings / include paths
  • args Can be an array of strings / program arguments
  • env Used for setting environment variables when debugging, PATH and PERL5LIB default to system unless overwritten
  • trace Boolean value to enable Debug Adapter Logging in perl-debug.log file
  • port Number for port to listen for remote debuggers to connect to. (Used only for remote debugging)
  • console String to identify where to launch the debuggee
  • debugRaw Boolean to enable logging of raw I/O with the Perl debugger in an output channel
  • debugLog Boolean to enable logging of other debug messages in an output channel
  • sessions String to configure how child processes are handled

Setup notes

You might have to install the PadWalker Perl package for variable inspection on Windows (and some linux distributions?)

A standard launch.json will resemble the following (on Windows; *nix distros will differ slightly.)

    {
        "version": "0.2.0",
        "configurations": [
            {
                "type": "perl",
                "request": "launch",
                "console": "integratedTerminal",
                "exec": "C:/Perl64/bin/perl.exe",
                "execArgs": [],
                "name": "Perl Debug",
                "root": "${workspaceRoot}",
                "program": "${workspaceRoot}/${relativeFile}",
                "inc": [],
                "args": [],
                "stopOnEntry": true
            }
        ]
    }

Remote debugger

When setting the console attribute in launch.json to remote the Visual Studio Code debug extension will start a debug server for the remote Perl debug instance to connect to.

E.g.:

 # Start remote debugger in vs code on port 5000 then:
 $ PERLDB_OPTS="RemotePort=localhost:5000" perl -d test.pl

localhost should be replaced by the ip address

Handling multiple processes

Visual Studio Code supports running multiple debugging sessions in parallel. If you have multiple configurations in your launch.json, you can start several of them simultaneously.

The extension can also automatically start additional debug sessions when a Perl process forks or if multiple debuggers try to connect to the same port. This behaviour needs to be enabled with the sessions option. To illustrate, with launch.json like

...
  "sessions": "watch",
  "console": "remote",
  "port": 5000,
...

Then you can start a debug session in Visual Studio Code and launch:

PERL5OPT=-d PERLDB_OPTS='RemotePort=localhost:5000' prove -l

All the Perl processes launched in one way or another by prove will then connect to the extension. In watch mode execution of dependent processes will continue immediately, in break mode they will stop on entry (like with stopOnEntry for the first or main process).

When using this feature, it is recommended to use the debugger module Devel::vscode. It overrides the fork function so that the Perl debugger connects to the extension right after fork returns in the child. When the module is not loaded, the extension creates a global watch expression w $$ to the same effect, but that puts the debugger in trace mode, wich can slow down debugging considerably.

When you start the Perl process you want to debug, instead of -d, specify -d:vscode. If the extension starts the Perl process, set execArgs: ["-d:vscode"] in launch.json.

Stability

Tests matrix running between OS and Perl versions:

  • OS X - Perl 5.22
  • OS X - Perl 5.20
  • OS X - Perl 5.18
  • OS X - Perl 5.16
  • OS X - Perl 5.14
  • Linux - Perl 5.22
  • Linux - Perl 5.20
  • Linux - Perl 5.18
  • Linux - Perl 5.16
  • Linux - Perl 5.14
  • Windows 64bit - Strawberry Perl 5.24.1
  • Windows 64bit - Strawberry Perl 5.22.3
  • Windows 64bit - Strawberry Perl 5.20.3
  • Windows 64bit - Strawberry Perl 5.18.4
  • Windows 64bit - Strawberry Perl 5.16.3
  • Windows 64bit - Activeperl 5.22.3.2204
  • Windows 64bit - Activeperl 5.24.1.2402

Known issues on Windows:

  • "Restart" - inhibit_exit is not respected and will cause the debugger to stop
  • Variable inspection unstable - it's due to output inconsistency from the Perl debugger

If you want to help test / debug read DEBUGGING.md

Todo

  • Watching variables doesn't create actual expression watchers yet - need more APIs for actually maintaining the list of expressions to watch. I might be able to do a workaround for now.
  • Variable values on hover doesn't work all the time due to the lack of information, e.g. $obj->{ownObj}->{ownFoo} hovering over $obj will work fine - but the children are not parsed correctly - to solve this we might need to parse the line of code.

Problems with perl5db.pl affecting this extension

Credits

Credits goes to Microsoft for making an awesome editor and a nice getting started mock debugger: https://github.com/Microsoft/vscode-mock-debug.git

Reporting issues and feature requests

I don't care about stars, but for everybodys sake: Please use GitHub for tracking issues and feature requests, thanks!

When you report an issue, it can be very helpful to enable debugRaw in your launch configuration. When enabled, you should have an output channel named Perl Debug RAW with contents like:

["2019-03-02T21:49:50.230Z","perl-debug.streamcatcher.write","127.0.0.1:40133 serving 127.0.0.1:43320","p $]\n"]
["2019-03-02T21:49:50.231Z","perl-debug.streamcatcher.data","127.0.0.1:40133 serving 127.0.0.1:43320","5.028001"]
...

These are the raw commands sent to the perl5db.pl debugger and the responses received. Including these in your report can make it easier to track down version differences and portability problems.

I do take pull requests for both documentation and code improvements!

Please be aware that this plugin depends on the OS/Visual Studio Code/Perl distribution/perl5db.pl, and none of these are perfect/consistent dependencies, therefore hard to track down. Why I've added a fairly broad test matrix across OS/Perl distributions

Please keep in mind that I'm an ES developer. I don't know all the corners of Perl - so any help is appreciated.

This project is using semantic release and commitlint for Visual Studio Code extensions. Commit messages should be formatted accordingly and should trigger correct versioning and automatic release / publish in the extension gallary.

Kind regards

Morten

You can’t perform that action at this time.