perldebguts documentation should be fixed

[p5pRT]

Migrated from rt.perl.org#131672 (status was 'resolved')

Searchable as RT131672$

[p5pRT]

From @KES777

Created by @KES777

[The documentation](https://perldoc.perl.org/perldebguts.html)
should be fixed​:

--- (This doesn't happen if the subroutine was compiled in the DB package.)
+++ (This doesn't happen if the subroutine was called from DB package.)

In short​:
Despite on 'from_db' sub is compiled at main​:: package we do NOT see calls to 'DB​::sub' for it
Becase CALL to this sub is made from DB​:: package

And vice versa​:
Despite on 'DB​::test' is compiled at DB​:: package we see calls to 'DB​::sub' for it
Becase CALL to this sub is made not from DB​:: package

The output​:
$ perl -Ilib -d​:DB test.pl
Called​: main​::BEGIN
Called​: DB​::test

$cat test.pl
sub from_db {};
use Test;
DB​::test();

$cat lib/Test.pm
package Test;
1;

$cat lib/Devel/DB.pm
package DB;

use B qw/ svref_2object /;
sub sub_name {
  my $r = shift;
  return $r unless ref $r;
  return $r unless my $cv = svref_2object( $r );
  return $r unless $cv->isa( 'B​::CV' )
  and my $gv = $cv->GV
  ;
  my $name = '';
  if ( my $st = $gv->STASH ) {
  $name = $st->NAME . '​::';
  }
  my $n = $gv->NAME;
  if ( $n ) {
  $name .= $n;
  if ( $n eq '__ANON__' ) {
  $name .= ' defined at ' . $gv->FILE . '​:' . $gv->LINE;
  }
  }
  return $name;
}

sub test{};

sub postponed {
  # Call only after DB​:: is loaded
  main​::from_db() if shift ne '*main​::_<lib/Devel/DB.pm';
}

sub DB{
  main​::from_db();
}

sub sub {
  print "Called​: ", sub_name( $DB​::sub ), "\n";
  main​::from_db();

  &$DB​::sub;
}

1;

See attached archive with source codes.

Perl Info

Flags:
    category=docs
    severity=low

Site configuration information for perl 5.24.1:

Configured by kes at Sun Apr 30 22:40:30 EEST 2017.

Summary of my perl5 (revision 5 version 24 subversion 1) configuration:
   
  Platform:
    osname=linux, osvers=4.4.0-53-generic, archname=x86_64-linux
    uname='linux kes-x751sa 4.4.0-53-generic #74-ubuntu smp fri dec 2 15:59:10 utc 2016 x86_64 x86_64 x86_64 gnulinux '
    config_args='-de -Dprefix=/home/kes/perl5/perlbrew/perls/perl-5.24.1 -Aeval:scriptdir=/home/kes/perl5/perlbrew/perls/perl-5.24.1/bin'
    hint=recommended, useposix=true, d_sigaction=define
    useithreads=undef, usemultiplicity=undef
    use64bitint=define, use64bitall=define, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='cc', ccflags ='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
    optimize='-O2',
    cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include'
    ccversion='', gccversion='5.4.0 20160609', gccosandvers=''
    intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678, doublekind=3
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16, longdblkind=3
    ivtype='long', ivsize=8, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
    alignbytes=8, prototype=define
  Linker and Libraries:
    ld='cc', ldflags =' -fstack-protector-strong -L/usr/local/lib'
    libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/5/include-fixed /usr/include/x86_64-linux-gnu /usr/lib /lib/x86_64-linux-gnu /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib
    libs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc
    perllibs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc
    libc=libc-2.23.so, so=so, useshrplib=false, libperl=libperl.a
    gnulibc_version='2.23'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
    cccdlflags='-fPIC', lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector-strong'

Locally applied patches:
    Devel::PatchPerl 1.38


@INC for perl 5.24.1:
    /home/kes/perl5/perlbrew/perls/perl-5.24.1/lib/site_perl/5.24.1/x86_64-linux
    /home/kes/perl5/perlbrew/perls/perl-5.24.1/lib/site_perl/5.24.1
    /home/kes/perl5/perlbrew/perls/perl-5.24.1/lib/5.24.1/x86_64-linux
    /home/kes/perl5/perlbrew/perls/perl-5.24.1/lib/5.24.1


Environment for perl 5.24.1:
    HOME=/home/kes
    LANG=en_US.UTF-8
    LANGUAGE=en
    LC_ADDRESS=uk_UA.UTF-8
    LC_IDENTIFICATION=uk_UA.UTF-8
    LC_MEASUREMENT=uk_UA.UTF-8
    LC_MESSAGES=en_US.UTF-8
    LC_MONETARY=uk_UA.UTF-8
    LC_NAME=uk_UA.UTF-8
    LC_NUMERIC=uk_UA.UTF-8
    LC_PAPER=uk_UA.UTF-8
    LC_TELEPHONE=uk_UA.UTF-8
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=/home/kes/perl5/perlbrew/bin:/home/kes/perl5/perlbrew/perls/perl-5.24.1/bin:/home/kes/bin:/home/kes/bin:/home/kes/bin:/home/kes/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games
    PERLBREW=command perlbrew
    PERLBREW_BASHRC_VERSION=0.78
    PERLBREW_HOME=/home/kes/.perlbrew
    PERLBREW_MANPATH=/home/kes/perl5/perlbrew/perls/perl-5.24.1/man
    PERLBREW_PATH=/home/kes/perl5/perlbrew/bin:/home/kes/perl5/perlbrew/perls/perl-5.24.1/bin
    PERLBREW_PERL=perl-5.24.1
    PERLBREW_ROOT=/home/kes/perl5/perlbrew
    PERLBREW_VERSION=0.78
    PERL_BADLANG (unset)
    SHELL=/bin/bash

[p5pRT]

From @KES777

bugreport.tar

[p5pRT]

From zefram@fysh.org

KES wrote​:

--- (This doesn't happen if the subroutine was compiled in the DB package.)
+++ (This doesn't happen if the subroutine was called from DB package.)

The phrase "the subroutine" is ambiguous, because in that paragraph
there are two subroutines in play. The original could be clarified
by expanding to "the calling subroutine". Your proposed change would
retain the ambiguity.

-zefram

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From @KES777

KES wrote​:

--- (This doesn't happen if the subroutine was compiled in the DB package.)
+++ (This doesn't happen if the subroutine was called from DB package.)

Actually first is right. Because with current behavior​:
  when a call to &DB​::sub is not happen if the subroutine was called from DB package

I can not setup breakpoint by subroutine name.

I check $DB​::sub and setup breakpoint at 'DB​::sub'. Code looks like next​:

  if( $breakpoints{ $DB​::sub } ) { $DB​::single = 1 };

This works well in most cases except for next one.

I implement debugger command in not DB package.
I do this because want to be able to debug debugger command.

So when that subroutine (which implements debugger command) is called from DB package, it can not be tracked.
  A call to &DB​::sub is not happen

As work around I put next code into that sub​:

  $^D |= (1<<30); $DB​::single = 1;

But this will not be required if perl works as documented​:
  A call to &DB​::sub is happened for all subroutines which was not compiled in the DB package.
  despite on place of call.

I check this behavior on the oldest version I have​: perl-5.6.2
it works contrary to the documentation too =(

[p5pRT]

From zefram@fysh.org

Documentation fixed in commit 7270698.

-zefram

[p5pRT]

@cpansprout - Status changed from 'open' to 'pending release'

[p5pRT]

From @KES777

On Tue, 05 Dec 2017 10​:11​:53 -0800, zefram@​fysh.org wrote​:

Documentation fixed in commit 7270698.

-zefram

Thank you for fix.

Zefram, will next sound more clear? Please review.
When execution of the program reaches a subroutine call, a call to &DB​::sub (args) is made instead, with $DB​::sub holding the name of the called subroutine. (This happen for all debuggable subroutines. Subroutines compiled in DB​:: package all are not debuggable.)

[p5pRT]

From zefram@fysh.org

KES via RT wrote​:

Zefram, will next sound more clear?

No, that's less clear.

If you want to raise another issue with the documentation, please do so
in a separate ticket.

-zefram

[p5pRT]

From @khwilliamson

Thank you for filing this report. You have helped make Perl better.

With the release yesterday of Perl 5.28.0, this and 185 other issues have been
resolved.

Perl 5.28.0 may be downloaded via​:
https://metacpan.org/release/XSAWYERX/perl-5.28.0

If you find that the problem persists, feel free to reopen this ticket.

[p5pRT]

@khwilliamson - Status changed from 'pending release' to 'resolved'