446 lines
15 KiB
HTML
446 lines
15 KiB
HTML
|
||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<HTML><HEAD><TITLE>Man page of PERLBUG</TITLE>
|
||
</HEAD><BODY>
|
||
<H1>PERLBUG</H1>
|
||
Section: Perl Programmers Reference Guide (1)<BR>Updated: 2020-10-19<BR><A HREF="#index">Index</A>
|
||
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<A NAME="lbAB"> </A>
|
||
<H2>NAME</H2>
|
||
|
||
perlbug - how to submit bug reports on Perl
|
||
<A NAME="lbAC"> </A>
|
||
<H2>SYNOPSIS</H2>
|
||
|
||
|
||
|
||
<B>perlbug</B>
|
||
<P>
|
||
|
||
<B>perlbug</B> [ <B>-v</B> ] [ <B>-a</B> <I>address</I> ] [ <B>-s</B> <I>subject</I> ]
|
||
[ <B>-b</B> <I>body</I> | <B>-f</B> <I>inputfile</I> ] [ <B>-F</B> <I>outputfile</I> ]
|
||
[ <B>-r</B> <I>returnaddress</I> ]
|
||
[ <B>-e</B> <I>editor</I> ] [ <B>-c</B> <I>adminaddress</I> | <B>-C</B> ]
|
||
[ <B>-S</B> ] [ <B>-t</B> ] [ <B>-d</B> ] [ <B>-A</B> ] [ <B>-h</B> ] [ <B>-T</B> ]
|
||
<P>
|
||
|
||
<B>perlbug</B> [ <B>-v</B> ] [ <B>-r</B> <I>returnaddress</I> ]
|
||
<BR> [ <B>-A</B> ] [ <B>-ok</B> | <B>-okay</B> | <B>-nok</B> | <B>-nokay</B> ]
|
||
<P>
|
||
|
||
<B>perlthanks</B>
|
||
<A NAME="lbAD"> </A>
|
||
<H2>DESCRIPTION</H2>
|
||
|
||
|
||
|
||
This program is designed to help you generate and send bug reports
|
||
(and thank-you notes) about perl5 and the modules which ship with it.
|
||
<P>
|
||
|
||
In most cases, you can just run it interactively from a command
|
||
line without any special arguments and follow the prompts.
|
||
<P>
|
||
|
||
If you have found a bug with a non-standard port (one that was not
|
||
part of the <I>standard distribution</I>), a binary distribution, or a
|
||
non-core module (such as Tk, <FONT SIZE="-1">DBI,</FONT> etc), then please see the
|
||
documentation that came with that distribution to determine the
|
||
correct place to report bugs.
|
||
<P>
|
||
|
||
If you are unable to send your report using <B>perlbug</B> (most likely
|
||
because your system doesn't have a way to send mail that perlbug
|
||
recognizes), you may be able to use this tool to compose your report
|
||
and save it to a file which you can then send to <B><A HREF="mailto:perlbug@perl.org">perlbug@perl.org</A></B>
|
||
using your regular mail client.
|
||
<P>
|
||
|
||
In extreme cases, <B>perlbug</B> may not work well enough on your system
|
||
to guide you through composing a bug report. In those cases, you
|
||
may be able to use <B>perlbug -d</B> to get system configuration
|
||
information to include in a manually composed bug report to
|
||
<B><A HREF="mailto:perlbug@perl.org">perlbug@perl.org</A></B>.
|
||
<P>
|
||
|
||
When reporting a bug, please run through this checklist:
|
||
<DL COMPACT>
|
||
<DT id="1">What version of Perl you are running?<DD>
|
||
|
||
|
||
Type <TT>"perl -v"</TT> at the command line to find out.
|
||
<DT id="2">Are you running the latest released version of perl?<DD>
|
||
|
||
|
||
Look at <A HREF="http://www.perl.org/">http://www.perl.org/</A> to find out. If you are not using the
|
||
latest released version, please try to replicate your bug on the
|
||
latest stable release.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Note that reports about bugs in old versions of Perl, especially
|
||
those which indicate you haven't also tested the current stable
|
||
release of Perl, are likely to receive less attention from the
|
||
volunteers who build and maintain Perl than reports about bugs in
|
||
the current release.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
This tool isn't appropriate for reporting bugs in any version
|
||
prior to Perl 5.0.
|
||
<DT id="3">Are you sure what you have is a bug?<DD>
|
||
|
||
|
||
A significant number of the bug reports we get turn out to be
|
||
documented features in Perl. Make sure the issue you've run into
|
||
isn't intentional by glancing through the documentation that comes
|
||
with the Perl distribution.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Given the sheer volume of Perl documentation, this isn't a trivial
|
||
undertaking, but if you can point to documentation that suggests
|
||
the behaviour you're seeing is <I>wrong</I>, your issue is likely to
|
||
receive more attention. You may want to start with <B>perldoc</B>
|
||
perltrap for pointers to common traps that new (and experienced)
|
||
Perl programmers run into.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
If you're unsure of the meaning of an error message you've run
|
||
across, <B>perldoc</B> perldiag for an explanation. If the message
|
||
isn't in perldiag, it probably isn't generated by Perl. You may
|
||
have luck consulting your operating system documentation instead.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
If you are on a non-UNIX platform <B>perldoc</B> perlport, as some
|
||
features may be unimplemented or work differently.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
You may be able to figure out what's going wrong using the Perl
|
||
debugger. For information about how to use the debugger <B>perldoc</B>
|
||
perldebug.
|
||
<DT id="4">Do you have a proper test case?<DD>
|
||
|
||
|
||
The easier it is to reproduce your bug, the more likely it will be
|
||
fixed --- if nobody can duplicate your problem, it probably won't be
|
||
addressed.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
A good test case has most of these attributes: short, simple code;
|
||
few dependencies on external commands, modules, or libraries; no
|
||
platform-dependent code (unless it's a platform-specific bug);
|
||
clear, simple documentation.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
A good test case is almost always a good candidate to be included in
|
||
Perl's test suite. If you have the time, consider writing your test case so
|
||
that it can be easily included into the standard test suite.
|
||
<DT id="5">Have you included all relevant information?<DD>
|
||
|
||
|
||
Be sure to include the <B>exact</B> error messages, if any.
|
||
``Perl gave an error'' is not an exact error message.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
If you get a core dump (or equivalent), you may use a debugger
|
||
(<B>dbx</B>, <B>gdb</B>, etc) to produce a stack trace to include in the bug
|
||
report.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
<FONT SIZE="-1">NOTE:</FONT> unless your Perl has been compiled with debug info
|
||
(often <B>-g</B>), the stack trace is likely to be somewhat hard to use
|
||
because it will most probably contain only the function names and not
|
||
their arguments. If possible, recompile your Perl with debug info and
|
||
reproduce the crash and the stack trace.
|
||
<DT id="6">Can you describe the bug in plain English?<DD>
|
||
|
||
|
||
The easier it is to understand a reproducible bug, the more likely
|
||
it will be fixed. Any insight you can provide into the problem
|
||
will help a great deal. In other words, try to analyze the problem
|
||
(to the extent you can) and report your discoveries.
|
||
<DT id="7">Can you fix the bug yourself?<DD>
|
||
|
||
|
||
If so, that's great news; bug reports with patches are likely to
|
||
receive significantly more attention and interest than those without
|
||
patches. Please attach your patch to the report using the <TT>"-p"</TT> option.
|
||
When sending a patch, create it using <TT>"git format-patch"</TT> if possible,
|
||
though a unified diff created with <TT>"diff -pu"</TT> will do nearly as well.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Your patch may be returned with requests for changes, or requests for more
|
||
detailed explanations about your fix.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Here are a few hints for creating high-quality patches:
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Make sure the patch is not reversed (the first argument to diff is
|
||
typically the original file, the second argument your changed file).
|
||
Make sure you test your patch by applying it with <TT>"git am"</TT> or the
|
||
<TT>"patch"</TT> program before you send it on its way. Try to follow the
|
||
same style as the code you are trying to patch. Make sure your patch
|
||
really does work (<TT>"make test"</TT>, if the thing you're patching is covered
|
||
by Perl's test suite).
|
||
<DT id="8">Can you use "perlbug" to submit the report?<DD>
|
||
|
||
|
||
|
||
|
||
<B>perlbug</B> will, amongst other things, ensure your report includes
|
||
crucial information about your version of perl. If <TT>"perlbug"</TT> is
|
||
unable to mail your report after you have typed it in, you may have
|
||
to compose the message yourself, add the output produced by <TT>"perlbug
|
||
-d"</TT> and email it to <B><A HREF="mailto:perlbug@perl.org">perlbug@perl.org</A></B>. If, for some reason, you
|
||
cannot run <TT>"perlbug"</TT> at all on your system, be sure to include the
|
||
entire output produced by running <TT>"perl -V"</TT> (note the uppercase V).
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Whether you use <TT>"perlbug"</TT> or send the email manually, please make
|
||
your Subject line informative. ``a bug'' is not informative. Neither
|
||
is ``perl crashes'' nor is ``<FONT SIZE="-1">HELP</FONT>!!!''. These don't help. A compact
|
||
description of what's wrong is fine.
|
||
<DT id="9">Can you use "perlbug" to submit a thank-you note?<DD>
|
||
|
||
|
||
|
||
|
||
Yes, you can do this by either using the <TT>"-T"</TT> option, or by invoking
|
||
the program as <TT>"perlthanks"</TT>. Thank-you notes are good. It makes people
|
||
smile.
|
||
</DL>
|
||
<P>
|
||
|
||
Having done your bit, please be prepared to wait, to be told the
|
||
bug is in your code, or possibly to get no reply at all. The
|
||
volunteers who maintain Perl are busy folks, so if your problem is
|
||
an obvious bug in your own code, is difficult to understand or is
|
||
a duplicate of an existing report, you may not receive a personal
|
||
reply.
|
||
<P>
|
||
|
||
If it is important to you that your bug be fixed, do monitor the
|
||
<A HREF="mailto:perl5-porters@perl.org">perl5-porters@perl.org</A> mailing list (mailing lists are moderated, your
|
||
message may take a while to show up) and the commit logs to development
|
||
versions of Perl, and encourage the maintainers with kind words or
|
||
offers of frosty beverages. (Please do be kind to the maintainers.
|
||
Harassing or flaming them is likely to have the opposite effect of the
|
||
one you want.)
|
||
<P>
|
||
|
||
Feel free to update the ticket about your bug on <A HREF="http://rt.perl.org">http://rt.perl.org</A>
|
||
if a new version of Perl is released and your bug is still present.
|
||
<A NAME="lbAE"> </A>
|
||
<H2>OPTIONS</H2>
|
||
|
||
|
||
|
||
<DL COMPACT>
|
||
<DT id="10"><B>-a</B><DD>
|
||
|
||
|
||
Address to send the report to. Defaults to <B><A HREF="mailto:perlbug@perl.org">perlbug@perl.org</A></B>.
|
||
<DT id="11"><B>-A</B><DD>
|
||
|
||
|
||
Don't send a bug received acknowledgement to the reply address.
|
||
Generally it is only a sensible to use this option if you are a
|
||
perl maintainer actively watching perl porters for your message to
|
||
arrive.
|
||
<DT id="12"><B>-b</B><DD>
|
||
|
||
|
||
Body of the report. If not included on the command line, or
|
||
in a file with <B>-f</B>, you will get a chance to edit the message.
|
||
<DT id="13"><B>-C</B><DD>
|
||
|
||
|
||
Don't send copy to administrator.
|
||
<DT id="14"><B>-c</B><DD>
|
||
|
||
|
||
Address to send copy of report to. Defaults to the address of the
|
||
local perl administrator (recorded when perl was built).
|
||
<DT id="15"><B>-d</B><DD>
|
||
|
||
|
||
Data mode (the default if you redirect or pipe output). This prints out
|
||
your configuration data, without mailing anything. You can use this
|
||
with <B>-v</B> to get more complete data.
|
||
<DT id="16"><B>-e</B><DD>
|
||
|
||
|
||
Editor to use.
|
||
<DT id="17"><B>-f</B><DD>
|
||
|
||
|
||
File containing the body of the report. Use this to quickly send a
|
||
prepared message.
|
||
<DT id="18"><B>-F</B><DD>
|
||
|
||
|
||
File to output the results to instead of sending as an email. Useful
|
||
particularly when running perlbug on a machine with no direct internet
|
||
connection.
|
||
<DT id="19"><B>-h</B><DD>
|
||
|
||
|
||
Prints a brief summary of the options.
|
||
<DT id="20"><B>-ok</B><DD>
|
||
|
||
|
||
Report successful build on this system to perl porters. Forces <B>-S</B>
|
||
and <B>-C</B>. Forces and supplies values for <B>-s</B> and <B>-b</B>. Only
|
||
prompts for a return address if it cannot guess it (for use with
|
||
<B>make</B>). Honors return address specified with <B>-r</B>. You can use this
|
||
with <B>-v</B> to get more complete data. Only makes a report if this
|
||
system is less than 60 days old.
|
||
<DT id="21"><B>-okay</B><DD>
|
||
|
||
|
||
As <B>-ok</B> except it will report on older systems.
|
||
<DT id="22"><B>-nok</B><DD>
|
||
|
||
|
||
Report unsuccessful build on this system. Forces <B>-C</B>. Forces and
|
||
supplies a value for <B>-s</B>, then requires you to edit the report
|
||
and say what went wrong. Alternatively, a prepared report may be
|
||
supplied using <B>-f</B>. Only prompts for a return address if it
|
||
cannot guess it (for use with <B>make</B>). Honors return address
|
||
specified with <B>-r</B>. You can use this with <B>-v</B> to get more
|
||
complete data. Only makes a report if this system is less than 60
|
||
days old.
|
||
<DT id="23"><B>-nokay</B><DD>
|
||
|
||
|
||
As <B>-nok</B> except it will report on older systems.
|
||
<DT id="24"><B>-p</B><DD>
|
||
|
||
|
||
The names of one or more patch files or other text attachments to be
|
||
included with the report. Multiple files must be separated with commas.
|
||
<DT id="25"><B>-r</B><DD>
|
||
|
||
|
||
Your return address. The program will ask you to confirm its default
|
||
if you don't use this option.
|
||
<DT id="26"><B>-S</B><DD>
|
||
|
||
|
||
Send without asking for confirmation.
|
||
<DT id="27"><B>-s</B><DD>
|
||
|
||
|
||
Subject to include with the message. You will be prompted if you don't
|
||
supply one on the command line.
|
||
<DT id="28"><B>-t</B><DD>
|
||
|
||
|
||
Test mode. The target address defaults to <B><A HREF="mailto:perlbug-test@perl.org">perlbug-test@perl.org</A></B>.
|
||
Also makes it possible to command perlbug from a pipe or file, for
|
||
testing purposes.
|
||
<DT id="29"><B>-T</B><DD>
|
||
|
||
|
||
Send a thank-you note instead of a bug report.
|
||
<DT id="30"><B>-v</B><DD>
|
||
|
||
|
||
Include verbose configuration data in the report.
|
||
</DL>
|
||
<A NAME="lbAF"> </A>
|
||
<H2>AUTHORS</H2>
|
||
|
||
|
||
|
||
Kenneth Albanowski (<<A HREF="mailto:kjahds@kjahds.com">kjahds@kjahds.com</A>>), subsequently
|
||
<I>doc</I>tored by Gurusamy Sarathy (<<A HREF="mailto:gsar@activestate.com">gsar@activestate.com</A>>),
|
||
Tom Christiansen (<<A HREF="mailto:tchrist@perl.com">tchrist@perl.com</A>>), Nathan Torkington
|
||
(<<A HREF="mailto:gnat@frii.com">gnat@frii.com</A>>), Charles F. Randall (<<A HREF="mailto:cfr@pobox.com">cfr@pobox.com</A>>),
|
||
Mike Guy (<<A HREF="mailto:mjtg@cam.ac.uk">mjtg@cam.ac.uk</A>>), Dominic Dunlop
|
||
(<<A HREF="mailto:domo@computer.org">domo@computer.org</A>>), Hugo van der Sanden (<<A HREF="mailto:hv@crypt.org">hv@crypt.org</A>>),
|
||
Jarkko Hietaniemi (<<A HREF="mailto:jhi@iki.fi">jhi@iki.fi</A>>), Chris Nandor
|
||
(<<A HREF="mailto:pudge@pobox.com">pudge@pobox.com</A>>), Jon Orwant (<<A HREF="mailto:orwant@media.mit.edu">orwant@media.mit.edu</A>>,
|
||
Richard Foley (<<A HREF="mailto:richard.foley@rfi.net">richard.foley@rfi.net</A>>), Jesse Vincent
|
||
(<<A HREF="mailto:jesse@bestpractical.com">jesse@bestpractical.com</A>>), and Craig A. Berry (<<A HREF="mailto:craigberry@mac.com">craigberry@mac.com</A>>).
|
||
<A NAME="lbAG"> </A>
|
||
<H2>SEE ALSO</H2>
|
||
|
||
|
||
|
||
<B><A HREF="/cgi-bin/man/man2html?1+perl">perl</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+perldebug">perldebug</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+perldiag">perldiag</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+perlport">perlport</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+perltrap">perltrap</A></B>(1),
|
||
<B><A HREF="/cgi-bin/man/man2html?1+diff">diff</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+patch">patch</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+dbx">dbx</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+gdb">gdb</A></B>(1)
|
||
<A NAME="lbAH"> </A>
|
||
<H2>BUGS</H2>
|
||
|
||
|
||
|
||
None known (guess what must have been used to report them?)
|
||
<P>
|
||
|
||
<HR>
|
||
<A NAME="index"> </A><H2>Index</H2>
|
||
<DL>
|
||
<DT id="31"><A HREF="#lbAB">NAME</A><DD>
|
||
<DT id="32"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
||
<DT id="33"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
||
<DT id="34"><A HREF="#lbAE">OPTIONS</A><DD>
|
||
<DT id="35"><A HREF="#lbAF">AUTHORS</A><DD>
|
||
<DT id="36"><A HREF="#lbAG">SEE ALSO</A><DD>
|
||
<DT id="37"><A HREF="#lbAH">BUGS</A><DD>
|
||
</DL>
|
||
<HR>
|
||
This document was created by
|
||
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
||
using the manual pages.<BR>
|
||
Time: 00:05:22 GMT, March 31, 2021
|
||
</BODY>
|
||
</HTML>
|