Out-of-date info on DEBUGGING in perlhacktips, perlrun

[p5pRT]

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

Searchable as RT128670$

[p5pRT]

From gdg@zplane.com

Created by gdg@zplane.com

Both perlhacktips.pod and perlrun.pod contain some out of date info on
enabling the compiler -DDEBUGGING option during configuration​: Both documents
indicate that running ./Configure with -Doptimize=-g will also enable the
compiler -DDEBUGGING option, but this has evidently not been the case for
many years.

Clarification regarding the relationship between the ./Configure
-DDEBUGGING option and the compiler -DDEBUGGING option would also be
helpful for the newbie perl hacker.

More in this thread​:

  http​://www.nntp.perl.org/group/perl.perl5.porters/2016/07/msg238127.html

Perl Info

Flags:
    category=docs
    severity=medium

Site configuration information for perl 5.24.0:

Configured by builduser at Tue May 10 17:41:50 CEST 2016.

Summary of my perl5 (revision 5 version 24 subversion 0) configuration:
   
  Platform:
    osname=linux, osvers=4.5.2-1-arch, archname=i686-linux-thread-multi
    uname='linux flo-32 4.5.2-1-arch #1 smp preempt thu apr 21 18:21:27 cest 2016 i686 gnulinux '
    config_args='-des -Dusethreads -Duseshrplib -Doptimize=-march=i686 -mtune=generic -O2 -pipe -fstack-protector-strong -Dprefix=/usr -Dvendorprefix=/usr -Dprivlib=/usr/share/perl5/core_perl -Darchlib=/usr/lib/perl5/core_perl -Dsitelib=/usr/share/perl5/site_perl -Dsitearch=/usr/lib/perl5/site_perl -Dvendorlib=/usr/share/perl5/vendor_perl -Dvendorarch=/usr/lib/perl5/vendor_perl -Dscriptdir=/usr/bin/core_perl -Dsitescript=/usr/bin/site_perl -Dvendorscript=/usr/bin/vendor_perl -Dinc_version_list=none -Dman1ext=1perl -Dman3ext=3perl -Dlddlflags=-shared -Wl,-O1,--sort-common,--as-needed,-z,relro -Dldflags=-Wl,-O1,--sort-common,--as-needed,-z,relro'
    hint=recommended, useposix=true, d_sigaction=define
    useithreads=define, usemultiplicity=define
    use64bitint=undef, use64bitall=undef, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='cc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
    optimize='-march=i686 -mtune=generic -O2 -pipe -fstack-protector-strong',
    cppflags='-D_REENTRANT -D_GNU_SOURCE -fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include'
    ccversion='', gccversion='6.1.1 20160501', gccosandvers=''
    intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234, doublekind=3
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12, longdblkind=3
    ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
    alignbytes=4, prototype=define
  Linker and Libraries:
    ld='cc', ldflags ='-Wl,-O1,--sort-common,--as-needed,-z,relro -fstack-protector-strong -L/usr/local/lib'
    libpth=/usr/local/lib /usr/lib/gcc/i686-pc-linux-gnu/6.1.1/include-fixed /usr/lib /lib
    libs=-lpthread -lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc -lgdbm_compat
    perllibs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc
    libc=libc-2.23.so, so=so, useshrplib=true, libperl=libperl.so
    gnulibc_version='2.23'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E -Wl,-rpath,/usr/lib/perl5/core_perl/CORE'
    cccdlflags='-fPIC', lddlflags='-shared -Wl,-O1,--sort-common,--as-needed,-z,relro -L/usr/local/lib -fstack-protector-strong'



@INC for perl 5.24.0:
    /home/gdg/locperl/lib/perl5/i686-linux-thread-multi
    /home/gdg/locperl/lib/perl5
    /home/gdg/lib/perllib
    /usr/lib/perl5/site_perl
    /usr/share/perl5/site_perl
    /usr/lib/perl5/vendor_perl
    /usr/share/perl5/vendor_perl
    /usr/lib/perl5/core_perl
    /usr/share/perl5/core_perl
    .


Environment for perl 5.24.0:
    HOME=/home/gdg
    LANG=en_US.UTF-8
    LANGUAGE (unset)
    LC_ALL=en_US
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=/home/gdg/bin:/usr/local/bin:/usr/bin:.:/usr/bin/core_perl:/usr/bin/vendor_perl:/opt/bin32-jre/jre/bin
    PERL5LIB=/home/gdg/locperl/lib/perl5:/home/gdg/lib/perllib
    PERL_BADLANG (unset)
    SHELL=/bin/bash

[p5pRT]

From @jkeenan

On Tue Jul 19 07​:09​:28 2016, gdg@​zplane.com wrote​:

This is a bug report for perl from gdg@​zplane.com,
generated with the help of perlbug 1.40 running under perl 5.24.0.

-----------------------------------------------------------------
[Please describe your issue here]

Both perlhacktips.pod and perlrun.pod contain some out of date info on
enabling the compiler -DDEBUGGING option during configuration​: Both
documents
indicate that running ./Configure with -Doptimize=-g will also enable
the
compiler -DDEBUGGING option, but this has evidently not been the case
for
many years.

Clarification regarding the relationship between the ./Configure
-DDEBUGGING option and the compiler -DDEBUGGING option would also be
helpful for the newbie perl hacker.

More in this thread​:

http​://www.nntp.perl.org/group/perl.perl5.porters/2016/07/msg238127.html

Are these the sections of the documentation which you find misleading?

#####
pod/perlhacktips.pod

=head2 Poking at Perl

To really poke around with Perl, you'll probably want to build Perl for
debugging, like this​:

  ./Configure -d -D optimize=-g
  make

C<-g> is a flag to the C compiler to have it produce debugging
information which will allow us to step through a running program, and
to see in which C function we are at (without the debugging information
we might see only the numerical addresses of the functions, which is
not very helpful).

F<Configure> will also turn on the C<DEBUGGING> compilation symbol
which enables all the internal debugging code in Perl. There are a
whole bunch of things you can debug with this​: L<perlrun> lists them
all, and the best way to find out about them is to play about with
them. The most useful options are probably
#####

#####
pod/perlrun.pod

All these flags require B<-DDEBUGGING> when you compile the Perl
executable (but see C<​:opd> in L<Devel​::Peek> or L<re/'debug' mode>
which may change this).
See the F<INSTALL> file in the Perl source distribution
for how to do this. This flag is automatically set if you include B<-g>
option when C<Configure> asks you about optimizer/debugger flags.
#####

Thank you very much.

--
James E Keenan (jkeenan@​cpan.org)

[p5pRT]

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

[p5pRT]

From gdg@zplane.com

James E Keenan via RT <perlbug-followup@​perl.org> [2016-07-27 16​:53​:30 -0700]​:

On Tue Jul 19 07​:09​:28 2016, gdg@​zplane.com wrote​:

This is a bug report for perl from gdg@​zplane.com,
generated with the help of perlbug 1.40 running under perl 5.24.0.

-----------------------------------------------------------------
[Please describe your issue here]

Both perlhacktips.pod and perlrun.pod contain some out of date info on
enabling the compiler -DDEBUGGING option during configuration​: Both
documents
indicate that running ./Configure with -Doptimize=-g will also enable
the
compiler -DDEBUGGING option, but this has evidently not been the case
for
many years.

Clarification regarding the relationship between the ./Configure
-DDEBUGGING option and the compiler -DDEBUGGING option would also be
helpful for the newbie perl hacker.

More in this thread​:

http​://www.nntp.perl.org/group/perl.perl5.porters/2016/07/msg238127.html

Are these the sections of the documentation which you find misleading?

#####
pod/perlhacktips.pod

=head2 Poking at Perl

To really poke around with Perl, you'll probably want to build Perl for
debugging, like this​:

\./Configure \-d \-D optimize=\-g
make

C<-g> is a flag to the C compiler to have it produce debugging
information which will allow us to step through a running program, and
to see in which C function we are at (without the debugging information
we might see only the numerical addresses of the functions, which is
not very helpful).

F<Configure> will also turn on the C<DEBUGGING> compilation symbol
which enables all the internal debugging code in Perl. There are a
whole bunch of things you can debug with this​: L<perlrun> lists them
all, and the best way to find out about them is to play about with
them. The most useful options are probably
#####

#####
pod/perlrun.pod

All these flags require B<-DDEBUGGING> when you compile the Perl
executable (but see C<​:opd> in L<Devel​::Peek> or L<re/'debug' mode>
which may change this).
See the F<INSTALL> file in the Perl source distribution
for how to do this. This flag is automatically set if you include B<-g>
option when C<Configure> asks you about optimizer/debugger flags.
#####

Yes, but mainly the text specifically referring to -g, implying that -g also
turns on the -DDEBUGGING compiler symbol.

Also, it's more than misleading, it's just wrong, at least with modern
perls. At least, that was my experience, and also what I came away with
from reading the responses in the thread where I asked about it. From
those responses, it sounded like Configure -g used to behave the way
that's described in the excerpted text above, but hasn't for quite some time.

[p5pRT]

From @iabyn

On Wed, Jul 27, 2016 at 06​:13​:01PM -0600, Glenn Golden wrote​:

Yes, but mainly the text specifically referring to -g, implying that -g also
turns on the -DDEBUGGING compiler symbol.

Also, it's more than misleading, it's just wrong, at least with modern
perls. At least, that was my experience, and also what I came away with
from reading the responses in the thread where I asked about it. From
those responses, it sounded like Configure -g used to behave the way
that's described in the excerpted text above, but hasn't for quite some time.

With commit v5.25.3-166-gf075db8, I've reworked the text in INSTALL,
perlhacktips and perlrun to hopefully make things clearer.

--
All wight. I will give you one more chance. This time, I want to hear
no Wubens. No Weginalds. No Wudolf the wed-nosed weindeers.
  -- Life of Brian

[p5pRT]

@iabyn - Status changed from 'open' to 'resolved'

[p5pRT]

From gdg@zplane.com

Dave Mitchell <davem@​iabyn.com> [2016-08-08 12​:44​:10 +0100]​:

On Wed, Jul 27, 2016 at 06​:13​:01PM -0600, Glenn Golden wrote​:

Yes, but mainly the text specifically referring to -g, implying that -g also
turns on the -DDEBUGGING compiler symbol.

Also, it's more than misleading, it's just wrong, at least with modern
perls. At least, that was my experience, and also what I came away with
from reading the responses in the thread where I asked about it. From
those responses, it sounded like Configure -g used to behave the way
that's described in the excerpted text above, but hasn't for quite some time.

With commit v5.25.3-166-gf075db8, I've reworked the text in INSTALL,
perlhacktips and perlrun to hopefully make things clearer.

Thanks Dave! Much improved.