Initial Commit

database/perl/vendor/lib/Devel/vscode.pm

@@ -0,0 +1,164 @@
+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