=item * Commit your change
-Commiting your work will save the change I<on your local system>:
+Committing your work will save the change I<on your local system>:
% git commit -a -m 'Commit message goes here'
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, you can send it to
-perlbug with this command line:
+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 HEAD^1..HEAD
- % perlbug -s '[PATCH] `git log --pretty=format:%s HEAD^1..HEAD`' -f 0001-*.patch
+ % 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 you
-can submit your patch.
+address and the patch you're submitting. Once you've answered them it
+will submit your patch via email.
=item * Thank you
=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.
+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>.
+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
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", or just the "porters".
+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
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
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>
+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 .
+ % 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)
+(Add the C<--delete> option to remove leftover files.)
To get a full list of the available sync points:
- $ rsync perl5.git.perl.org::
+ % rsync perl5.git.perl.org::
=head2 Write access via git
made. If you prefer to send a single patch for all commits, you can use
C<git diff>.
- % git co blead
+ % git checkout blead
% git pull
% git diff blead my-branch-name
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
-E-Mail, 50 characters being a good rule of thumb.
+email, 50 characters being a good rule of thumb.
-A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ..) will
+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.
"if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
+=item *
+
+Do not declare variables using "register". It may be counterproductive
+with modern compilers, and is deprecated in C++, under which the Perl
+source is regularly compiled.
+
+=item *
+
+In-line functions that are in headers that are accessible to XS code
+need to be able to compile without warnings with commonly used extra
+compilation flags, such as gcc's C<-Wswitch-default> which warns
+whenever a switch statement does not have a "default" 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.
+
=back
=head3 Test suite
-If your patch changes code (rather than just changing documentation)
+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
This works just like patching anything else, with one extra
consideration.
-Some core modules also live on CPAN and are maintained outside of the
-Perl core. When the author updates the module, the updates are simply
-copied into the core.
+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.
-Module in the F<cpan/> directory of the source tree are maintained
-outside of the Perl core. See that module's listing on 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.
=head3 Is the implementation generic enough to be portable?
-The worst patches make use of a system-specific features. It's highly
+The worst patches make use of system-specific features. It's highly
unlikely that non-portable additions to the Perl language will be
accepted.
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|TAP>.
+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>
+=item * F<t/base>, F<t/comp> and F<t/opbasic>
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.
+tests for these three. Step carefully to avoid using the feature being
+tested. Tests in F<t/opbasic>, for instance, have been placed there rather
+than in F<t/op> because they test functionality which F<t/test.pl> presumes
+has already been demonstrated to work.
-=item * F<t/cmd>, F<t/run> F<t/io>, and F<t/op>
+=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
+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
=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
+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.
=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>.
+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>.
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
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 C<ext/IO/t/io_dir.t>). If necessary run just the failing scripts
-again sequentially and see if the failures go away.
-=item * test-notty test_notty
-
-Sets PERL_SKIP_TTY_TEST to true before running normal test.
+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 the following
-commands from the F<t/> directory :
+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
./perl -I../lib harness list-of-.t-files
-(if you don't specify test scripts, the whole test suite will be run.)
+(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.
+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
+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.
You can run an individual test by a command similar to
- ./perl -I../lib patho/to/foo.t
+ ./perl -I../lib path/to/foo.t
except that the harnesses set up some environment variables that may
affect the execution of the test:
=item * PERL_CORE=1
-indicates that we're running this test part of the perl core test
+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>)
+L<perlhacktips/PERL_DESTRUCT_LEVEL>).
=item * PERL
This sets a variable in op/numconvert.t.
+=item * PERL_TEST_MEMORY
+
+Setting this variable includes the tests in F<t/bigmem/>. This should
+be set to the number of gigabytes of memory available for testing,
+eg. C<PERL_TEST_MEMORY=4> indicates that tests that require 4GiB of
+available memory can be run safely.
+
=back
See also the documentation for the Test and Test::Harness modules, for
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
+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
+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
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 epigramic inscription
-that alludes, indirectly and metaphorically, to the material you're
-about to read.
+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
+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:
https://perl5.git.perl.org / perl5.git / blobdiff