The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Devel-vscode-0.01
River stage zero No dependents
1 ++
/ Devel::vscode

NAME

Devel::vscode - Debug with perl-debug in Visual Studio Code

SYNOPSIS

  % perl -d:vscode example.pl

DESCRIPTION

This module primarily serves as a namespace registration for the Devel::vscode namespace for use in the perl-debug extension for Visual Studio Code. It is not needed to use the extension, and is only a very thin wrapper around the built-in debugger perl5db.pl.

FORK OVERRIDE

The only reason to use this as debugger is to enhance your debugging experience when your code uses fork (see "fork" in perlfunc). The extension talks to perl5db.pl over a socket and expects that the debugger will open a new connection to the extension for newly forked children.

However, perl5db.pl will only do so when it assumes control over the child process. That means the Visual Studio Code extension has no good way to show newly forked children in the user interface until the child has been stopped. As far as the author of this module is aware, the following options are available:

  • Do something akin to the debugger command w $$. That would create a global watch expression that would break into the debugger when the value of $$, the pid of the current process, changes. That would be right after fork returns in the child process.

    The debugger can do this only by enabling trace mode. That however comes with a runtime performance penalty and would also affect code that does not use fork. Furthermore, it would mix user defined watchpoints with a watchpoint set by the extension which may be confusing for users aswell as the extension itself (what should it do when the user clears all watch expressions, for instance).

  • Override CORE::GLOBAL::fork at compile time. That is the approach implemented by this module. Devel::vscode::_fork is a wrapper for CORE::fork that, depending on $Devel::vscode::BREAK_AFTER_FORK, breaks into the debugger right after fork returns successfully in child processes. That gives the Visual Studio Code extension a chance to control this behaviour at runtime, does not affect code that does not use fork, can be recognised by the extension by looking at the callstack.

    This behaviour is the default and can be configured explicitly using:

      % perl -d:vscode=fork=break

    To disable this behaviour:

      % perl -d:vscode=fork=

    Note that when the debuggee, or modules it uses, call CORE::fork directly, they would bypass this wrapper. In that case, w $$ is the only alternative.

BUG REPORTS

SEE ALSO

* https://marketplace.visualstudio.com/items?itemName=mortenhenriksen.perl-debug

* https://github.com/raix/vscode-perl-debug/

* perldebug

AUTHOR / COPYRIGHT / LICENSE

  Copyright (c) 2019 Bjoern Hoehrmann <bjoern@hoehrmann.de>.
  This module is licensed under the same terms as Perl itself.