Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1246 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man1/perlhack.1 b/upstream/debian-bookworm/man1/perlhack.1
new file mode 100644
index 00000000..3c1174f2
--- /dev/null
+++ b/upstream/debian-bookworm/man1/perlhack.1
@@ -0,0 +1,1246 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLHACK 1"
+.TH PERLHACK 1 "2023-11-25" "perl v5.36.0" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+perlhack \- How to hack on Perl
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This document explains how Perl development works.  It includes details
+about the Perl 5 Porters email list, the Perl repository, the Perl
+bug tracker, patch guidelines, and commentary on Perl development
+philosophy.
+.SH "SUPER QUICK PATCH GUIDE"
+.IX Header "SUPER QUICK PATCH GUIDE"
+If you just want to submit a single small patch like a pod fix, a test
+for a bug, comment fixes, etc., it's easy! Here's how:
+.IP "\(bu" 4
+Check out the source repository
+.Sp
+The perl source is in a git repository.  You can clone the repository
+with the following command:
+.Sp
+.Vb 1
+\&  % git clone https://github.com/Perl/perl5.git perl
+.Ve
+.IP "\(bu" 4
+Ensure you're following the latest advice
+.Sp
+In case the advice in this guide has been updated recently, read the
+latest version directly from the perl source:
+.Sp
+.Vb 1
+\&  % perldoc pod/perlhack.pod
+.Ve
+.IP "\(bu" 4
+Create a branch for your change
+.Sp
+Create a branch based on blead to commit your change to, which will
+later be used to send it to the Perl issue tracker.
+.Sp
+.Vb 1
+\&  % git checkout \-b mychange
+.Ve
+.IP "\(bu" 4
+Make your change
+.Sp
+Hack, hack, hack.  Keep in mind that Perl runs on many different
+platforms, with different operating systems that have different
+capabilities, different filesystem organizations, and even different
+character sets.  perlhacktips gives advice on this.
+.IP "\(bu" 4
+Test your change
+.Sp
+You can run all the tests with the following commands:
+.Sp
+.Vb 2
+\&  % ./Configure \-des \-Dusedevel
+\&  % make test
+.Ve
+.Sp
+Keep hacking until the tests pass.
+.IP "\(bu" 4
+Commit your change
+.Sp
+Committing your work will save the change \fIon your local system\fR:
+.Sp
+.Vb 1
+\&  % git commit \-a \-m \*(AqCommit message goes here\*(Aq
+.Ve
+.Sp
+Make sure the commit message describes your change in a single
+sentence.  For example, \*(L"Fixed spelling errors in perlhack.pod\*(R".
+.IP "\(bu" 4
+Send your change to the Perl issue tracker
+.Sp
+The next step is to submit your patch to the Perl core ticket system.
+.Sp
+Create a GitHub fork of the perl5 repository and add it as a remote,
+if you haven't already, as described in the GitHub documentation at
+<https://help.github.com/en/articles/working\-with\-forks>.
+.Sp
+.Vb 1
+\&  % git remote add fork git@github.com:MyUser/perl5.git
+.Ve
+.Sp
+For more information, see \*(L"Connecting to GitHub with \s-1SSH\*(R"\s0 <https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh>.
+.Sp
+If you'd rather use an \s-1HTTPS URL\s0 for your \f(CW\*(C`git push\*(C'\fR see \*(L"Cloning with
+\&\s-1HTTPS\s0 URLs\*(R" <https://docs.github.com/en/free-pro-team@latest/github/using-git/which-remote-url-should-i-use#cloning-with-https-urls>.
+.Sp
+.Vb 1
+\&  % git remote add fork https://github.com/MyUser/perl5.git
+.Ve
+.Sp
+Then, push your new branch to your fork.
+.Sp
+.Vb 1
+\&  % git push \-u fork mychange
+.Ve
+.Sp
+Finally, create a Pull Request on GitHub from your branch to blead as
+described in the GitHub documentation at
+<https://help.github.com/en/articles/creating\-a\-pull\-request\-from\-a\-fork>.
+.IP "\(bu" 4
+Thank you
+.Sp
+The porters appreciate the time you spent helping to make Perl better.
+Thank you!
+.IP "\(bu" 4
+Acknowledgement
+.Sp
+All contributors are credited (by name and email address) in the
+\&\s-1AUTHORS\s0 file, which is part of the perl distribution, as well as the
+Git commit history.
+.Sp
+If you don’t want to be included in the \s-1AUTHORS\s0 file, just let us
+know. Otherwise we will take your submission of a patch as permission
+to credit you in the \s-1AUTHORS\s0 file.
+.IP "\(bu" 4
+Next time
+.Sp
+The next time you wish to make a patch, you need to start from the
+latest perl in a pristine state.  Check you don't have any local changes
+or added files in your perl check-out which you wish to keep, then run
+these commands:
+.Sp
+.Vb 4
+\&  % git checkout blead
+\&  % git pull
+\&  % git reset \-\-hard origin/blead
+\&  % git clean \-dxf
+.Ve
+.SH "BUG REPORTING"
+.IX Header "BUG REPORTING"
+If you want to report a bug in Perl, or browse existing Perl bugs and
+patches, use the GitHub issue tracker at
+<https://github.com/perl/perl5/issues>.
+.PP
+Please check the archive of the perl5\-porters list (see below) and/or
+the bug tracking system before submitting a bug report.  Often, you'll
+find that the bug has been reported already.
+.PP
+You can log in to the bug tracking system and comment on existing bug
+reports.  If you have additional information regarding an existing bug,
+please add it.  This will help the porters fix the bug.
+.SH "PERL 5 PORTERS"
+.IX Header "PERL 5 PORTERS"
+The perl5\-porters (p5p) mailing list is where the Perl standard
+distribution is maintained and developed.  The people who maintain Perl
+are also referred to as the \*(L"Perl 5 Porters\*(R", \*(L"p5p\*(R" or just the
+\&\*(L"porters\*(R".
+.PP
+A searchable archive of the list is available at
+<https://markmail.org/search/?q=perl5\-porters>.  There is also an archive at
+<https://archive.develooper.com/perl5\-porters@perl.org/>.
+.SS "perl-changes mailing list"
+.IX Subsection "perl-changes mailing list"
+The perl5\-changes mailing list receives a copy of each patch that gets
+submitted to the maintenance and development branches of the perl
+repository.  See <https://lists.perl.org/list/perl5\-changes.html> for
+subscription and archive information.
+.SS "#p5p on \s-1IRC\s0"
+.IX Subsection "#p5p on IRC"
+Many porters are also active on the <irc://irc.perl.org/#p5p> channel.
+Feel free to join the channel and ask questions about hacking on the
+Perl core.
+.SH "GETTING THE PERL SOURCE"
+.IX Header "GETTING THE PERL SOURCE"
+All of Perl's source code is kept centrally in a Git repository at
+\&\fIgithub.com\fR.  The repository contains many Perl revisions
+from Perl 1 onwards and all the revisions from Perforce, the previous
+version control system.
+.PP
+For much more detail on using git with the Perl repository, please see
+perlgit.
+.SS "Read access via Git"
+.IX Subsection "Read access via Git"
+You will need a copy of Git for your computer.  You can fetch a copy of
+the repository using the git protocol:
+.PP
+.Vb 1
+\&  % git clone git@github.com:Perl/perl5.git perl
+.Ve
+.PP
+This clones the repository and makes a local copy in the \fIperl\fR
+directory.
+.PP
+If you cannot use the git protocol for firewall reasons, you can also
+clone via http:
+.PP
+.Vb 1
+\&  % git clone https://github.com/Perl/perl5.git perl
+.Ve
+.SS "Read access via the web"
+.IX Subsection "Read access via the web"
+You may access the repository over the web.  This allows you to browse
+the tree, see recent commits, subscribe to repository notifications,
+search for particular commits and more.  You may access it at
+<https://github.com/Perl/perl5>.
+.SS "Write access via git"
+.IX Subsection "Write access via git"
+If you have a commit bit, please see perlgit for more details on
+using git.
+.SH "PATCHING PERL"
+.IX Header "PATCHING PERL"
+If you're planning to do more extensive work than a single small fix,
+we encourage you to read the documentation below.  This will help you
+focus your work and make your patches easier to incorporate into the
+Perl source.
+.SS "Submitting patches"
+.IX Subsection "Submitting patches"
+If you have a small patch to submit, please submit it via the GitHub
+Pull Request workflow.  You may also send patches to the p5p list.
+.PP
+Patches are reviewed and discussed on GitHub or the p5p list.  Simple,
+uncontroversial patches will usually be applied without any discussion.
+When the patch is applied, the ticket will be updated and you will
+receive email.
+.PP
+In other cases, the patch will need more work or discussion.
+You are encouraged to participate in the discussion and advocate for
+your patch.  Sometimes your patch may get lost in the shuffle.  It's
+appropriate to send a reminder email to p5p if no action has been taken
+in a month.  Please remember that the Perl 5 developers are all
+volunteers, and be polite.
+.PP
+Changes are always applied directly to the main development branch,
+called \*(L"blead\*(R".  Some patches may be backported to a maintenance
+branch.  If you think your patch is appropriate for the maintenance
+branch (see \*(L"\s-1MAINTENANCE BRANCHES\*(R"\s0 in perlpolicy), please explain why
+when you submit it.
+.SS "Getting your patch accepted"
+.IX Subsection "Getting your patch accepted"
+If you are submitting a code patch there are several things that you
+can do to help the Perl 5 Porters accept your patch.
+.PP
+\fIPatch style\fR
+.IX Subsection "Patch style"
+.PP
+Using the GitHub Pull Request workflow, your patch will automatically
+be available in a suitable format.  If you wish to submit a patch to
+the p5p list for review, make sure to create it appropriately.
+.PP
+If you used git to check out the Perl source, then using \f(CW\*(C`git
+format\-patch\*(C'\fR will produce a patch in a style suitable for Perl.  The
+\&\f(CW\*(C`format\-patch\*(C'\fR command produces one patch file for each commit you
+made.  If you prefer to send a single patch for all commits, you can
+use \f(CW\*(C`git diff\*(C'\fR.
+.PP
+.Vb 3
+\&  % git checkout blead
+\&  % git pull
+\&  % git diff blead my\-branch\-name
+.Ve
+.PP
+This produces a patch based on the difference between blead and your
+current branch.  It's important to make sure that blead is up to date
+before producing the diff, that's why we call \f(CW\*(C`git pull\*(C'\fR first.
+.PP
+We strongly recommend that you use git if possible.  It will make your
+life easier, and ours as well.
+.PP
+However, if you're not using git, you can still produce a suitable
+patch.  You'll need a pristine copy of the Perl source to diff against.
+The porters prefer unified diffs.  Using \s-1GNU\s0 \f(CW\*(C`diff\*(C'\fR, you can produce a
+diff like this:
+.PP
+.Vb 1
+\&  % diff \-Npurd perl.pristine perl.mine
+.Ve
+.PP
+Make sure that you \f(CW\*(C`make realclean\*(C'\fR in your copy of Perl to remove any
+build artifacts, or you may get a confusing result.
+.PP
+\fICommit message\fR
+.IX Subsection "Commit message"
+.PP
+As you craft each patch you intend to submit to the Perl core, it's
+important to write a good commit message.  This is especially important
+if your submission will consist of a series of commits.
+.PP
+The first line of the commit message should be a short description
+without a period.  It should be no longer than the subject line of an
+email, 50 characters being a good rule of thumb.
+.PP
+A lot of Git tools (Gitweb, GitHub, git log \-\-pretty=oneline, ...) will
+only display the first line (cut off at 50 characters) when presenting
+commit summaries.
+.PP
+The commit message should include a description of the problem that the
+patch corrects or new functionality that the patch adds.
+.PP
+As a general rule of thumb, your commit message should help a
+programmer who knows the Perl core quickly understand what you were
+trying to do, how you were trying to do it, and why the change matters
+to Perl.
+.IP "\(bu" 4
+Why
+.Sp
+Your commit message should describe why the change you are making is
+important.  When someone looks at your change in six months or six
+years, your intent should be clear.
+.Sp
+If you're deprecating a feature with the intent of later simplifying
+another bit of code, say so.  If you're fixing a performance problem or
+adding a new feature to support some other bit of the core, mention
+that.
+.IP "\(bu" 4
+What
+.Sp
+Your commit message should describe what part of the Perl core you're
+changing and what you expect your patch to do.
+.IP "\(bu" 4
+How
+.Sp
+While it's not necessary for documentation changes, new tests or
+trivial patches, it's often worth explaining how your change works.
+Even if it's clear to you today, it may not be clear to a porter next
+month or next year.
+.PP
+A commit message isn't intended to take the place of comments in your
+code.  Commit messages should describe the change you made, while code
+comments should describe the current state of the code.
+.PP
+If you've just implemented a new feature, complete with doc, tests and
+well-commented code, a brief commit message will often suffice.  If,
+however, you've just changed a single character deep in the parser or
+lexer, you might need to write a small novel to ensure that future
+readers understand what you did and why you did it.
+.PP
+\fIComments, Comments, Comments\fR
+.IX Subsection "Comments, Comments, Comments"
+.PP
+Be sure to adequately comment your code.  While commenting every line
+is unnecessary, anything that takes advantage of side effects of
+operators, that creates changes that will be felt outside of the
+function being patched, or that others may find confusing should be
+documented.  If you are going to err, it is better to err on the side
+of adding too many comments than too few.
+.PP
+The best comments explain \fIwhy\fR the code does what it does, not \fIwhat
+it does\fR.
+.PP
+\fIStyle\fR
+.IX Subsection "Style"
+.PP
+In general, please follow the particular style of the code you are
+patching.
+.PP
+In particular, follow these general guidelines for patching Perl
+sources:
+.IP "\(bu" 4
+4\-wide indents for code, 2\-wide indents for nested \s-1CPP\s0 \f(CW\*(C`#define\*(C'\fRs,
+with 8\-wide tabstops.
+.IP "\(bu" 4
+Use spaces for indentation, not tab characters.
+.Sp
+The codebase is a mixture of tabs and spaces for indentation, and we
+are moving to spaces only.  Converting lines you're patching from 8\-wide
+tabs to spaces will help this migration.
+.IP "\(bu" 4
+Try not to exceed 79 columns
+.Sp
+In general, we target 80 column lines.  When sticking to 80 columns would lead
+to torturous code or rework, it's fine to go longer.  Try to keep your excess
+past 80 to a minimum.
+.IP "\(bu" 4
+\&\s-1ANSI C\s0 prototypes
+.IP "\(bu" 4
+Uncuddled elses and \*(L"K&R\*(R" style for indenting control constructs
+.IP "\(bu" 4
+No \*(C+ style (//) comments
+.IP "\(bu" 4
+Mark places that need to be revisited with \s-1XXX\s0 (and revisit often!)
+.IP "\(bu" 4
+Opening brace lines up with \*(L"if\*(R" when conditional spans multiple lines;
+should be at end-of-line otherwise
+.IP "\(bu" 4
+In function definitions, name starts in column 0 (return value-type is on
+previous line)
+.IP "\(bu" 4
+Single space after keywords that are followed by parens, no space
+between function name and following paren
+.IP "\(bu" 4
+Avoid assignments in conditionals, but if they're unavoidable, use
+extra paren, e.g. \*(L"if (a && (b = c)) ...\*(R"
+.IP "\(bu" 4
+\&\*(L"return foo;\*(R" rather than \*(L"return(foo);\*(R"
+.IP "\(bu" 4
+\&\*(L"if (!foo) ...\*(R" rather than \*(L"if (foo == \s-1FALSE\s0) ...\*(R" etc.
+.IP "\(bu" 4
+Do not declare variables using \*(L"register\*(R".  It may be counterproductive
+with modern compilers, and is deprecated in \*(C+, under which the Perl
+source is regularly compiled.
+.IP "\(bu" 4
+In-line functions that are in headers that are accessible to \s-1XS\s0 code
+need to be able to compile without warnings with commonly used extra
+compilation flags, such as gcc's \f(CW\*(C`\-Wswitch\-default\*(C'\fR which warns
+whenever a switch statement does not have a \*(L"default\*(R" case.  The use of
+these extra flags is to catch potential problems in legal C code, and
+is often used by Perl aggregators, such as Linux distributors.
+.PP
+\fITest suite\fR
+.IX Subsection "Test suite"
+.PP
+If your patch changes code (rather than just changing documentation),
+you should also include one or more test cases which illustrate the bug
+you're fixing or validate the new functionality you're adding.  In
+general, you should update an existing test file rather than create a
+new one.
+.PP
+Your test suite additions should generally follow these guidelines
+(courtesy of Gurusamy Sarathy <gsar@activestate.com>):
+.IP "\(bu" 4
+Know what you're testing.  Read the docs, and the source.
+.IP "\(bu" 4
+Tend to fail, not succeed.
+.IP "\(bu" 4
+Interpret results strictly.
+.IP "\(bu" 4
+Use unrelated features (this will flush out bizarre interactions).
+.IP "\(bu" 4
+Use non-standard idioms (otherwise you are not testing \s-1TIMTOWTDI\s0).
+.IP "\(bu" 4
+Avoid using hardcoded test numbers whenever possible (the \s-1EXPECTED/GOT\s0
+found in t/op/tie.t is much more maintainable, and gives better failure
+reports).
+.IP "\(bu" 4
+Give meaningful error messages when a test fails.
+.IP "\(bu" 4
+Avoid using qx// and \fBsystem()\fR unless you are testing for them.  If you
+do use them, make sure that you cover _all_ perl platforms.
+.IP "\(bu" 4
+Unlink any temporary files you create.
+.IP "\(bu" 4
+Promote unforeseen warnings to errors with \f(CW$SIG\fR{_\|_WARN_\|_}.
+.IP "\(bu" 4
+Be sure to use the libraries and modules shipped with the version being
+tested, not those that were already installed.
+.IP "\(bu" 4
+Add comments to the code explaining what you are testing for.
+.IP "\(bu" 4
+Make updating the '1..42' string unnecessary.  Or make sure that you
+update it.
+.IP "\(bu" 4
+Test _all_ behaviors of a given operator, library, or function.
+.Sp
+Test all optional arguments.
+.Sp
+Test return values in various contexts (boolean, scalar, list, lvalue).
+.Sp
+Use both global and lexical variables.
+.Sp
+Don't forget the exceptional, pathological cases.
+.SS "Patching a core module"
+.IX Subsection "Patching a core module"
+This works just like patching anything else, with one extra
+consideration.
+.PP
+Modules in the \fIcpan/\fR directory of the source tree are maintained
+outside of the Perl core.  When the author updates the module, the
+updates are simply copied into the core.  See that module's
+documentation or its listing on <https://metacpan.org/> for more
+information on reporting bugs and submitting patches.
+.PP
+In most cases, patches to modules in \fIcpan/\fR should be sent upstream
+and should not be applied to the Perl core individually.  If a patch to
+a file in \fIcpan/\fR absolutely cannot wait for the fix to be made
+upstream, released to \s-1CPAN\s0 and copied to blead, you must add (or
+update) a \f(CW\*(C`CUSTOMIZED\*(C'\fR entry in the \fIPorting/Maintainers.pl\fR file
+to flag that a local modification has been made.  See
+\&\fIPorting/Maintainers.pl\fR for more details.
+.PP
+In contrast, modules in the \fIdist/\fR directory are maintained in the
+core.
+.SS "Updating perldelta"
+.IX Subsection "Updating perldelta"
+For changes significant enough to warrant a \fIpod/perldelta.pod\fR entry,
+the porters will greatly appreciate it if you submit a delta entry
+along with your actual change.  Significant changes include, but are
+not limited to:
+.IP "\(bu" 4
+Adding, deprecating, or removing core features
+.IP "\(bu" 4
+Adding, deprecating, removing, or upgrading core or dual-life modules
+.IP "\(bu" 4
+Adding new core tests
+.IP "\(bu" 4
+Fixing security issues and user-visible bugs in the core
+.IP "\(bu" 4
+Changes that might break existing code, either on the perl or C level
+.IP "\(bu" 4
+Significant performance improvements
+.IP "\(bu" 4
+Adding, removing, or significantly changing documentation in the
+\&\fIpod/\fR directory
+.IP "\(bu" 4
+Important platform-specific changes
+.PP
+Please make sure you add the perldelta entry to the right section
+within \fIpod/perldelta.pod\fR.  More information on how to write good
+perldelta entries is available in the \f(CW\*(C`Style\*(C'\fR section of
+\&\fIPorting/how_to_write_a_perldelta.pod\fR.
+.SS "What makes for a good patch?"
+.IX Subsection "What makes for a good patch?"
+New features and extensions to the language can be contentious.  There
+is no specific set of criteria which determine what features get added,
+but here are some questions to consider when developing a patch:
+.PP
+\fIDoes the concept match the general goals of Perl?\fR
+.IX Subsection "Does the concept match the general goals of Perl?"
+.PP
+Our goals include, but are not limited to:
+.IP "1." 4
+Keep it fast, simple, and useful.
+.IP "2." 4
+Keep features/concepts as orthogonal as possible.
+.IP "3." 4
+No arbitrary limits (platforms, data sizes, cultures).
+.IP "4." 4
+Keep it open and exciting to use/patch/advocate Perl everywhere.
+.IP "5." 4
+Either assimilate new technologies, or build bridges to them.
+.PP
+\fIWhere is the implementation?\fR
+.IX Subsection "Where is the implementation?"
+.PP
+All the talk in the world is useless without an implementation.  In
+almost every case, the person or people who argue for a new feature
+will be expected to be the ones who implement it.  Porters capable of
+coding new features have their own agendas, and are not available to
+implement your (possibly good) idea.
+.PP
+\fIBackwards compatibility\fR
+.IX Subsection "Backwards compatibility"
+.PP
+It's a cardinal sin to break existing Perl programs.  New warnings can
+be contentious\*(--some say that a program that emits warnings is not
+broken, while others say it is.  Adding keywords has the potential to
+break programs, changing the meaning of existing token sequences or
+functions might break programs.
+.PP
+The Perl 5 core includes mechanisms to help porters make backwards
+incompatible changes more compatible such as the feature and
+deprecate modules.  Please use them when appropriate.
+.PP
+\fICould it be a module instead?\fR
+.IX Subsection "Could it be a module instead?"
+.PP
+Perl 5 has extension mechanisms, modules and \s-1XS,\s0 specifically to avoid
+the need to keep changing the Perl interpreter.  You can write modules
+that export functions, you can give those functions prototypes so they
+can be called like built-in functions, you can even write \s-1XS\s0 code to
+mess with the runtime data structures of the Perl interpreter if you
+want to implement really complicated things.
+.PP
+Whenever possible, new features should be prototyped in a \s-1CPAN\s0 module
+before they will be considered for the core.
+.PP
+\fIIs the feature generic enough?\fR
+.IX Subsection "Is the feature generic enough?"
+.PP
+Is this something that only the submitter wants added to the language,
+or is it broadly useful?  Sometimes, instead of adding a feature with a
+tight focus, the porters might decide to wait until someone implements
+the more generalized feature.
+.PP
+\fIDoes it potentially introduce new bugs?\fR
+.IX Subsection "Does it potentially introduce new bugs?"
+.PP
+Radical rewrites of large chunks of the Perl interpreter have the
+potential to introduce new bugs.
+.PP
+\fIHow big is it?\fR
+.IX Subsection "How big is it?"
+.PP
+The smaller and more localized the change, the better.  Similarly, a
+series of small patches is greatly preferred over a single large patch.
+.PP
+\fIDoes it preclude other desirable features?\fR
+.IX Subsection "Does it preclude other desirable features?"
+.PP
+A patch is likely to be rejected if it closes off future avenues of
+development.  For instance, a patch that placed a true and final
+interpretation on prototypes is likely to be rejected because there are
+still options for the future of prototypes that haven't been addressed.
+.PP
+\fIIs the implementation robust?\fR
+.IX Subsection "Is the implementation robust?"
+.PP
+Good patches (tight code, complete, correct) stand more chance of going
+in.  Sloppy or incorrect patches might be placed on the back burner
+until fixes can be made, or they might be discarded altogether
+without further notice.
+.PP
+\fIIs the implementation generic enough to be portable?\fR
+.IX Subsection "Is the implementation generic enough to be portable?"
+.PP
+The worst patches make use of system-specific features.  It's highly
+unlikely that non-portable additions to the Perl language will be
+accepted.
+.PP
+\fIIs the implementation tested?\fR
+.IX Subsection "Is the implementation tested?"
+.PP
+Patches which change behaviour (fixing bugs or introducing new
+features) must include regression tests to verify that everything works
+as expected.
+.PP
+Without tests provided by the original author, how can anyone else
+changing perl in the future be sure that they haven't unwittingly
+broken the behaviour the patch implements? And without tests, how can
+the patch's author be confident that his/her hard work put into the
+patch won't be accidentally thrown away by someone in the future?
+.PP
+\fIIs there enough documentation?\fR
+.IX Subsection "Is there enough documentation?"
+.PP
+Patches without documentation are probably ill-thought out or
+incomplete.  No features can be added or changed without documentation,
+so submitting a patch for the appropriate pod docs as well as the
+source code is important.
+.PP
+\fIIs there another way to do it?\fR
+.IX Subsection "Is there another way to do it?"
+.PP
+Larry said "Although the Perl Slogan is \fIThere's More Than One Way to
+Do It\fR, I hesitate to make 10 ways to do something".  This is a tricky
+heuristic to navigate, though\*(--one man's essential addition is another
+man's pointless cruft.
+.PP
+\fIDoes it create too much work?\fR
+.IX Subsection "Does it create too much work?"
+.PP
+Work for the committers, work for Perl programmers, work for module
+authors, ... Perl is supposed to be easy.
+.PP
+\fIPatches speak louder than words\fR
+.IX Subsection "Patches speak louder than words"
+.PP
+Working code is always preferred to pie-in-the-sky ideas.  A patch to
+add a feature stands a much higher chance of making it to the language
+than does a random feature request, no matter how fervently argued the
+request might be.  This ties into \*(L"Will it be useful?\*(R", as the fact
+that someone took the time to make the patch demonstrates a strong
+desire for the feature.
+.SH "TESTING"
+.IX Header "TESTING"
+The core uses the same testing style as the rest of Perl, a simple
+\&\*(L"ok/not ok\*(R" run through Test::Harness, but there are a few special
+considerations.
+.PP
+There are three ways to write a test in the core: Test::More,
+\&\fIt/test.pl\fR and ad hoc \f(CW\*(C`print $test ? "ok 42\en" : "not ok 42\en"\*(C'\fR.
+The decision of which to use depends on what part of the test suite
+you're working on.  This is a measure to prevent a high-level failure
+(such as Config.pm breaking) from causing basic functionality tests to
+fail.
+.PP
+The \fIt/test.pl\fR library provides some of the features of
+Test::More, but avoids loading most modules and uses as few core
+features as possible.
+.PP
+If you write your own test, use the Test Anything
+Protocol <https://testanything.org>.
+.IP "\(bu" 4
+\&\fIt/base\fR, \fIt/comp\fR and \fIt/opbasic\fR
+.Sp
+Since we don't know if \f(CW\*(C`require\*(C'\fR works, or even subroutines, use ad hoc
+tests for these three.  Step carefully to avoid using the feature being
+tested.  Tests in \fIt/opbasic\fR, for instance, have been placed there
+rather than in \fIt/op\fR because they test functionality which
+\&\fIt/test.pl\fR presumes has already been demonstrated to work.
+.IP "\(bu" 4
+All other subdirectories of \fIt/\fR
+.Sp
+Now that basic \fBrequire()\fR and subroutines are tested, you can use the
+\&\fIt/test.pl\fR library.
+.Sp
+You can also use certain libraries like Config conditionally, but be
+sure to skip the test gracefully if it's not there.
+.IP "\(bu" 4
+Test files not found under \fIt/\fR
+.Sp
+This category includes \fI.t\fR files underneath directories such as \fIdist\fR,
+\&\fIext\fR and \fIlib\fR.  Since the core of Perl has now been tested, Test::More
+can and now should be used.  You can also use the full suite of core modules
+in the tests.  (As noted in \*(L"Patching a core module\*(R" above, changes to
+\&\fI.t\fR files found under \fIcpan/\fR should be submitted to the upstream
+maintainers of those modules.)
+.PP
+When you say \*(L"make test\*(R", Perl uses the \fIt/TEST\fR program to run the
+test suite (except under Win32 where it uses \fIt/harness\fR instead).
+All tests are run from the \fIt/\fR directory, \fBnot\fR the directory which
+contains the test.  This causes some problems with the tests in
+\&\fIlib/\fR, so here's some opportunity for some patching.
+.PP
+You must be triply conscious of cross-platform concerns.  This usually
+boils down to using File::Spec, avoiding things like \f(CW\*(C`fork()\*(C'\fR
+and \f(CW\*(C`system()\*(C'\fR unless absolutely necessary, and not assuming that a
+given character has a particular ordinal value (code point) or that its
+\&\s-1UTF\-8\s0 representation is composed of particular bytes.
+.PP
+There are several functions available to specify characters and code
+points portably in tests.  The always-preloaded functions
+\&\f(CW\*(C`utf8::unicode_to_native()\*(C'\fR and its inverse
+\&\f(CW\*(C`utf8::native_to_unicode()\*(C'\fR take code points and translate
+appropriately.  The file \fIt/charset_tools.pl\fR has several functions
+that can be useful.  It has versions of the previous two functions
+that take strings as inputs \*(-- not single numeric code points:
+\&\f(CW\*(C`uni_to_native()\*(C'\fR and \f(CW\*(C`native_to_uni()\*(C'\fR.  If you must look at the
+individual bytes comprising a \s-1UTF\-8\s0 encoded string,
+\&\f(CW\*(C`byte_utf8a_to_utf8n()\*(C'\fR takes as input a string of those bytes encoded
+for an \s-1ASCII\s0 platform, and returns the equivalent string in the native
+platform.  For example, \f(CW\*(C`byte_utf8a_to_utf8n("\exC2\exA0")\*(C'\fR returns the
+byte sequence on the current platform that form the \s-1UTF\-8\s0 for \f(CW\*(C`U+00A0\*(C'\fR,
+since \f(CW"\exC2\exA0"\fR are the \s-1UTF\-8\s0 bytes on an \s-1ASCII\s0 platform for that
+code point.  This function returns \f(CW"\exC2\exA0"\fR on an \s-1ASCII\s0 platform, and
+\&\f(CW"\ex80\ex41"\fR on an \s-1EBCDIC 1047\s0 one.
+.PP
+But easiest is, if the character is specifiable as a literal, like
+\&\f(CW"A"\fR or \f(CW"%"\fR, to use that; if not so specificable, you can use
+\&\f(CW\*(C`\eN{}\*(C'\fR , if the side effects aren't troublesome.  Simply specify all
+your characters in hex, using \f(CW\*(C`\eN{U+ZZ}\*(C'\fR instead of \f(CW\*(C`\exZZ\*(C'\fR.  \f(CW\*(C`\eN{}\*(C'\fR
+is the Unicode name, and so it
+always gives you the Unicode character.  \f(CW\*(C`\eN{U+41}\*(C'\fR is the character
+whose Unicode code point is \f(CW0x41\fR, hence is \f(CW\*(AqA\*(Aq\fR on all platforms.
+The side effects are:
+.IP "\(bu" 4
+These select Unicode rules.  That means that in double-quotish strings,
+the string is always converted to \s-1UTF\-8\s0 to force a Unicode
+interpretation (you can \f(CW\*(C`utf8::downgrade()\*(C'\fR afterwards to convert back
+to non\-UTF8, if possible).  In regular expression patterns, the
+conversion isn't done, but if the character set modifier would
+otherwise be \f(CW\*(C`/d\*(C'\fR, it is changed to \f(CW\*(C`/u\*(C'\fR.
+.IP "\(bu" 4
+If you use the form \f(CW\*(C`\eN{\f(CIcharacter name\f(CW}\*(C'\fR, the charnames module
+gets automatically loaded.  This may not be suitable for the test level
+you are doing.
+.PP
+If you are testing locales (see perllocale), there are helper
+functions in \fIt/loc_tools.pl\fR to enable you to see what locales there
+are on the current platform.
+.ie n .SS "Special ""make test"" targets"
+.el .SS "Special \f(CWmake test\fP targets"
+.IX Subsection "Special make test targets"
+There are various special make targets that can be used to test Perl
+slightly differently than the standard \*(L"test\*(R" target.  Not all them are
+expected to give a 100% success rate.  Many of them have several
+aliases, and many of them are not available on certain operating
+systems.
+.IP "\(bu" 4
+test_porting
+.Sp
+This runs some basic sanity tests on the source tree and helps catch
+basic errors before you submit a patch.
+.IP "\(bu" 4
+minitest
+.Sp
+Run \fIminiperl\fR on \fIt/base\fR, \fIt/comp\fR, \fIt/cmd\fR, \fIt/run\fR, \fIt/io\fR,
+\&\fIt/op\fR, \fIt/uni\fR and \fIt/mro\fR tests.
+.Sp
+\&\fIminiperl\fR is a minimalistic perl built to bootstrap building
+extensions, utilties, documentation etc.  It doesn't support dynamic
+loading and depending on the point in the build process will only have
+access to a limited set of core modules.  \fIminiperl\fR is not intended
+for day to day use.
+.IP "\(bu" 4
+test.valgrind check.valgrind
+.Sp
+(Only in Linux) Run all the tests using the memory leak + naughty
+memory access tool \*(L"valgrind\*(R".  The log files will be named
+\&\fItestname.valgrind\fR.
+.IP "\(bu" 4
+test_harness
+.Sp
+Run the test suite with the \fIt/harness\fR controlling program, instead
+of \fIt/TEST\fR.  \fIt/harness\fR is more sophisticated, and uses the
+Test::Harness module, thus using this test target supposes that perl
+mostly works.  The main advantage for our purposes is that it prints a
+detailed summary of failed tests at the end.  Also, unlike \fIt/TEST\fR,
+it doesn't redirect stderr to stdout.
+.Sp
+Note that under Win32 \fIt/harness\fR is always used instead of \fIt/TEST\fR,
+so there is no special \*(L"test_harness\*(R" target.
+.Sp
+Under Win32's \*(L"test\*(R" target you may use the \s-1TEST_SWITCHES\s0 and
+\&\s-1TEST_FILES\s0 environment variables to control the behaviour of
+\&\fIt/harness\fR.  This means you can say
+.Sp
+.Vb 2
+\&    nmake test TEST_FILES="op/*.t"
+\&    nmake test TEST_SWITCHES="\-torture" TEST_FILES="op/*.t"
+.Ve
+.IP "\(bu" 4
+test-notty test_notty
+.Sp
+Sets \s-1PERL_SKIP_TTY_TEST\s0 to true before running normal test.
+.SS "Parallel tests"
+.IX Subsection "Parallel tests"
+The core distribution can now run its regression tests in parallel on
+Unix-like and Windows platforms.  On Unix, instead of running \f(CW\*(C`make
+test\*(C'\fR, set \f(CW\*(C`TEST_JOBS\*(C'\fR in your environment to the number of tests to
+run in parallel, and run \f(CW\*(C`make test_harness\*(C'\fR.  On a Bourne-like shell,
+this can be done as
+.PP
+.Vb 1
+\&    TEST_JOBS=3 make test_harness  # Run 3 tests in parallel
+.Ve
+.PP
+An environment variable is used, rather than parallel make itself,
+because TAP::Harness needs to be able to schedule individual
+non-conflicting test scripts itself, and there is no standard interface
+to \f(CW\*(C`make\*(C'\fR utilities to interact with their job schedulers.
+.PP
+Tests are normally run in a logical order, with the sanity tests first,
+then the main tests of the Perl core functionality, then the tests for
+the non-core modules.  On many-core systems, this may not use the
+hardware as effectively as possible.  By also specifying
+.PP
+.Vb 1
+\& TEST_JOBS=19 PERL_TEST_HARNESS_ASAP=1 make \-j19 test_harness
+.Ve
+.PP
+you signal that you want the tests to finish in wall-clock time as short
+as possible.  After the sanity tests are completed, this causes the
+remaining ones to be packed into the available cores as tightly as
+we know how.  This has its greatest effect on slower, many-core systems.
+Throughput was sped up by 20% on an outmoded 24\-core system; less on
+more recent faster ones with fewer cores.
+.PP
+Note that the command line above added a \f(CW\*(C`\-j\*(C'\fR parameter to make, so as
+to cause parallel compilation.  This may or may not work on your
+platform.
+.SS "Running tests by hand"
+.IX Subsection "Running tests by hand"
+You can run part of the test suite by hand by using one of the
+following commands from the \fIt/\fR directory:
+.PP
+.Vb 1
+\&    ./perl \-I../lib TEST list\-of\-.t\-files
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    ./perl \-I../lib harness list\-of\-.t\-files
+.Ve
+.PP
+(If you don't specify test scripts, the whole test suite will be run.)
+.SS "Using \fIt/harness\fP for testing"
+.IX Subsection "Using t/harness for testing"
+If you use \f(CW\*(C`harness\*(C'\fR for testing, you have several command line
+options available to you.  The arguments are as follows, and are in the
+order that they must appear if used together.
+.PP
+.Vb 2
+\&    harness \-v \-torture \-re=pattern LIST OF FILES TO TEST
+\&    harness \-v \-torture \-re LIST OF PATTERNS TO MATCH
+.Ve
+.PP
+If \f(CW\*(C`LIST OF FILES TO TEST\*(C'\fR is omitted, the file list is obtained from
+the manifest.  The file list may include shell wildcards which will be
+expanded out.
+.IP "\(bu" 4
+\&\-v
+.Sp
+Run the tests under verbose mode so you can see what tests were run,
+and debug output.
+.IP "\(bu" 4
+\&\-torture
+.Sp
+Run the torture tests as well as the normal set.
+.IP "\(bu" 4
+\&\-re=PATTERN
+.Sp
+Filter the file list so that all the test files run match \s-1PATTERN.\s0
+Note that this form is distinct from the \fB\-re \s-1LIST OF PATTERNS\s0\fR form
+below in that it allows the file list to be provided as well.
+.IP "\(bu" 4
+\&\-re \s-1LIST OF PATTERNS\s0
+.Sp
+Filter the file list so that all the test files run match
+/(LIST|OF|PATTERNS)/.  Note that with this form the patterns are joined
+by '|' and you cannot supply a list of files, instead the test files
+are obtained from the \s-1MANIFEST.\s0
+.PP
+You can run an individual test by a command similar to
+.PP
+.Vb 1
+\&    ./perl \-I../lib path/to/foo.t
+.Ve
+.PP
+except that the harnesses set up some environment variables that may
+affect the execution of the test:
+.IP "\(bu" 4
+PERL_CORE=1
+.Sp
+indicates that we're running this test as part of the perl core test
+suite.  This is useful for modules that have a dual life on \s-1CPAN.\s0
+.IP "\(bu" 4
+PERL_DESTRUCT_LEVEL=2
+.Sp
+is set to 2 if it isn't set already (see
+\&\*(L"\s-1PERL_DESTRUCT_LEVEL\*(R"\s0 in perlhacktips).
+.IP "\(bu" 4
+\&\s-1PERL\s0
+.Sp
+(used only by \fIt/TEST\fR) if set, overrides the path to the perl
+executable that should be used to run the tests (the default being
+\&\fI./perl\fR).
+.IP "\(bu" 4
+\&\s-1PERL_SKIP_TTY_TEST\s0
+.Sp
+if set, tells to skip the tests that need a terminal.  It's actually
+set automatically by the Makefile, but can also be forced artificially
+by running 'make test_notty'.
+.PP
+\fIOther environment variables that may influence tests\fR
+.IX Subsection "Other environment variables that may influence tests"
+.IP "\(bu" 4
+PERL_TEST_Net_Ping
+.Sp
+Setting this variable runs all the Net::Ping modules tests, otherwise
+some tests that interact with the outside world are skipped.  See
+perl58delta.
+.IP "\(bu" 4
+\&\s-1PERL_TEST_NOVREXX\s0
+.Sp
+Setting this variable skips the vrexx.t tests for \s-1OS2::REXX.\s0
+.IP "\(bu" 4
+\&\s-1PERL_TEST_NUMCONVERTS\s0
+.Sp
+This sets a variable in op/numconvert.t.
+.IP "\(bu" 4
+\&\s-1PERL_TEST_MEMORY\s0
+.Sp
+Setting this variable includes the tests in \fIt/bigmem/\fR.  This should
+be set to the number of gigabytes of memory available for testing, eg.
+\&\f(CW\*(C`PERL_TEST_MEMORY=4\*(C'\fR indicates that tests that require 4GiB of
+available memory can be run safely.
+.PP
+See also the documentation for the Test and Test::Harness modules, for
+more environment variables that affect testing.
+.SS "Performance testing"
+.IX Subsection "Performance testing"
+The file \fIt/perf/benchmarks\fR contains snippets of perl code which are
+intended to be benchmarked across a range of perls by the
+\&\fIPorting/bench.pl\fR tool. If you fix or enhance a performance issue, you
+may want to add a representative code sample to the file, then run
+\&\fIbench.pl\fR against the previous and current perls to see what difference
+it has made, and whether anything else has slowed down as a consequence.
+.PP
+The file \fIt/perf/opcount.t\fR is designed to test whether a particular
+code snippet has been compiled into an optree containing specified
+numbers of particular op types. This is good for testing whether
+optimisations which alter ops, such as converting an \f(CW\*(C`aelem\*(C'\fR op into an
+\&\f(CW\*(C`aelemfast\*(C'\fR op, are really doing that.
+.PP
+The files \fIt/perf/speed.t\fR and \fIt/re/speed.t\fR are designed to test
+things that run thousands of times slower if a particular optimisation
+is broken (for example, the utf8 length cache on long utf8 strings).
+Add a test that will take a fraction of a second normally, and minutes
+otherwise, causing the test file to time out on failure.
+.SS "Building perl at older commits"
+.IX Subsection "Building perl at older commits"
+In the course of hacking on the Perl core distribution, you may have occasion
+to configure, build and test perl at an old commit.  Sometimes \f(CW\*(C`make\*(C'\fR will
+fail during this process.  If that happens, you may be able to salvage the
+situation by using the Devel::PatchPerl library from \s-1CPAN\s0 (not included in the
+core) to bring the source code at that commit to a buildable state.
+.PP
+Here's a real world example, taken from work done to resolve
+perl #10118 <https://github.com/Perl/perl5/issues/10118>.
+Use of \fIPorting/bisect.pl\fR had identified commit
+\&\f(CW\*(C`ba77e4cc9d1ceebf472c9c5c18b2377ee47062e6\*(C'\fR as the commit in which a bug was
+corrected.  To confirm, a P5P developer wanted to configure and build perl at
+commit \f(CW\*(C`ba77e4c^\*(C'\fR (presumably \*(L"bad\*(R") and then at \f(CW\*(C`ba77e4c\*(C'\fR (presumably
+\&\*(L"good\*(R").  Normal configuration and build was attempted:
+.PP
+.Vb 2
+\&    $ sh ./Configure \-des \-Dusedevel
+\&    $ make test_prep
+.Ve
+.PP
+\&\f(CW\*(C`make\*(C'\fR, however, failed with output (excerpted) like this:
+.PP
+.Vb 10
+\&    cc \-fstack\-protector \-L/usr/local/lib \-o miniperl \e
+\&      gv.o toke.o perly.o pad.o regcomp.o dump.o util.o \e
+\&      mg.o reentr.o mro.o hv.o av.o run.o pp_hot.o sv.o \e
+\&      pp.o scope.o pp_ctl.o pp_sys.o doop.o doio.o regexec.o \e
+\&      utf8.o taint.o deb.o universal.o globals.o perlio.o \e
+\&      numeric.o mathoms.o locale.o pp_pack.o pp_sort.o  \e
+\&      miniperlmain.o opmini.o perlmini.o
+\&    pp.o: In function \`Perl_pp_pow\*(Aq:
+\&    pp.c:(.text+0x2db9): undefined reference to \`pow\*(Aq
+\&    ...
+\&    collect2: error: ld returned 1 exit status
+\&    makefile:348: recipe for target \*(Aqminiperl\*(Aq failed
+\&    make: *** [miniperl] Error 1
+.Ve
+.PP
+Another P5P contributor recommended installation and use of Devel::PatchPerl
+for this situation, first to determine the version of perl at the commit in
+question, then to patch the source code at that point to facilitate a build.
+.PP
+.Vb 6
+\& $ perl \-MDevel::PatchPerl \-e \e
+\&     \*(Aqprint Devel::PatchPerl\->determine_version("/path/to/sourcecode"),
+\&            "\en";\*(Aq
+\& 5.11.1
+\& $ perl \-MDevel::PatchPerl \-e \e
+\&     \*(AqDevel::PatchPerl\->patch_source("5.11.1", "/path/to/sourcecode");\*(Aq
+.Ve
+.PP
+Once the source was patched, \f(CW\*(C`./Configure\*(C'\fR and \f(CW\*(C`make test_prep\*(C'\fR were called
+and completed successfully, enabling confirmation of the findings in \s-1RT\s0
+#72414.
+.SH "MORE READING FOR GUTS HACKERS"
+.IX Header "MORE READING FOR GUTS HACKERS"
+To hack on the Perl guts, you'll need to read the following things:
+.IP "\(bu" 4
+perlsource
+.Sp
+An overview of the Perl source tree.  This will help you find the files
+you're looking for.
+.IP "\(bu" 4
+perlinterp
+.Sp
+An overview of the Perl interpreter source code and some details on how
+Perl does what it does.
+.IP "\(bu" 4
+perlhacktut
+.Sp
+This document walks through the creation of a small patch to Perl's C
+code.  If you're just getting started with Perl core hacking, this will
+help you understand how it works.
+.IP "\(bu" 4
+perlhacktips
+.Sp
+More details on hacking the Perl core.  This document focuses on lower
+level details such as how to write tests, compilation issues,
+portability, debugging, etc.
+.Sp
+If you plan on doing serious C hacking, make sure to read this.
+.IP "\(bu" 4
+perlguts
+.Sp
+This is of paramount importance, since it's the documentation of what
+goes where in the Perl source.  Read it over a couple of times and it
+might start to make sense \- don't worry if it doesn't yet, because the
+best way to study it is to read it in conjunction with poking at Perl
+source, and we'll do that later on.
+.Sp
+Gisle Aas's \*(L"illustrated perlguts\*(R", also known as \fIillguts\fR, has very
+helpful pictures:
+.Sp
+<https://metacpan.org/release/RURBAN/illguts\-0.49>
+.IP "\(bu" 4
+perlxstut and perlxs
+.Sp
+A working knowledge of \s-1XSUB\s0 programming is incredibly useful for core
+hacking; XSUBs use techniques drawn from the \s-1PP\s0 code, the portion of
+the guts that actually executes a Perl program.  It's a lot gentler to
+learn those techniques from simple examples and explanation than from
+the core itself.
+.IP "\(bu" 4
+perlapi
+.Sp
+The documentation for the Perl \s-1API\s0 explains what some of the internal
+functions do, as well as the many macros used in the source.
+.IP "\(bu" 4
+\&\fIPorting/pumpkin.pod\fR
+.Sp
+This is a collection of words of wisdom for a Perl porter; some of it
+is only useful to the pumpkin holders, but most of it applies to anyone
+wanting to go about Perl development.
+.SH "CPAN TESTERS AND PERL SMOKERS"
+.IX Header "CPAN TESTERS AND PERL SMOKERS"
+The \s-1CPAN\s0 testers ( <http://cpantesters.org/> ) are a group of volunteers
+who test \s-1CPAN\s0 modules on a variety of platforms.
+.PP
+Perl Smokers ( <https://www.nntp.perl.org/group/perl.daily\-build/> and
+<https://www.nntp.perl.org/group/perl.daily\-build.reports/> )
+automatically test Perl source releases on platforms with various
+configurations.
+.PP
+Both efforts welcome volunteers.  In order to get involved in smoke
+testing of the perl itself visit
+<https://metacpan.org/release/Test\-Smoke>.  In order to start smoke
+testing \s-1CPAN\s0 modules visit
+<https://metacpan.org/release/CPANPLUS\-YACSmoke> or
+<https://metacpan.org/release/minismokebox> or
+<https://metacpan.org/release/CPAN\-Reporter>.
+.SH "WHAT NEXT?"
+.IX Header "WHAT NEXT?"
+If you've read all the documentation in the document and the ones
+listed above, you're more than ready to hack on Perl.
+.PP
+Here's some more recommendations
+.IP "\(bu" 4
+Subscribe to perl5\-porters, follow the patches and try and understand
+them; don't be afraid to ask if there's a portion you're not clear on \-
+who knows, you may unearth a bug in the patch...
+.IP "\(bu" 4
+Do read the \s-1README\s0 associated with your operating system, e.g.
+\&\s-1README\s0.aix on the \s-1IBM AIX OS.\s0  Don't hesitate to supply patches to that
+\&\s-1README\s0 if you find anything missing or changed over a new \s-1OS\s0 release.
+.IP "\(bu" 4
+Find an area of Perl that seems interesting to you, and see if you can
+work out how it works.  Scan through the source, and step over it in
+the debugger.  Play, poke, investigate, fiddle! You'll probably get to
+understand not just your chosen area but a much wider range of
+\&\fIperl\fR's activity as well, and probably sooner than you'd think.
+.ie n .SS """The Road goes ever on and on, down from the door where it began."""
+.el .SS "``The Road goes ever on and on, down from the door where it began.''"
+.IX Subsection "The Road goes ever on and on, down from the door where it began."
+If you can do these things, you've started on the long road to Perl
+porting.  Thanks for wanting to help make Perl better \- and happy
+hacking!
+.SS "Metaphoric Quotations"
+.IX Subsection "Metaphoric Quotations"
+If you recognized the quote about the Road above, you're in luck.
+.PP
+Most software projects begin each file with a literal description of
+each file's purpose.  Perl instead begins each with a literary allusion
+to that file's purpose.
+.PP
+Like chapters in many books, all top-level Perl source files (along
+with a few others here and there) begin with an epigrammatic
+inscription that alludes, indirectly and metaphorically, to the
+material you're about to read.
+.PP
+Quotations are taken from writings of J.R.R. Tolkien pertaining to his
+Legendarium, almost always from \fIThe Lord of the Rings\fR.  Chapters and
+page numbers are given using the following editions:
+.IP "\(bu" 4
+\&\fIThe Hobbit\fR, by J.R.R. Tolkien.  The hardcover, 70th\-anniversary
+edition of 2007 was used, published in the \s-1UK\s0 by Harper Collins
+Publishers and in the \s-1US\s0 by the Houghton Mifflin Company.
+.IP "\(bu" 4
+\&\fIThe Lord of the Rings\fR, by J.R.R. Tolkien.  The hardcover,
+50th\-anniversary edition of 2004 was used, published in the \s-1UK\s0 by
+Harper Collins Publishers and in the \s-1US\s0 by the Houghton Mifflin
+Company.
+.IP "\(bu" 4
+\&\fIThe Lays of Beleriand\fR, by J.R.R. Tolkien and published posthumously
+by his son and literary executor, C.J.R. Tolkien, being the 3rd of the
+12 volumes in Christopher's mammoth \fIHistory of Middle Earth\fR.  Page
+numbers derive from the hardcover edition, first published in 1983 by
+George Allen & Unwin; no page numbers changed for the special 3\-volume
+omnibus edition of 2002 or the various trade-paper editions, all again
+now by Harper Collins or Houghton Mifflin.
+.PP
+Other \s-1JRRT\s0 books fair game for quotes would thus include \fIThe
+Adventures of Tom Bombadil\fR, \fIThe Silmarillion\fR, \fIUnfinished Tales\fR,
+and \fIThe Tale of the Children of Hurin\fR, all but the first
+posthumously assembled by \s-1CJRT.\s0  But \fIThe Lord of the Rings\fR itself is
+perfectly fine and probably best to quote from, provided you can find a
+suitable quote there.
+.PP
+So if you were to supply a new, complete, top-level source file to add
+to Perl, you should conform to this peculiar practice by yourself
+selecting an appropriate quotation from Tolkien, retaining the original
+spelling and punctuation and using the same format the rest of the
+quotes are in.  Indirect and oblique is just fine; remember, it's a
+metaphor, so being meta is, after all, what it's for.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+This document was originally written by Nathan Torkington, and is
+maintained by the perl5\-porters mailing list.