165 lines
3.7 KiB
Perl
165 lines
3.7 KiB
Perl
package Devel::vscode;
|
|
use 5.008;
|
|
use strict;
|
|
use warnings;
|
|
no strict;
|
|
no warnings;
|
|
|
|
our $VERSION = '0.02';
|
|
|
|
our $BREAK_AFTER_FORK = 1;
|
|
|
|
sub import {
|
|
my ($class, @args) = @_;
|
|
|
|
for (@args) {
|
|
|
|
if (/^fork=break$/) {
|
|
|
|
$BREAK_AFTER_FORK = 1;
|
|
|
|
} elsif (/^fork=$/) {
|
|
|
|
$BREAK_AFTER_FORK = 0;
|
|
|
|
} else {
|
|
|
|
die "Unknown option $_";
|
|
|
|
}
|
|
|
|
}
|
|
|
|
return;
|
|
}
|
|
|
|
sub _fork {
|
|
|
|
if ($BREAK_AFTER_FORK) {
|
|
|
|
my $pid = &CORE::fork;
|
|
|
|
return $pid if not defined $pid;
|
|
return $pid if $pid;
|
|
|
|
$DB::single = 2;
|
|
|
|
return $pid;
|
|
|
|
} else {
|
|
|
|
&CORE::fork;
|
|
|
|
}
|
|
|
|
};
|
|
|
|
BEGIN {
|
|
require "perl5db.pl";
|
|
}
|
|
|
|
BEGIN {
|
|
*CORE::GLOBAL::fork = \&_fork;
|
|
}
|
|
|
|
1;
|
|
|
|
__END__
|
|
|
|
=head1 NAME
|
|
|
|
Devel::vscode - Debug with perl-debug in Visual Studio Code
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
% perl -d:vscode example.pl
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This module primarily serves as a namespace registration for the
|
|
C<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 C<perl5db.pl>.
|
|
|
|
=head2 FORK OVERRIDE
|
|
|
|
The only reason to use this as debugger is to enhance your debugging
|
|
experience when your code uses C<fork> (see L<perlfunc/fork>). The
|
|
extension talks to C<perl5db.pl> over a socket and expects that the
|
|
debugger will open a new connection to the extension for newly forked
|
|
children.
|
|
|
|
However, C<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:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
Do something akin to the debugger command C<w $$>. That would create
|
|
a global watch expression that would break into the debugger when the
|
|
value of C<$$>, the pid of the current process, changes. That would
|
|
be right after C<fork> returns in the child process.
|
|
|
|
The debugger can do this only by enabling C<trace> mode. That however
|
|
comes with a runtime performance penalty and would also affect code
|
|
that does not use C<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).
|
|
|
|
=item *
|
|
|
|
Override C<CORE::GLOBAL::fork> at compile time. That is the approach
|
|
implemented by this module. C<Devel::vscode::_fork> is a wrapper for
|
|
C<CORE::fork> that, depending on C<$Devel::vscode::BREAK_AFTER_FORK>,
|
|
breaks into the debugger right after C<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 C<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 C<CORE::fork>
|
|
directly, they would bypass this wrapper. In that case, C<w $$> is
|
|
the only alternative.
|
|
|
|
=back
|
|
|
|
=head1 BUG REPORTS
|
|
|
|
=over
|
|
|
|
=item * L<https://github.com/hoehrmann/Devel-vscode/issues>
|
|
|
|
=item * L<mailto:bug-Devel-vscode@rt.cpan.org>
|
|
|
|
=item * L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-vscode>
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
* L<https://marketplace.visualstudio.com/items?itemName=mortenhenriksen.perl-debug>
|
|
|
|
* L<https://github.com/raix/vscode-perl-debug/>
|
|
|
|
* L<perldebug>
|
|
|
|
=head1 AUTHOR / COPYRIGHT / LICENSE
|
|
|
|
Copyright (c) 2019 Bjoern Hoehrmann <bjoern@hoehrmann.de>.
|
|
This module is licensed under the same terms as Perl itself.
|
|
|
|
=cut
|