summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perlhack.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlhack.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlhack.pod1144
1 files changed, 0 insertions, 1144 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlhack.pod b/Master/tlpkg/tlperl/lib/pods/perlhack.pod
deleted file mode 100644
index 63df5d5dfc3..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlhack.pod
+++ /dev/null
@@ -1,1144 +0,0 @@
-=encoding utf8
-
-=for comment
-Consistent formatting of this file is achieved with:
- perl ./Porting/podtidy pod/perlhack.pod
-
-=head1 NAME
-
-perlhack - How to hack on Perl
-
-=head1 DESCRIPTION
-
-This document explains how Perl development works. It includes details
-about the Perl 5 Porters email list, the Perl repository, the Perlbug
-bug tracker, patch guidelines, and commentary on Perl development
-philosophy.
-
-=head1 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:
-
-=over 4
-
-=item * Check out the source repository
-
-The perl source is in a git repository. You can clone the repository
-with the following command:
-
- % git clone git://perl5.git.perl.org/perl.git perl
-
-=item * Make your change
-
-Hack, hack, hack.
-
-=item * Test your change
-
-You can run all the tests with the following commands:
-
- % ./Configure -des -Dusedevel
- % make test
-
-Keep hacking until the tests pass.
-
-=item * Commit your change
-
-Committing your work will save the change I<on your local system>:
-
- % git commit -a -m 'Commit message goes here'
-
-Make sure the commit message describes your change in a single
-sentence. For example, "Fixed spelling errors in perlhack.pod".
-
-=item * Send your change to perlbug
-
-The next step is to submit your patch to the Perl core ticket system
-via email.
-
-Assuming your patch consists of a single git commit, the following
-writes the file as a MIME attachment, and sends it with a meaningful
-subject:
-
- % git format-patch -1 --attach
- % perlbug -s "[PATCH] $(git log -1 --oneline HEAD)" -f 0001-*.patch
-
-The perlbug program will ask you a few questions about your email
-address and the patch you're submitting. Once you've answered them it
-will submit your patch via email.
-
-=item * Thank you
-
-The porters appreciate the time you spent helping to make Perl better.
-Thank you!
-
-=back
-
-=head1 BUG REPORTING
-
-If you want to report a bug in Perl, you must use the F<perlbug>
-command line tool. This tool will ensure that your bug report includes
-all the relevant system and configuration information.
-
-To browse existing Perl bugs and patches, you can use the web interface
-at L<http://rt.perl.org/>.
-
-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.
-
-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.
-
-=head1 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 "Perl 5 Porters", "p5p" or just the
-"porters".
-
-A searchable archive of the list is available at
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is
-also another archive at
-L<http://archive.develooper.com/perl5-porters@perl.org/>.
-
-=head2 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 L<http://lists.perl.org/list/perl5-changes.html> for
-subscription and archive information.
-
-=head2 #p5p on IRC
-
-Many porters are also active on the L<irc://irc.perl.org/#p5p> channel.
-Feel free to join the channel and ask questions about hacking on the
-Perl core.
-
-=head1 GETTING THE PERL SOURCE
-
-All of Perl's source code is kept centrally in a Git repository at
-I<perl5.git.perl.org>. The repository contains many Perl revisions from
-Perl 1 onwards and all the revisions from Perforce, the previous
-version control system.
-
-For much more detail on using git with the Perl repository, please see
-L<perlgit>.
-
-=head2 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:
-
- % git clone git://perl5.git.perl.org/perl.git perl
-
-This clones the repository and makes a local copy in the F<perl>
-directory.
-
-If you cannot use the git protocol for firewall reasons, you can also
-clone via http, though this is much slower:
-
- % git clone http://perl5.git.perl.org/perl.git perl
-
-=head2 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 RSS feeds for the changes,
-search for particular commits and more. You may access it at
-L<http://perl5.git.perl.org/perl.git>. A mirror of the repository is
-found at L<http://github.com/mirrors/perl>.
-
-=head2 Read access via rsync
-
-You can also choose to use rsync to get a copy of the current source
-tree for the bleadperl branch and all maintenance branches:
-
- % rsync -avz rsync://perl5.git.perl.org/perl-current .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.12.x .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.10.x .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.8.x .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.6.x .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.005xx .
-
-(Add the C<--delete> option to remove leftover files.)
-
-To get a full list of the available sync points:
-
- % rsync perl5.git.perl.org::
-
-=head2 Write access via git
-
-If you have a commit bit, please see L<perlgit> for more details on
-using git.
-
-=head1 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.
-
-=head2 Submitting patches
-
-If you have a small patch to submit, please submit it via perlbug. You
-can also send email directly to perlbug@perl.org. Please note that
-messages sent to perlbug may be held in a moderation queue, so you
-won't receive a response immediately.
-
-You'll know your submission has been processed when you receive an
-email from our ticket tracking system. This email will give you a
-ticket number. Once your patch has made it to the ticket tracking
-system, it will also be sent to the perl5-porters@perl.org list.
-
-Patches are reviewed and discussed on 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. In addition, an email will be sent to the p5p list.
-
-In other cases, the patch will need more work or discussion. That will
-happen on the p5p list.
-
-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.
-
-Changes are always applied directly to the main development branch,
-called "blead". Some patches may be backported to a maintenance branch.
-If you think your patch is appropriate for the maintenance branch,
-please explain why when you submit it.
-
-=head2 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.
-
-=head3 Patch style
-
-If you used git to check out the Perl source, then using C<git
-format-patch> will produce a patch in a style suitable for Perl. The
-C<format-patch> command produces one patch file for each commit you
-made. If you prefer to send a single patch for all commits, you can use
-C<git diff>.
-
- % git checkout blead
- % git pull
- % git diff blead my-branch-name
-
-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 C<git pull> first.
-
-We strongly recommend that you use git if possible. It will make your
-life easier, and ours as well.
-
-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 GNU C<diff>, you can produce a
-diff like this:
-
- % diff -Npurd perl.pristine perl.mine
-
-Make sure that you C<make realclean> in your copy of Perl to remove any
-build artifacts, or you may get a confusing result.
-
-=head3 Commit message
-
-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.
-
-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.
-
-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.
-
-The commit message should include a description of the problem that the
-patch corrects or new functionality that the patch adds.
-
-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.
-
-=over 4
-
-=item * Why
-
-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.
-
-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.
-
-=item * What
-
-Your commit message should describe what part of the Perl core you're
-changing and what you expect your patch to do.
-
-=item * How
-
-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.
-
-=back
-
-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.
-
-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.
-
-=head3 Comments, Comments, Comments
-
-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.
-
-The best comments explain I<why> the code does what it does, not I<what
-it does>.
-
-=head3 Style
-
-In general, please follow the particular style of the code you are
-patching.
-
-In particular, follow these general guidelines for patching Perl
-sources:
-
-=over 4
-
-=item *
-
-8-wide tabs (no exceptions!)
-
-=item *
-
-4-wide indents for code, 2-wide indents for nested CPP #defines
-
-=item *
-
-Try hard not to exceed 79-columns
-
-=item *
-
-ANSI C prototypes
-
-=item *
-
-Uncuddled elses and "K&R" style for indenting control constructs
-
-=item *
-
-No C++ style (//) comments
-
-=item *
-
-Mark places that need to be revisited with XXX (and revisit often!)
-
-=item *
-
-Opening brace lines up with "if" when conditional spans multiple lines;
-should be at end-of-line otherwise
-
-=item *
-
-In function definitions, name starts in column 0 (return value is on
-previous line)
-
-=item *
-
-Single space after keywords that are followed by parens, no space
-between function name and following paren
-
-=item *
-
-Avoid assignments in conditionals, but if they're unavoidable, use
-extra paren, e.g. "if (a && (b = c)) ..."
-
-=item *
-
-"return foo;" rather than "return(foo);"
-
-=item *
-
-"if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
-
-=back
-
-=head3 Test suite
-
-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.
-
-Your test suite additions should generally follow these guidelines
-(courtesy of Gurusamy Sarathy <gsar@activestate.com>):
-
-=over 4
-
-=item *
-
-Know what you're testing. Read the docs, and the source.
-
-=item *
-
-Tend to fail, not succeed.
-
-=item *
-
-Interpret results strictly.
-
-=item *
-
-Use unrelated features (this will flush out bizarre interactions).
-
-=item *
-
-Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
-
-=item *
-
-Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT
-found in t/op/tie.t is much more maintainable, and gives better failure
-reports).
-
-=item *
-
-Give meaningful error messages when a test fails.
-
-=item *
-
-Avoid using qx// and system() unless you are testing for them. If you
-do use them, make sure that you cover _all_ perl platforms.
-
-=item *
-
-Unlink any temporary files you create.
-
-=item *
-
-Promote unforeseen warnings to errors with $SIG{__WARN__}.
-
-=item *
-
-Be sure to use the libraries and modules shipped with the version being
-tested, not those that were already installed.
-
-=item *
-
-Add comments to the code explaining what you are testing for.
-
-=item *
-
-Make updating the '1..42' string unnecessary. Or make sure that you
-update it.
-
-=item *
-
-Test _all_ behaviors of a given operator, library, or function.
-
-Test all optional arguments.
-
-Test return values in various contexts (boolean, scalar, list, lvalue).
-
-Use both global and lexical variables.
-
-Don't forget the exceptional, pathological cases.
-
-=back
-
-=head2 Patching a core module
-
-This works just like patching anything else, with one extra
-consideration.
-
-Modules in the F<cpan/> 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 L<http://search.cpan.org/> for more
-information on reporting bugs and submitting patches.
-
-In most cases, patches to modules in F<cpan/> should be sent upstream
-and should not be applied to the Perl core individually. If a patch to
-a file in F<cpan/> absolutely cannot wait for the fix to be made
-upstream, released to CPAN and copied to blead, you must add (or
-update) a C<CUSTOMIZED> entry in the F<"Porting/Maintainers.pl"> file
-to flag that a local modification has been made. See
-F<"Porting/Maintainers.pl"> for more details.
-
-In contrast, modules in the F<dist/> directory are maintained in the
-core.
-
-=head2 Updating perldelta
-
-For changes significant enough to warrant a F<pod/perldelta.pod> 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:
-
-=over 4
-
-=item *
-
-Adding, deprecating, or removing core features
-
-=item *
-
-Adding, deprecating, removing, or upgrading core or dual-life modules
-
-=item *
-
-Adding new core tests
-
-=item *
-
-Fixing security issues and user-visible bugs in the core
-
-=item *
-
-Changes that might break existing code, either on the perl or C level
-
-=item *
-
-Significant performance improvements
-
-=item *
-
-Adding, removing, or significantly changing documentation in the
-F<pod/> directory
-
-=item *
-
-Important platform-specific changes
-
-=back
-
-Please make sure you add the perldelta entry to the right section
-within F<pod/perldelta.pod>. More information on how to write good
-perldelta entries is available in the C<Style> section of
-F<Porting/how_to_write_a_perldelta.pod>.
-
-=head2 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:
-
-=head3 Does the concept match the general goals of Perl?
-
-Our goals include, but are not limited to:
-
-=over 4
-
-=item 1.
-
-Keep it fast, simple, and useful.
-
-=item 2.
-
-Keep features/concepts as orthogonal as possible.
-
-=item 3.
-
-No arbitrary limits (platforms, data sizes, cultures).
-
-=item 4.
-
-Keep it open and exciting to use/patch/advocate Perl everywhere.
-
-=item 5.
-
-Either assimilate new technologies, or build bridges to them.
-
-=back
-
-=head3 Where is the implementation?
-
-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.
-
-=head3 Backwards compatibility
-
-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.
-
-The Perl 5 core includes mechanisms to help porters make backwards
-incompatible changes more compatible such as the L<feature> and
-L<deprecate> modules. Please use them when appropriate.
-
-=head3 Could it be a module instead?
-
-Perl 5 has extension mechanisms, modules and XS, 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 XS code to
-mess with the runtime data structures of the Perl interpreter if you
-want to implement really complicated things.
-
-Whenever possible, new features should be prototyped in a CPAN module
-before they will be considered for the core.
-
-=head3 Is the feature generic enough?
-
-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.
-
-=head3 Does it potentially introduce new bugs?
-
-Radical rewrites of large chunks of the Perl interpreter have the
-potential to introduce new bugs.
-
-=head3 How big is it?
-
-The smaller and more localized the change, the better. Similarly, a
-series of small patches is greatly preferred over a single large patch.
-
-=head3 Does it preclude other desirable features?
-
-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.
-
-=head3 Is the implementation robust?
-
-Good patches (tight code, complete, correct) stand more chance of going
-in. Sloppy or incorrect patches might be placed on the back burner
-until the pumpking has time to fix, or might be discarded altogether
-without further notice.
-
-=head3 Is the implementation generic enough to be portable?
-
-The worst patches make use of system-specific features. It's highly
-unlikely that non-portable additions to the Perl language will be
-accepted.
-
-=head3 Is the implementation tested?
-
-Patches which change behaviour (fixing bugs or introducing new
-features) must include regression tests to verify that everything works
-as expected.
-
-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?
-
-=head3 Is there enough documentation?
-
-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.
-
-=head3 Is there another way to do it?
-
-Larry said "Although the Perl Slogan is I<There's More Than One Way to
-Do It>, 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.
-
-=head3 Does it create too much work?
-
-Work for the pumpking, work for Perl programmers, work for module
-authors, ... Perl is supposed to be easy.
-
-=head3 Patches speak louder than words
-
-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 "Will it be useful?", as the fact that
-someone took the time to make the patch demonstrates a strong desire
-for the feature.
-
-=head1 TESTING
-
-The core uses the same testing style as the rest of Perl, a simple
-"ok/not ok" run through Test::Harness, but there are a few special
-considerations.
-
-There are three ways to write a test in the core. L<Test::More>,
-F<t/test.pl> and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">. 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.
-
-The F<t/test.pl> library provides some of the features of
-L<Test::More>, but avoids loading most modules and uses as few core
-features as possible.
-
-If you write your own test, use the L<Test Anything
-Protocol|http://testanything.org>.
-
-=over 4
-
-=item * F<t/base> and F<t/comp>
-
-Since we don't know if require works, or even subroutines, use ad hoc
-tests for these two. Step carefully to avoid using the feature being
-tested.
-
-=item * F<t/cmd>, F<t/run>, F<t/io> and F<t/op>
-
-Now that basic require() and subroutines are tested, you can use the
-F<t/test.pl> library.
-
-You can also use certain libraries like Config conditionally, but be
-sure to skip the test gracefully if it's not there.
-
-=item * Everything else
-
-Now that the core of Perl is tested, L<Test::More> can and should be
-used. You can also use the full suite of core modules in the tests.
-
-=back
-
-When you say "make test", Perl uses the F<t/TEST> program to run the
-test suite (except under Win32 where it uses F<t/harness> instead). All
-tests are run from the F<t/> directory, B<not> the directory which
-contains the test. This causes some problems with the tests in F<lib/>,
-so here's some opportunity for some patching.
-
-You must be triply conscious of cross-platform concerns. This usually
-boils down to using L<File::Spec> and avoiding things like C<fork()>
-and C<system()> unless absolutely necessary.
-
-=head2 Special C<make test> targets
-
-There are various special make targets that can be used to test Perl
-slightly differently than the standard "test" 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.
-
-=over 4
-
-=item * test_porting
-
-This runs some basic sanity tests on the source tree and helps catch
-basic errors before you submit a patch.
-
-=item * coretest
-
-Run F<perl> on all core tests (F<t/*> and F<lib/[a-z]*> pragma tests).
-
-(Not available on Win32)
-
-=item * test.deparse
-
-Run all the tests through L<B::Deparse>. Not all tests will succeed.
-
-(Not available on Win32)
-
-=item * test.taintwarn
-
-Run all tests with the B<-t> command-line switch. Not all tests are
-expected to succeed (until they're specifically fixed, of course).
-
-(Not available on Win32)
-
-=item * minitest
-
-Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>,
-F<t/op>, F<t/uni> and F<t/mro> tests.
-
-=item * test.valgrind check.valgrind utest.valgrind ucheck.valgrind
-
-(Only in Linux) Run all the tests using the memory leak + naughty
-memory access tool "valgrind". The log files will be named
-F<testname.valgrind>.
-
-=item * test.torture torturetest
-
-Run all the usual tests and some extra tests. As of Perl 5.8.0, the
-only extra tests are Abigail's JAPHs, F<t/japh/abigail.t>.
-
-You can also run the torture test with F<t/harness> by giving
-C<-torture> argument to F<t/harness>.
-
-=item * utest ucheck test.utf8 check.utf8
-
-Run all the tests with -Mutf8. Not all tests will succeed.
-
-(Not available on Win32)
-
-=item * minitest.utf16 test.utf16
-
-Runs the tests with UTF-16 encoded scripts, encoded with different
-versions of this encoding.
-
-C<make utest.utf16> runs the test suite with a combination of C<-utf8>
-and C<-utf16> arguments to F<t/TEST>.
-
-(Not available on Win32)
-
-=item * test_harness
-
-Run the test suite with the F<t/harness> controlling program, instead
-of F<t/TEST>. F<t/harness> is more sophisticated, and uses the
-L<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 F<t/TEST>, it
-doesn't redirect stderr to stdout.
-
-Note that under Win32 F<t/harness> is always used instead of F<t/TEST>,
-so there is no special "test_harness" target.
-
-Under Win32's "test" target you may use the TEST_SWITCHES and
-TEST_FILES environment variables to control the behaviour of
-F<t/harness>. This means you can say
-
- nmake test TEST_FILES="op/*.t"
- nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t"
-
-=item * test-notty test_notty
-
-Sets PERL_SKIP_TTY_TEST to true before running normal test.
-
-=back
-
-=head2 Parallel tests
-
-The core distribution can now run its regression tests in parallel on
-Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS>
-in your environment to the number of tests to run in parallel, and run
-C<make test_harness>. On a Bourne-like shell, this can be done as
-
- TEST_JOBS=3 make test_harness # Run 3 tests in parallel
-
-An environment variable is used, rather than parallel make itself,
-because L<TAP::Harness> needs to be able to schedule individual
-non-conflicting test scripts itself, and there is no standard interface
-to C<make> utilities to interact with their job schedulers.
-
-Note that currently some test scripts may fail when run in parallel
-(most notably F<ext/IO/t/io_dir.t>). If necessary, run just the failing
-scripts again sequentially and see if the failures go away.
-
-=head2 Running tests by hand
-
-You can run part of the test suite by hand by using one of the
-following commands from the F<t/> directory:
-
- ./perl -I../lib TEST list-of-.t-files
-
-or
-
- ./perl -I../lib harness list-of-.t-files
-
-(If you don't specify test scripts, the whole test suite will be run.)
-
-=head2 Using F<t/harness> for testing
-
-If you use C<harness> 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.
-
- harness -v -torture -re=pattern LIST OF FILES TO TEST
- harness -v -torture -re LIST OF PATTERNS TO MATCH
-
-If C<LIST OF FILES TO TEST> is omitted, the file list is obtained from
-the manifest. The file list may include shell wildcards which will be
-expanded out.
-
-=over 4
-
-=item * -v
-
-Run the tests under verbose mode so you can see what tests were run,
-and debug output.
-
-=item * -torture
-
-Run the torture tests as well as the normal set.
-
-=item * -re=PATTERN
-
-Filter the file list so that all the test files run match PATTERN. Note
-that this form is distinct from the B<-re LIST OF PATTERNS> form below
-in that it allows the file list to be provided as well.
-
-=item * -re LIST OF PATTERNS
-
-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 MANIFEST.
-
-=back
-
-You can run an individual test by a command similar to
-
- ./perl -I../lib path/to/foo.t
-
-except that the harnesses set up some environment variables that may
-affect the execution of the test:
-
-=over 4
-
-=item * PERL_CORE=1
-
-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 CPAN.
-
-=item * PERL_DESTRUCT_LEVEL=2
-
-is set to 2 if it isn't set already (see
-L<perlhacktips/PERL_DESTRUCT_LEVEL>).
-
-=item * PERL
-
-(used only by F<t/TEST>) if set, overrides the path to the perl
-executable that should be used to run the tests (the default being
-F<./perl>).
-
-=item * PERL_SKIP_TTY_TEST
-
-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'.
-
-=back
-
-=head3 Other environment variables that may influence tests
-
-=over 4
-
-=item * PERL_TEST_Net_Ping
-
-Setting this variable runs all the Net::Ping modules tests, otherwise
-some tests that interact with the outside world are skipped. See
-L<perl58delta>.
-
-=item * PERL_TEST_NOVREXX
-
-Setting this variable skips the vrexx.t tests for OS2::REXX.
-
-=item * PERL_TEST_NUMCONVERTS
-
-This sets a variable in op/numconvert.t.
-
-=back
-
-See also the documentation for the Test and Test::Harness modules, for
-more environment variables that affect testing.
-
-=head1 MORE READING FOR GUTS HACKERS
-
-To hack on the Perl guts, you'll need to read the following things:
-
-=over 4
-
-=item * L<perlsource>
-
-An overview of the Perl source tree. This will help you find the files
-you're looking for.
-
-=item * L<perlinterp>
-
-An overview of the Perl interpreter source code and some details on how
-Perl does what it does.
-
-=item * L<perlhacktut>
-
-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.
-
-=item * L<perlhacktips>
-
-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.
-
-If you plan on doing serious C hacking, make sure to read this.
-
-=item * L<perlguts>
-
-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.
-
-Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very
-helpful pictures:
-
-L<http://search.cpan.org/dist/illguts/>
-
-=item * L<perlxstut> and L<perlxs>
-
-A working knowledge of XSUB programming is incredibly useful for core
-hacking; XSUBs use techniques drawn from the PP 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.
-
-=item * L<perlapi>
-
-The documentation for the Perl API explains what some of the internal
-functions do, as well as the many macros used in the source.
-
-=item * F<Porting/pumpkin.pod>
-
-This is a collection of words of wisdom for a Perl porter; some of it
-is only useful to the pumpkin holder, but most of it applies to anyone
-wanting to go about Perl development.
-
-=item * The perl5-porters FAQ
-
-This should be available from
-http://dev.perl.org/perl5/docs/p5p-faq.html . It contains hints on
-reading perl5-porters, information on how perl5-porters works and how
-Perl development in general works.
-
-=back
-
-=head1 CPAN TESTERS AND PERL SMOKERS
-
-The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers
-who test CPAN modules on a variety of platforms.
-
-Perl Smokers ( http://www.nntp.perl.org/group/perl.daily-build/ and
-http://www.nntp.perl.org/group/perl.daily-build.reports/ )
-automatically test Perl source releases on platforms with various
-configurations.
-
-Both efforts welcome volunteers. In order to get involved in smoke
-testing of the perl itself visit
-L<http://search.cpan.org/dist/Test-Smoke/>. In order to start smoke
-testing CPAN modules visit
-L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or
-L<http://search.cpan.org/dist/minismokebox/> or
-L<http://search.cpan.org/dist/CPAN-Reporter/>.
-
-=head1 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.
-
-Here's some more recommendations
-
-=over 4
-
-=item *
-
-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...
-
-=item *
-
-Do read the README associated with your operating system, e.g.
-README.aix on the IBM AIX OS. Don't hesitate to supply patches to that
-README if you find anything missing or changed over a new OS release.
-
-=item *
-
-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
-F<perl>'s activity as well, and probably sooner than you'd think.
-
-=back
-
-=head2 "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!
-
-=head2 Metaphoric Quotations
-
-If you recognized the quote about the Road above, you're in luck.
-
-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.
-
-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.
-
-Quotations are taken from writings of J.R.R. Tolkien pertaining to his
-Legendarium, almost always from I<The Lord of the Rings>. Chapters and
-page numbers are given using the following editions:
-
-=over 4
-
-=item *
-
-I<The Hobbit>, by J.R.R. Tolkien. The hardcover, 70th-anniversary
-edition of 2007 was used, published in the UK by Harper Collins
-Publishers and in the US by the Houghton Mifflin Company.
-
-=item *
-
-I<The Lord of the Rings>, by J.R.R. Tolkien. The hardcover,
-50th-anniversary edition of 2004 was used, published in the UK by
-Harper Collins Publishers and in the US by the Houghton Mifflin
-Company.
-
-=item *
-
-I<The Lays of Beleriand>, 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 I<History of Middle Earth>. 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.
-
-=back
-
-Other JRRT books fair game for quotes would thus include I<The
-Adventures of Tom Bombadil>, I<The Silmarillion>, I<Unfinished Tales>,
-and I<The Tale of the Children of Hurin>, all but the first
-posthumously assembled by CJRT. But I<The Lord of the Rings> itself is
-perfectly fine and probably best to quote from, provided you can find a
-suitable quote there.
-
-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.
-
-=head1 AUTHOR
-
-This document was originally written by Nathan Torkington, and is
-maintained by the perl5-porters mailing list.
-