This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
When and how to use Devel::PatchPerl to repair older builds.
[perl5.git] / pod / perlhack.pod
CommitLineData
04c692a8 1=encoding utf8
35c336e6 2
04c692a8
DR
3=for comment
4Consistent formatting of this file is achieved with:
5 perl ./Porting/podtidy pod/perlhack.pod
35c336e6 6
04c692a8 7=head1 NAME
35c336e6 8
04c692a8 9perlhack - How to hack on Perl
35c336e6 10
04c692a8 11=head1 DESCRIPTION
35c336e6 12
531e2078 13This document explains how Perl development works. It includes details
04c692a8
DR
14about the Perl 5 Porters email list, the Perl repository, the Perlbug
15bug tracker, patch guidelines, and commentary on Perl development
16philosophy.
f7e1e956 17
04c692a8 18=head1 SUPER QUICK PATCH GUIDE
f7e1e956 19
04c692a8
DR
20If you just want to submit a single small patch like a pod fix, a test
21for a bug, comment fixes, etc., it's easy! Here's how:
f7e1e956 22
04c692a8 23=over 4
e018f8be 24
04c692a8 25=item * Check out the source repository
e018f8be 26
531e2078 27The perl source is in a git repository. You can clone the repository
04c692a8 28with the following command:
e018f8be 29
04c692a8 30 % git clone git://perl5.git.perl.org/perl.git perl
e018f8be 31
69434957
S
32=item * Ensure you're following the latest advice
33
34In case the advice in this guide has been updated recently, read the
35latest version directly from the perl source:
36
37 % perldoc pod/perlhack.pod
38
04c692a8 39=item * Make your change
e018f8be 40
eb9df707
KW
41Hack, hack, hack. Keep in mind that Perl runs on many different
42platforms, with different operating systems that have different
43capabilities, different filesystem organizations, and even different
44character sets. L<perlhacktips> gives advice on this.
7205a85d 45
04c692a8 46=item * Test your change
e018f8be 47
04c692a8 48You can run all the tests with the following commands:
b26492ee 49
04c692a8
DR
50 % ./Configure -des -Dusedevel
51 % make test
7205a85d 52
04c692a8 53Keep hacking until the tests pass.
b26492ee 54
04c692a8 55=item * Commit your change
e018f8be 56
b6538e4f 57Committing your work will save the change I<on your local system>:
7205a85d 58
04c692a8 59 % git commit -a -m 'Commit message goes here'
e018f8be 60
04c692a8 61Make sure the commit message describes your change in a single
531e2078 62sentence. For example, "Fixed spelling errors in perlhack.pod".
e018f8be 63
04c692a8 64=item * Send your change to perlbug
7a834142 65
04c692a8
DR
66The next step is to submit your patch to the Perl core ticket system
67via email.
7a834142 68
84788b0a 69If your changes are in a single git commit, run the following commands
e7769b3e 70to generate the patch file and attach it to your bug report:
e018f8be 71
e7769b3e
CB
72 % git format-patch -1
73 % ./perl -Ilib utils/perlbug -p 0001-*.patch
e018f8be 74
04c692a8 75The perlbug program will ask you a few questions about your email
531e2078 76address and the patch you're submitting. Once you've answered them it
84b19098 77will submit your patch via email.
e018f8be 78
e7769b3e
CB
79If your changes are in multiple commits, generate a patch file for each
80one and provide them to perlbug's C<-p> option separated by commas:
2d1c9392 81
e7769b3e
CB
82 % git format-patch -3
83 % ./perl -Ilib utils/perlbug -p 0001-fix1.patch,0002-fix2.patch,\
84 > 0003-fix3.patch
2d1c9392 85
e7769b3e 86When prompted, pick a subject that summarizes your changes.
2d1c9392 87
04c692a8 88=item * Thank you
e018f8be 89
04c692a8
DR
90The porters appreciate the time you spent helping to make Perl better.
91Thank you!
e018f8be 92
e99cf3f0
S
93=item * Next time
94
95The next time you wish to make a patch, you need to start from the
30454452 96latest perl in a pristine state. Check you don't have any local changes
e99cf3f0
S
97or added files in your perl check-out which you wish to keep, then run
98these commands:
99
100 % git pull
101 % git reset --hard origin/blead
102 % git clean -dxf
103
cce04beb 104=back
e018f8be 105
04c692a8 106=head1 BUG REPORTING
cc0710ff 107
9e6670f3 108If you want to report a bug in Perl, you must use the F<perlbug>
531e2078 109command line tool. This tool will ensure that your bug report includes
9e6670f3 110all the relevant system and configuration information.
7205a85d 111
04c692a8 112To browse existing Perl bugs and patches, you can use the web interface
a8d15a22 113at L<http://rt.perl.org/>.
244d9cb7 114
04c692a8 115Please check the archive of the perl5-porters list (see below) and/or
531e2078 116the bug tracking system before submitting a bug report. Often, you'll
04c692a8 117find that the bug has been reported already.
244d9cb7 118
04c692a8 119You can log in to the bug tracking system and comment on existing bug
531e2078
FC
120reports. If you have additional information regarding an existing bug,
121please add it. This will help the porters fix the bug.
7205a85d 122
04c692a8 123=head1 PERL 5 PORTERS
7205a85d 124
04c692a8 125The perl5-porters (p5p) mailing list is where the Perl standard
531e2078 126distribution is maintained and developed. The people who maintain Perl
9e6670f3
DR
127are also referred to as the "Perl 5 Porters", "p5p" or just the
128"porters".
a75f557c 129
04c692a8 130A searchable archive of the list is available at
586e992d 131L<http://markmail.org/search/?q=perl5-porters>. There is also an archive at
04c692a8 132L<http://archive.develooper.com/perl5-porters@perl.org/>.
7205a85d 133
04c692a8 134=head2 perl-changes mailing list
7205a85d 135
04c692a8
DR
136The perl5-changes mailing list receives a copy of each patch that gets
137submitted to the maintenance and development branches of the perl
531e2078 138repository. See L<http://lists.perl.org/list/perl5-changes.html> for
04c692a8 139subscription and archive information.
244d9cb7 140
37bf3a91
DR
141=head2 #p5p on IRC
142
143Many porters are also active on the L<irc://irc.perl.org/#p5p> channel.
144Feel free to join the channel and ask questions about hacking on the
145Perl core.
146
04c692a8 147=head1 GETTING THE PERL SOURCE
244d9cb7 148
04c692a8 149All of Perl's source code is kept centrally in a Git repository at
a44b8c28
S
150I<perl5.git.perl.org>. The repository contains many Perl revisions
151from Perl 1 onwards and all the revisions from Perforce, the previous
04c692a8 152version control system.
244d9cb7 153
04c692a8
DR
154For much more detail on using git with the Perl repository, please see
155L<perlgit>.
244d9cb7 156
04c692a8 157=head2 Read access via Git
244d9cb7 158
531e2078 159You will need a copy of Git for your computer. You can fetch a copy of
04c692a8 160the repository using the git protocol:
244d9cb7 161
04c692a8 162 % git clone git://perl5.git.perl.org/perl.git perl
244d9cb7 163
04c692a8
DR
164This clones the repository and makes a local copy in the F<perl>
165directory.
7205a85d 166
04c692a8
DR
167If you cannot use the git protocol for firewall reasons, you can also
168clone via http, though this is much slower:
7205a85d 169
04c692a8 170 % git clone http://perl5.git.perl.org/perl.git perl
7205a85d 171
04c692a8 172=head2 Read access via the web
7205a85d 173
531e2078 174You may access the repository over the web. This allows you to browse
04c692a8 175the tree, see recent commits, subscribe to RSS feeds for the changes,
531e2078
FC
176search for particular commits and more. You may access it at
177L<http://perl5.git.perl.org/perl.git>. A mirror of the repository is
b0959619 178found at L<https://github.com/Perl/perl5>.
7205a85d 179
04c692a8 180=head2 Read access via rsync
7205a85d 181
04c692a8
DR
182You can also choose to use rsync to get a copy of the current source
183tree for the bleadperl branch and all maintenance branches:
7205a85d 184
7eac65da
S
185 % rsync -avz rsync://perl5.git.perl.org/perl-current .
186 % rsync -avz rsync://perl5.git.perl.org/perl-5.12.x .
187 % rsync -avz rsync://perl5.git.perl.org/perl-5.10.x .
188 % rsync -avz rsync://perl5.git.perl.org/perl-5.8.x .
189 % rsync -avz rsync://perl5.git.perl.org/perl-5.6.x .
190 % rsync -avz rsync://perl5.git.perl.org/perl-5.005xx .
7205a85d 191
a8d15a22 192(Add the C<--delete> option to remove leftover files.)
7205a85d 193
04c692a8 194To get a full list of the available sync points:
7205a85d 195
7eac65da 196 % rsync perl5.git.perl.org::
7205a85d 197
04c692a8 198=head2 Write access via git
7205a85d 199
04c692a8
DR
200If you have a commit bit, please see L<perlgit> for more details on
201using git.
7205a85d 202
04c692a8 203=head1 PATCHING PERL
7205a85d 204
04c692a8 205If you're planning to do more extensive work than a single small fix,
531e2078 206we encourage you to read the documentation below. This will help you
04c692a8
DR
207focus your work and make your patches easier to incorporate into the
208Perl source.
244d9cb7 209
04c692a8 210=head2 Submitting patches
244d9cb7 211
531e2078
FC
212If you have a small patch to submit, please submit it via perlbug. You
213can also send email directly to perlbug@perl.org. Please note that
04c692a8
DR
214messages sent to perlbug may be held in a moderation queue, so you
215won't receive a response immediately.
244d9cb7 216
04c692a8 217You'll know your submission has been processed when you receive an
531e2078
FC
218email from our ticket tracking system. This email will give you a
219ticket number. Once your patch has made it to the ticket tracking
04c692a8 220system, it will also be sent to the perl5-porters@perl.org list.
244d9cb7 221
531e2078 222Patches are reviewed and discussed on the p5p list. Simple,
04c692a8
DR
223uncontroversial patches will usually be applied without any discussion.
224When the patch is applied, the ticket will be updated and you will
531e2078 225receive email. In addition, an email will be sent to the p5p list.
244d9cb7 226
531e2078 227In other cases, the patch will need more work or discussion. That will
04c692a8 228happen on the p5p list.
244d9cb7 229
04c692a8 230You are encouraged to participate in the discussion and advocate for
531e2078 231your patch. Sometimes your patch may get lost in the shuffle. It's
04c692a8 232appropriate to send a reminder email to p5p if no action has been taken
531e2078 233in a month. Please remember that the Perl 5 developers are all
04c692a8 234volunteers, and be polite.
244d9cb7 235
04c692a8 236Changes are always applied directly to the main development branch,
a44b8c28 237called "blead". Some patches may be backported to a maintenance
30454452 238branch. If you think your patch is appropriate for the maintenance
839a0e5a 239branch (see L<perlpolicy/MAINTENANCE BRANCHES>), please explain why
d0bba22e 240when you submit it.
244d9cb7 241
04c692a8 242=head2 Getting your patch accepted
244d9cb7 243
84c2f6fd
DR
244If you are submitting a code patch there are several things that you
245can do to help the Perl 5 Porters accept your patch.
244d9cb7 246
a126fb62
DR
247=head3 Patch style
248
249If you used git to check out the Perl source, then using C<git
531e2078 250format-patch> will produce a patch in a style suitable for Perl. The
a126fb62 251C<format-patch> command produces one patch file for each commit you
a44b8c28
S
252made. If you prefer to send a single patch for all commits, you can
253use C<git diff>.
a126fb62 254
9d440a18 255 % git checkout blead
a126fb62
DR
256 % git pull
257 % git diff blead my-branch-name
258
259This produces a patch based on the difference between blead and your
531e2078 260current branch. It's important to make sure that blead is up to date
a126fb62
DR
261before producing the diff, that's why we call C<git pull> first.
262
531e2078 263We strongly recommend that you use git if possible. It will make your
a126fb62
DR
264life easier, and ours as well.
265
266However, if you're not using git, you can still produce a suitable
531e2078
FC
267patch. You'll need a pristine copy of the Perl source to diff against.
268The porters prefer unified diffs. Using GNU C<diff>, you can produce a
a126fb62
DR
269diff like this:
270
271 % diff -Npurd perl.pristine perl.mine
272
273Make sure that you C<make realclean> in your copy of Perl to remove any
274build artifacts, or you may get a confusing result.
275
04c692a8 276=head3 Commit message
244d9cb7 277
04c692a8 278As you craft each patch you intend to submit to the Perl core, it's
531e2078 279important to write a good commit message. This is especially important
04c692a8 280if your submission will consist of a series of commits.
244d9cb7 281
04c692a8 282The first line of the commit message should be a short description
531e2078 283without a period. It should be no longer than the subject line of an
a8d15a22 284email, 50 characters being a good rule of thumb.
f7e1e956 285
a8d15a22 286A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will
04c692a8
DR
287only display the first line (cut off at 50 characters) when presenting
288commit summaries.
7cd58830 289
04c692a8
DR
290The commit message should include a description of the problem that the
291patch corrects or new functionality that the patch adds.
7cd58830 292
04c692a8
DR
293As a general rule of thumb, your commit message should help a
294programmer who knows the Perl core quickly understand what you were
295trying to do, how you were trying to do it, and why the change matters
296to Perl.
7cd58830 297
04c692a8 298=over 4
7cd58830 299
04c692a8 300=item * Why
7cd58830 301
04c692a8 302Your commit message should describe why the change you are making is
531e2078 303important. When someone looks at your change in six months or six
04c692a8 304years, your intent should be clear.
7cd58830 305
04c692a8 306If you're deprecating a feature with the intent of later simplifying
531e2078 307another bit of code, say so. If you're fixing a performance problem or
04c692a8
DR
308adding a new feature to support some other bit of the core, mention
309that.
7cd58830 310
04c692a8 311=item * What
7cd58830 312
04c692a8
DR
313Your commit message should describe what part of the Perl core you're
314changing and what you expect your patch to do.
7cd58830 315
04c692a8 316=item * How
7cd58830 317
04c692a8
DR
318While it's not necessary for documentation changes, new tests or
319trivial patches, it's often worth explaining how your change works.
320Even if it's clear to you today, it may not be clear to a porter next
321month or next year.
d7889f52 322
04c692a8 323=back
d7889f52 324
04c692a8 325A commit message isn't intended to take the place of comments in your
531e2078 326code. Commit messages should describe the change you made, while code
04c692a8 327comments should describe the current state of the code.
d7889f52 328
04c692a8 329If you've just implemented a new feature, complete with doc, tests and
531e2078 330well-commented code, a brief commit message will often suffice. If,
04c692a8
DR
331however, you've just changed a single character deep in the parser or
332lexer, you might need to write a small novel to ensure that future
333readers understand what you did and why you did it.
d7889f52 334
04c692a8 335=head3 Comments, Comments, Comments
d7889f52 336
a44b8c28
S
337Be sure to adequately comment your code. While commenting every line
338is unnecessary, anything that takes advantage of side effects of
04c692a8
DR
339operators, that creates changes that will be felt outside of the
340function being patched, or that others may find confusing should be
a44b8c28
S
341documented. If you are going to err, it is better to err on the side
342of adding too many comments than too few.
d7889f52 343
04c692a8
DR
344The best comments explain I<why> the code does what it does, not I<what
345it does>.
d7889f52 346
04c692a8 347=head3 Style
d7889f52 348
04c692a8
DR
349In general, please follow the particular style of the code you are
350patching.
d7889f52 351
04c692a8
DR
352In particular, follow these general guidelines for patching Perl
353sources:
cce04beb 354
04c692a8 355=over 4
d7889f52
JH
356
357=item *
358
0529658c
AL
3594-wide indents for code, 2-wide indents for nested CPP C<#define>s,
360with 8-wide tabstops.
d7889f52
JH
361
362=item *
363
0529658c
AL
364Use spaces for indentation, not tab characters.
365
366The codebase is a mixture of tabs and spaces for indentation, and we
367are moving to spaces only. Converting lines you're patching from 8-wide
368tabs to spaces will help this migration.
ee9468a2 369
cce04beb 370=item *
ee9468a2 371
04c692a8 372Try hard not to exceed 79-columns
bc028b6b 373
ee9468a2
RGS
374=item *
375
04c692a8 376ANSI C prototypes
d7889f52
JH
377
378=item *
379
04c692a8 380Uncuddled elses and "K&R" style for indenting control constructs
0bec6c03 381
04c692a8 382=item *
d7889f52 383
04c692a8 384No C++ style (//) comments
d7889f52
JH
385
386=item *
387
04c692a8 388Mark places that need to be revisited with XXX (and revisit often!)
27565cb6
JH
389
390=item *
391
04c692a8
DR
392Opening brace lines up with "if" when conditional spans multiple lines;
393should be at end-of-line otherwise
27565cb6 394
04c692a8 395=item *
27565cb6 396
15c526cb 397In function definitions, name starts in column 0 (return value-type is on
04c692a8 398previous line)
27565cb6 399
04c692a8 400=item *
27565cb6 401
04c692a8
DR
402Single space after keywords that are followed by parens, no space
403between function name and following paren
606fd33d 404
27565cb6
JH
405=item *
406
04c692a8
DR
407Avoid assignments in conditionals, but if they're unavoidable, use
408extra paren, e.g. "if (a && (b = c)) ..."
27565cb6
JH
409
410=item *
411
04c692a8 412"return foo;" rather than "return(foo);"
27565cb6
JH
413
414=item *
415
04c692a8 416"if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
606fd33d 417
a8bd0d47
KW
418=item *
419
420Do not declare variables using "register". It may be counterproductive
421with modern compilers, and is deprecated in C++, under which the Perl
422source is regularly compiled.
423
5b48d9bb
KW
424=item *
425
426In-line functions that are in headers that are accessible to XS code
427need to be able to compile without warnings with commonly used extra
428compilation flags, such as gcc's C<-Wswitch-default> which warns
429whenever a switch statement does not have a "default" case. The use of
a44b8c28
S
430these extra flags is to catch potential problems in legal C code, and
431is often used by Perl aggregators, such as Linux distributors.
5b48d9bb 432
606fd33d 433=back
27565cb6 434
04c692a8 435=head3 Test suite
d7889f52 436
a8d15a22 437If your patch changes code (rather than just changing documentation),
04c692a8 438you should also include one or more test cases which illustrate the bug
531e2078 439you're fixing or validate the new functionality you're adding. In
04c692a8
DR
440general, you should update an existing test file rather than create a
441new one.
2bbc8d55 442
04c692a8
DR
443Your test suite additions should generally follow these guidelines
444(courtesy of Gurusamy Sarathy <gsar@activestate.com>):
2bbc8d55 445
04c692a8 446=over 4
0bec6c03 447
04c692a8 448=item *
0bec6c03 449
531e2078 450Know what you're testing. Read the docs, and the source.
ee9468a2
RGS
451
452=item *
453
04c692a8 454Tend to fail, not succeed.
0bec6c03 455
04c692a8 456=item *
0bec6c03 457
04c692a8 458Interpret results strictly.
27565cb6 459
04c692a8 460=item *
27565cb6 461
04c692a8 462Use unrelated features (this will flush out bizarre interactions).
27565cb6 463
04c692a8 464=item *
27565cb6 465
04c692a8 466Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
27565cb6 467
04c692a8 468=item *
d7889f52 469
04c692a8
DR
470Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT
471found in t/op/tie.t is much more maintainable, and gives better failure
472reports).
d7889f52 473
04c692a8 474=item *
d7889f52 475
04c692a8 476Give meaningful error messages when a test fails.
d7889f52 477
04c692a8 478=item *
d7889f52 479
531e2078 480Avoid using qx// and system() unless you are testing for them. If you
04c692a8 481do use them, make sure that you cover _all_ perl platforms.
d7889f52 482
04c692a8 483=item *
0bec6c03 484
04c692a8 485Unlink any temporary files you create.
63796a85 486
04c692a8 487=item *
0bec6c03 488
04c692a8 489Promote unforeseen warnings to errors with $SIG{__WARN__}.
0bec6c03 490
04c692a8 491=item *
0bec6c03 492
04c692a8
DR
493Be sure to use the libraries and modules shipped with the version being
494tested, not those that were already installed.
d7889f52 495
04c692a8 496=item *
d7889f52 497
04c692a8 498Add comments to the code explaining what you are testing for.
d7889f52 499
04c692a8 500=item *
d7889f52 501
531e2078 502Make updating the '1..42' string unnecessary. Or make sure that you
04c692a8 503update it.
d7889f52 504
04c692a8 505=item *
d7889f52 506
04c692a8 507Test _all_ behaviors of a given operator, library, or function.
d7889f52 508
04c692a8 509Test all optional arguments.
d7889f52 510
04c692a8 511Test return values in various contexts (boolean, scalar, list, lvalue).
d7889f52 512
04c692a8 513Use both global and lexical variables.
d7889f52 514
04c692a8 515Don't forget the exceptional, pathological cases.
0bec6c03 516
cce04beb 517=back
0bec6c03 518
04c692a8 519=head2 Patching a core module
ee9468a2 520
04c692a8
DR
521This works just like patching anything else, with one extra
522consideration.
63796a85 523
a8d15a22 524Modules in the F<cpan/> directory of the source tree are maintained
531e2078 525outside of the Perl core. When the author updates the module, the
24b68a05
DG
526updates are simply copied into the core. See that module's
527documentation or its listing on L<http://search.cpan.org/> for more
528information on reporting bugs and submitting patches.
529
530In most cases, patches to modules in F<cpan/> should be sent upstream
9e6670f3
DR
531and should not be applied to the Perl core individually. If a patch to
532a file in F<cpan/> absolutely cannot wait for the fix to be made
7e5887a1
DG
533upstream, released to CPAN and copied to blead, you must add (or
534update) a C<CUSTOMIZED> entry in the F<"Porting/Maintainers.pl"> file
535to flag that a local modification has been made. See
536F<"Porting/Maintainers.pl"> for more details.
63796a85 537
04c692a8
DR
538In contrast, modules in the F<dist/> directory are maintained in the
539core.
63796a85 540
04c692a8 541=head2 Updating perldelta
63796a85 542
04c692a8
DR
543For changes significant enough to warrant a F<pod/perldelta.pod> entry,
544the porters will greatly appreciate it if you submit a delta entry
a44b8c28
S
545along with your actual change. Significant changes include, but are
546not limited to:
63796a85 547
04c692a8 548=over 4
63796a85 549
04c692a8 550=item *
63796a85 551
04c692a8 552Adding, deprecating, or removing core features
ee9468a2 553
04c692a8 554=item *
ee9468a2 555
04c692a8 556Adding, deprecating, removing, or upgrading core or dual-life modules
ee9468a2 557
04c692a8 558=item *
ee9468a2 559
04c692a8 560Adding new core tests
ee9468a2 561
04c692a8 562=item *
ee9468a2 563
04c692a8 564Fixing security issues and user-visible bugs in the core
cce04beb 565
04c692a8 566=item *
ad7244db 567
04c692a8 568Changes that might break existing code, either on the perl or C level
ad7244db
JH
569
570=item *
571
04c692a8 572Significant performance improvements
ad7244db
JH
573
574=item *
575
04c692a8
DR
576Adding, removing, or significantly changing documentation in the
577F<pod/> directory
ad7244db 578
cce04beb 579=item *
ad7244db 580
04c692a8 581Important platform-specific changes
d7889f52 582
cce04beb
DG
583=back
584
04c692a8 585Please make sure you add the perldelta entry to the right section
531e2078 586within F<pod/perldelta.pod>. More information on how to write good
04c692a8
DR
587perldelta entries is available in the C<Style> section of
588F<Porting/how_to_write_a_perldelta.pod>.
d7889f52 589
04c692a8 590=head2 What makes for a good patch?
d7889f52 591
531e2078 592New features and extensions to the language can be contentious. There
04c692a8
DR
593is no specific set of criteria which determine what features get added,
594but here are some questions to consider when developing a patch:
d7889f52 595
04c692a8 596=head3 Does the concept match the general goals of Perl?
d7889f52 597
04c692a8 598Our goals include, but are not limited to:
d7889f52 599
04c692a8 600=over 4
d7889f52 601
04c692a8 602=item 1.
d7889f52 603
04c692a8 604Keep it fast, simple, and useful.
cce04beb 605
04c692a8 606=item 2.
cce04beb 607
04c692a8 608Keep features/concepts as orthogonal as possible.
902b9dbf 609
04c692a8 610=item 3.
902b9dbf 611
04c692a8 612No arbitrary limits (platforms, data sizes, cultures).
a958818a 613
04c692a8 614=item 4.
ac036724 615
04c692a8 616Keep it open and exciting to use/patch/advocate Perl everywhere.
a958818a 617
04c692a8 618=item 5.
a958818a 619
04c692a8 620Either assimilate new technologies, or build bridges to them.
a958818a 621
04c692a8 622=back
a958818a 623
04c692a8 624=head3 Where is the implementation?
a958818a 625
531e2078 626All the talk in the world is useless without an implementation. In
04c692a8 627almost every case, the person or people who argue for a new feature
531e2078 628will be expected to be the ones who implement it. Porters capable of
04c692a8
DR
629coding new features have their own agendas, and are not available to
630implement your (possibly good) idea.
a1b65709 631
04c692a8 632=head3 Backwards compatibility
37c0adeb 633
531e2078 634It's a cardinal sin to break existing Perl programs. New warnings can
04c692a8 635be contentious--some say that a program that emits warnings is not
531e2078 636broken, while others say it is. Adding keywords has the potential to
04c692a8
DR
637break programs, changing the meaning of existing token sequences or
638functions might break programs.
f50e5b73 639
04c692a8
DR
640The Perl 5 core includes mechanisms to help porters make backwards
641incompatible changes more compatible such as the L<feature> and
531e2078 642L<deprecate> modules. Please use them when appropriate.
902b9dbf 643
04c692a8 644=head3 Could it be a module instead?
902b9dbf 645
04c692a8 646Perl 5 has extension mechanisms, modules and XS, specifically to avoid
531e2078 647the need to keep changing the Perl interpreter. You can write modules
04c692a8
DR
648that export functions, you can give those functions prototypes so they
649can be called like built-in functions, you can even write XS code to
650mess with the runtime data structures of the Perl interpreter if you
651want to implement really complicated things.
902b9dbf 652
04c692a8
DR
653Whenever possible, new features should be prototyped in a CPAN module
654before they will be considered for the core.
902b9dbf 655
04c692a8 656=head3 Is the feature generic enough?
902b9dbf 657
04c692a8
DR
658Is this something that only the submitter wants added to the language,
659or is it broadly useful? Sometimes, instead of adding a feature with a
660tight focus, the porters might decide to wait until someone implements
661the more generalized feature.
902b9dbf 662
04c692a8 663=head3 Does it potentially introduce new bugs?
902b9dbf 664
04c692a8
DR
665Radical rewrites of large chunks of the Perl interpreter have the
666potential to introduce new bugs.
902b9dbf 667
04c692a8 668=head3 How big is it?
902b9dbf 669
531e2078 670The smaller and more localized the change, the better. Similarly, a
04c692a8 671series of small patches is greatly preferred over a single large patch.
902b9dbf 672
04c692a8 673=head3 Does it preclude other desirable features?
902b9dbf 674
04c692a8 675A patch is likely to be rejected if it closes off future avenues of
531e2078 676development. For instance, a patch that placed a true and final
04c692a8
DR
677interpretation on prototypes is likely to be rejected because there are
678still options for the future of prototypes that haven't been addressed.
902b9dbf 679
04c692a8 680=head3 Is the implementation robust?
902b9dbf 681
04c692a8 682Good patches (tight code, complete, correct) stand more chance of going
531e2078 683in. Sloppy or incorrect patches might be placed on the back burner
04c692a8
DR
684until the pumpking has time to fix, or might be discarded altogether
685without further notice.
902b9dbf 686
04c692a8 687=head3 Is the implementation generic enough to be portable?
902b9dbf 688
531e2078 689The worst patches make use of system-specific features. It's highly
04c692a8
DR
690unlikely that non-portable additions to the Perl language will be
691accepted.
902b9dbf 692
04c692a8 693=head3 Is the implementation tested?
902b9dbf 694
04c692a8
DR
695Patches which change behaviour (fixing bugs or introducing new
696features) must include regression tests to verify that everything works
697as expected.
902b9dbf 698
04c692a8
DR
699Without tests provided by the original author, how can anyone else
700changing perl in the future be sure that they haven't unwittingly
701broken the behaviour the patch implements? And without tests, how can
702the patch's author be confident that his/her hard work put into the
703patch won't be accidentally thrown away by someone in the future?
902b9dbf 704
04c692a8 705=head3 Is there enough documentation?
902b9dbf 706
04c692a8 707Patches without documentation are probably ill-thought out or
531e2078 708incomplete. No features can be added or changed without documentation,
04c692a8
DR
709so submitting a patch for the appropriate pod docs as well as the
710source code is important.
902b9dbf 711
04c692a8 712=head3 Is there another way to do it?
902b9dbf 713
04c692a8 714Larry said "Although the Perl Slogan is I<There's More Than One Way to
531e2078 715Do It>, I hesitate to make 10 ways to do something". This is a tricky
04c692a8
DR
716heuristic to navigate, though--one man's essential addition is another
717man's pointless cruft.
902b9dbf 718
04c692a8 719=head3 Does it create too much work?
902b9dbf 720
04c692a8
DR
721Work for the pumpking, work for Perl programmers, work for module
722authors, ... Perl is supposed to be easy.
902b9dbf 723
04c692a8 724=head3 Patches speak louder than words
902b9dbf 725
531e2078 726Working code is always preferred to pie-in-the-sky ideas. A patch to
04c692a8
DR
727add a feature stands a much higher chance of making it to the language
728than does a random feature request, no matter how fervently argued the
a44b8c28
S
729request might be. This ties into "Will it be useful?", as the fact
730that someone took the time to make the patch demonstrates a strong
731desire for the feature.
c406981e 732
04c692a8 733=head1 TESTING
c406981e 734
04c692a8
DR
735The core uses the same testing style as the rest of Perl, a simple
736"ok/not ok" run through Test::Harness, but there are a few special
737considerations.
c406981e 738
531e2078 739There are three ways to write a test in the core: L<Test::More>,
a44b8c28
S
740F<t/test.pl> and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">.
741The decision of which to use depends on what part of the test suite
742you're working on. This is a measure to prevent a high-level failure
743(such as Config.pm breaking) from causing basic functionality tests to
744fail.
c406981e 745
04c692a8
DR
746The F<t/test.pl> library provides some of the features of
747L<Test::More>, but avoids loading most modules and uses as few core
748features as possible.
902b9dbf 749
9e6670f3
DR
750If you write your own test, use the L<Test Anything
751Protocol|http://testanything.org>.
902b9dbf
MF
752
753=over 4
754
bb52f720 755=item * F<t/base>, F<t/comp> and F<t/opbasic>
902b9dbf 756
15c526cb 757Since we don't know if C<require> works, or even subroutines, use ad hoc
531e2078 758tests for these three. Step carefully to avoid using the feature being
a44b8c28
S
759tested. Tests in F<t/opbasic>, for instance, have been placed there
760rather than in F<t/op> because they test functionality which
761F<t/test.pl> presumes has already been demonstrated to work.
902b9dbf 762
a8d15a22 763=item * F<t/cmd>, F<t/run>, F<t/io> and F<t/op>
902b9dbf 764
04c692a8
DR
765Now that basic require() and subroutines are tested, you can use the
766F<t/test.pl> library.
902b9dbf 767
a8d15a22 768You can also use certain libraries like Config conditionally, but be
04c692a8 769sure to skip the test gracefully if it's not there.
902b9dbf 770
04c692a8 771=item * Everything else
902b9dbf 772
04c692a8 773Now that the core of Perl is tested, L<Test::More> can and should be
531e2078 774used. You can also use the full suite of core modules in the tests.
902b9dbf
MF
775
776=back
777
a8d15a22 778When you say "make test", Perl uses the F<t/TEST> program to run the
a44b8c28
S
779test suite (except under Win32 where it uses F<t/harness> instead).
780All tests are run from the F<t/> directory, B<not> the directory which
781contains the test. This causes some problems with the tests in
782F<lib/>, so here's some opportunity for some patching.
902b9dbf 783
531e2078 784You must be triply conscious of cross-platform concerns. This usually
eb9df707
KW
785boils down to using L<File::Spec>, avoiding things like C<fork()>
786and C<system()> unless absolutely necessary, and not assuming that a
787given character has a particular ordinal value (code point) or that its
788UTF-8 representation is composed of particular bytes.
789
790There are several functions available to specify characters and code
791points portably in tests. The always-preloaded functions
792C<utf8::unicode_to_native()> and its inverse
793C<utf8::native_to_unicode()> take code points and translate
794appropriately. The file F<t/charset_tools.pl> has several functions
795that can be useful. It has versions of the previous two functions
796that take strings as inputs -- not single numeric code points:
797C<uni_to_native()> and C<native_to_uni()>. If you must look at the
798individual bytes comprising a UTF-8 encoded string,
799C<byte_utf8a_to_utf8n()> takes as input a string of those bytes encoded
800for an ASCII platform, and returns the equivalent string in the native
801platform. For example, C<byte_utf8a_to_utf8n("\xC2\xA0")> returns the
802byte sequence on the current platform that form the UTF-8 for C<U+00A0>,
803since C<"\xC2\xA0"> are the UTF-8 bytes on an ASCII platform for that
804code point. This function returns C<"\xC2\xA0"> on an ASCII platform, and
805C<"\x80\x41"> on an EBCDIC 1047 one.
806
15c526cb
KW
807But easiest is, if the character is specifiable as a literal, like
808C<"A"> or C<"%">, to use that; if not so specificable, you can use use
809C<\N{}> , if the side effects aren't troublesome. Simply specify all
810your characters in hex, using C<\N{U+ZZ}> instead of C<\xZZ>. C<\N{}>
811is the Unicode name, and so it
eb9df707
KW
812always gives you the Unicode character. C<\N{U+41}> is the character
813whose Unicode code point is C<0x41>, hence is C<'A'> on all platforms.
814The side effects are:
815
816=over 4
817
3f9568ff 818=item *
eb9df707
KW
819
820These select Unicode rules. That means that in double-quotish strings,
821the string is always converted to UTF-8 to force a Unicode
822interpretation (you can C<utf8::downgrade()> afterwards to convert back
823to non-UTF8, if possible). In regular expression patterns, the
824conversion isn't done, but if the character set modifier would
825otherwise be C</d>, it is changed to C</u>.
826
3f9568ff 827=item *
eb9df707
KW
828
829If you use the form C<\N{I<character name>}>, the L<charnames> module
830gets automatically loaded. This may not be suitable for the test level
831you are doing.
832
833=back
7a834142 834
15c526cb
KW
835If you are testing locales (see L<perllocale>), there are helper
836functions in F<t/loc_tools.pl> to enable you to see what locales there
837are on the current platform.
838
04c692a8 839=head2 Special C<make test> targets
07aa3531 840
04c692a8 841There are various special make targets that can be used to test Perl
531e2078
FC
842slightly differently than the standard "test" target. Not all them are
843expected to give a 100% success rate. Many of them have several
04c692a8
DR
844aliases, and many of them are not available on certain operating
845systems.
07aa3531 846
04c692a8 847=over 4
d44161bf 848
04c692a8 849=item * test_porting
7a834142 850
04c692a8
DR
851This runs some basic sanity tests on the source tree and helps catch
852basic errors before you submit a patch.
7a834142 853
04c692a8 854=item * minitest
51a35ef1 855
04c692a8
DR
856Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>,
857F<t/op>, F<t/uni> and F<t/mro> tests.
51a35ef1 858
499cea6b 859=item * test.valgrind check.valgrind
51a35ef1 860
04c692a8 861(Only in Linux) Run all the tests using the memory leak + naughty
531e2078 862memory access tool "valgrind". The log files will be named
04c692a8 863F<testname.valgrind>.
83f0ef60 864
04c692a8 865=item * test_harness
83f0ef60 866
04c692a8 867Run the test suite with the F<t/harness> controlling program, instead
531e2078 868of F<t/TEST>. F<t/harness> is more sophisticated, and uses the
04c692a8 869L<Test::Harness> module, thus using this test target supposes that perl
531e2078 870mostly works. The main advantage for our purposes is that it prints a
a44b8c28
S
871detailed summary of failed tests at the end. Also, unlike F<t/TEST>,
872it doesn't redirect stderr to stdout.
83f0ef60 873
04c692a8
DR
874Note that under Win32 F<t/harness> is always used instead of F<t/TEST>,
875so there is no special "test_harness" target.
83f0ef60 876
04c692a8
DR
877Under Win32's "test" target you may use the TEST_SWITCHES and
878TEST_FILES environment variables to control the behaviour of
531e2078 879F<t/harness>. This means you can say
83f0ef60 880
04c692a8
DR
881 nmake test TEST_FILES="op/*.t"
882 nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t"
83f0ef60 883
78087e0a
R
884=item * test-notty test_notty
885
886Sets PERL_SKIP_TTY_TEST to true before running normal test.
887
83f0ef60
JH
888=back
889
04c692a8 890=head2 Parallel tests
83f0ef60 891
04c692a8 892The core distribution can now run its regression tests in parallel on
531e2078 893Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS>
04c692a8 894in your environment to the number of tests to run in parallel, and run
531e2078 895C<make test_harness>. On a Bourne-like shell, this can be done as
07aa3531 896
04c692a8 897 TEST_JOBS=3 make test_harness # Run 3 tests in parallel
07aa3531 898
04c692a8
DR
899An environment variable is used, rather than parallel make itself,
900because L<TAP::Harness> needs to be able to schedule individual
901non-conflicting test scripts itself, and there is no standard interface
902to C<make> utilities to interact with their job schedulers.
51a35ef1 903
9e6670f3 904Note that currently some test scripts may fail when run in parallel
cb0ee57a 905(most notably F<dist/IO/t/io_dir.t>). If necessary, run just the
a44b8c28 906failing scripts again sequentially and see if the failures go away.
51a35ef1 907
04c692a8 908=head2 Running tests by hand
51a35ef1 909
9e6670f3
DR
910You can run part of the test suite by hand by using one of the
911following commands from the F<t/> directory:
51a35ef1 912
04c692a8 913 ./perl -I../lib TEST list-of-.t-files
51a35ef1 914
04c692a8 915or
51a35ef1 916
04c692a8 917 ./perl -I../lib harness list-of-.t-files
51a35ef1 918
a8d15a22 919(If you don't specify test scripts, the whole test suite will be run.)
51a35ef1 920
04c692a8 921=head2 Using F<t/harness> for testing
51a35ef1 922
9e6670f3 923If you use C<harness> for testing, you have several command line
531e2078 924options available to you. The arguments are as follows, and are in the
9e6670f3 925order that they must appear if used together.
51a35ef1 926
04c692a8
DR
927 harness -v -torture -re=pattern LIST OF FILES TO TEST
928 harness -v -torture -re LIST OF PATTERNS TO MATCH
07aa3531 929
a8d15a22 930If C<LIST OF FILES TO TEST> is omitted, the file list is obtained from
531e2078 931the manifest. The file list may include shell wildcards which will be
04c692a8 932expanded out.
07aa3531 933
04c692a8 934=over 4
4ae3d70a 935
04c692a8 936=item * -v
4ae3d70a 937
04c692a8
DR
938Run the tests under verbose mode so you can see what tests were run,
939and debug output.
51a35ef1 940
04c692a8 941=item * -torture
4ae3d70a 942
04c692a8 943Run the torture tests as well as the normal set.
4ae3d70a 944
04c692a8 945=item * -re=PATTERN
6c41479b 946
a44b8c28
S
947Filter the file list so that all the test files run match PATTERN.
948Note that this form is distinct from the B<-re LIST OF PATTERNS> form
949below in that it allows the file list to be provided as well.
6c41479b 950
04c692a8 951=item * -re LIST OF PATTERNS
6c41479b 952
04c692a8 953Filter the file list so that all the test files run match
531e2078 954/(LIST|OF|PATTERNS)/. Note that with this form the patterns are joined
04c692a8
DR
955by '|' and you cannot supply a list of files, instead the test files
956are obtained from the MANIFEST.
6c41479b 957
04c692a8 958=back
6c41479b 959
04c692a8 960You can run an individual test by a command similar to
6c41479b 961
a8d15a22 962 ./perl -I../lib path/to/foo.t
6c41479b 963
04c692a8
DR
964except that the harnesses set up some environment variables that may
965affect the execution of the test:
6c41479b
JH
966
967=over 4
968
04c692a8 969=item * PERL_CORE=1
6c41479b 970
a8d15a22 971indicates that we're running this test as part of the perl core test
531e2078 972suite. This is useful for modules that have a dual life on CPAN.
6c41479b 973
04c692a8 974=item * PERL_DESTRUCT_LEVEL=2
6c41479b 975
04c692a8 976is set to 2 if it isn't set already (see
a8d15a22 977L<perlhacktips/PERL_DESTRUCT_LEVEL>).
6c41479b 978
04c692a8 979=item * PERL
6c41479b 980
04c692a8
DR
981(used only by F<t/TEST>) if set, overrides the path to the perl
982executable that should be used to run the tests (the default being
983F<./perl>).
6c41479b 984
04c692a8 985=item * PERL_SKIP_TTY_TEST
6c41479b 986
a44b8c28
S
987if set, tells to skip the tests that need a terminal. It's actually
988set automatically by the Makefile, but can also be forced artificially
989by running 'make test_notty'.
6c41479b 990
04c692a8 991=back
6c41479b 992
04c692a8 993=head3 Other environment variables that may influence tests
6c41479b 994
04c692a8 995=over 4
6c41479b 996
04c692a8 997=item * PERL_TEST_Net_Ping
6c41479b 998
04c692a8 999Setting this variable runs all the Net::Ping modules tests, otherwise
531e2078 1000some tests that interact with the outside world are skipped. See
04c692a8 1001L<perl58delta>.
6c41479b 1002
04c692a8 1003=item * PERL_TEST_NOVREXX
cce04beb 1004
04c692a8 1005Setting this variable skips the vrexx.t tests for OS2::REXX.
cce04beb 1006
04c692a8 1007=item * PERL_TEST_NUMCONVERTS
cce04beb 1008
04c692a8 1009This sets a variable in op/numconvert.t.
cce04beb 1010
ff5db609
TC
1011=item * PERL_TEST_MEMORY
1012
1013Setting this variable includes the tests in F<t/bigmem/>. This should
a44b8c28
S
1014be set to the number of gigabytes of memory available for testing, eg.
1015C<PERL_TEST_MEMORY=4> indicates that tests that require 4GiB of
ff5db609
TC
1016available memory can be run safely.
1017
04c692a8 1018=back
cce04beb 1019
04c692a8
DR
1020See also the documentation for the Test and Test::Harness modules, for
1021more environment variables that affect testing.
cce04beb 1022
9e7973fa
DM
1023=head2 Performance testing
1024
1025The file F<t/perf/benchmarks> contains snippets of perl code which are
1026intended to be benchmarked across a range of perls by the
1027F<Porting/bench.pl> tool. If you fix or enhance a performance issue, you
1028may want to add a representative code sample to the file, then run
1029F<bench.pl> against the previous and current perls to see what difference
1030it has made, and whether anything else has slowed down as a consequence.
1031
1032The file F<t/perf/opcount.t> is designed to test whether a particular
1033code snippet has been compiled into an optree containing specified
1034numbers of particular op types. This is good for testing whether
1035optimisations which alter ops, such as converting an C<aelem> op into an
1036C<aelemfast> op, are really doing that.
1037
1038The files F<t/perf/speed.t> and F<t/re/speed.t> are designed to test
1039things that run thousands of times slower if a particular optimisation
1040is broken (for example, the utf8 length cache on long utf8 strings).
1041Add a test that will take a fraction of a second normally, and minutes
1042otherwise, causing the test file to time out on failure.
1043
ca31f56c
JK
1044=head2 Building perl at older commits
1045
1046In the course of hacking on the Perl core distribution, you may have occasion
1047to configure, build and test perl at an old commit. Sometimes C<make> will
1048fail during this process. If that happens, you may be able to salvage the
1049situation by using the Devel::PatchPerl library from CPAN (not included in the
1050core) to bring the source code at that commit to a buildable state.
1051
1052Here's a real world example, taken from work done to resolve
1053L<perl #72414|https://rt.perl.org/Ticket/Display.html?id=72414>.
1054Use of F<Porting/bisect.pl> had identified commit
1055C<ba77e4cc9d1ceebf472c9c5c18b2377ee47062e6> as the commit in which a bug was
1056corrected. To confirm, a P5P developer wanted to configure and build perl at
1057commit C<ba77e4c^> (presumably "bad") and then at C<ba77e4c> (presumably
1058"good"). Normal configuration and build was attempted:
1059
1060 $ sh ./Configure -des -Dusedevel
1061 $ make test_prep
1062
1063C<make>, however, failed with output (excerpted) like this:
1064
1065 cc -fstack-protector -L/usr/local/lib -o miniperl \
1066 gv.o toke.o perly.o pad.o regcomp.o dump.o util.o \
1067 mg.o reentr.o mro.o hv.o av.o run.o pp_hot.o sv.o \
1068 pp.o scope.o pp_ctl.o pp_sys.o doop.o doio.o regexec.o \
1069 utf8.o taint.o deb.o universal.o globals.o perlio.o \
1070 perlapi.o numeric.o mathoms.o locale.o pp_pack.o pp_sort.o \
1071 miniperlmain.o opmini.o perlmini.o
1072 pp.o: In function `Perl_pp_pow':
1073 pp.c:(.text+0x2db9): undefined reference to `pow'
1074 ...
1075 collect2: error: ld returned 1 exit status
1076 makefile:348: recipe for target 'miniperl' failed
1077 make: *** [miniperl] Error 1
1078
1079Another P5P contributor recommended installation and use of Devel::PatchPerl
1080for this situation, first to determine the version of perl at the commit in
1081question, then to patch the source code at that point to facilitate a build.
1082
1083 $ perl -MDevel::PatchPerl -e \
1084 'print Devel::PatchPerl->determine_version("/path/to/sourcecode"), "\n";'
1085 5.11.1
1086 $ perl -MDevel::PatchPerl -e \
1087 'Devel::PatchPerl->patch_source("5.11.1", "/path/to/sourcecode");'
1088
1089Once the source was patched, C<./Configure> and C<make test_prep> were called
1090and completed successfully, enabling confirmation of the findings in RT
1091#72414.
1092
04c692a8 1093=head1 MORE READING FOR GUTS HACKERS
cce04beb 1094
04c692a8 1095To hack on the Perl guts, you'll need to read the following things:
cce04beb 1096
04c692a8 1097=over 4
cce04beb 1098
04c692a8 1099=item * L<perlsource>
b8ddf6b3 1100
531e2078 1101An overview of the Perl source tree. This will help you find the files
04c692a8 1102you're looking for.
b8ddf6b3 1103
04c692a8 1104=item * L<perlinterp>
b8ddf6b3 1105
04c692a8
DR
1106An overview of the Perl interpreter source code and some details on how
1107Perl does what it does.
b8ddf6b3 1108
04c692a8 1109=item * L<perlhacktut>
b8ddf6b3 1110
04c692a8 1111This document walks through the creation of a small patch to Perl's C
531e2078 1112code. If you're just getting started with Perl core hacking, this will
04c692a8 1113help you understand how it works.
b8ddf6b3 1114
04c692a8 1115=item * L<perlhacktips>
b8ddf6b3 1116
531e2078 1117More details on hacking the Perl core. This document focuses on lower
04c692a8
DR
1118level details such as how to write tests, compilation issues,
1119portability, debugging, etc.
b8ddf6b3 1120
04c692a8 1121If you plan on doing serious C hacking, make sure to read this.
b8ddf6b3 1122
04c692a8 1123=item * L<perlguts>
b8ddf6b3 1124
04c692a8 1125This is of paramount importance, since it's the documentation of what
531e2078 1126goes where in the Perl source. Read it over a couple of times and it
04c692a8
DR
1127might start to make sense - don't worry if it doesn't yet, because the
1128best way to study it is to read it in conjunction with poking at Perl
1129source, and we'll do that later on.
b8ddf6b3 1130
04c692a8
DR
1131Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very
1132helpful pictures:
9965345d 1133
04c692a8 1134L<http://search.cpan.org/dist/illguts/>
9965345d 1135
04c692a8 1136=item * L<perlxstut> and L<perlxs>
f1fac472 1137
04c692a8
DR
1138A working knowledge of XSUB programming is incredibly useful for core
1139hacking; XSUBs use techniques drawn from the PP code, the portion of
531e2078 1140the guts that actually executes a Perl program. It's a lot gentler to
04c692a8
DR
1141learn those techniques from simple examples and explanation than from
1142the core itself.
f1fac472 1143
04c692a8 1144=item * L<perlapi>
f1fac472 1145
04c692a8
DR
1146The documentation for the Perl API explains what some of the internal
1147functions do, as well as the many macros used in the source.
f1fac472 1148
04c692a8 1149=item * F<Porting/pumpkin.pod>
f1fac472 1150
04c692a8
DR
1151This is a collection of words of wisdom for a Perl porter; some of it
1152is only useful to the pumpkin holder, but most of it applies to anyone
1153wanting to go about Perl development.
f1fac472 1154
04c692a8 1155=back
f1fac472 1156
04c692a8 1157=head1 CPAN TESTERS AND PERL SMOKERS
f1fac472 1158
4b05bc8e 1159The CPAN testers ( L<http://testers.cpan.org/> ) are a group of volunteers
04c692a8 1160who test CPAN modules on a variety of platforms.
b8ddf6b3 1161
4b05bc8e
KW
1162Perl Smokers ( L<http://www.nntp.perl.org/group/perl.daily-build/> and
1163L<http://www.nntp.perl.org/group/perl.daily-build.reports/> )
04c692a8
DR
1164automatically test Perl source releases on platforms with various
1165configurations.
f1fac472 1166
531e2078 1167Both efforts welcome volunteers. In order to get involved in smoke
04c692a8 1168testing of the perl itself visit
531e2078 1169L<http://search.cpan.org/dist/Test-Smoke/>. In order to start smoke
04c692a8
DR
1170testing CPAN modules visit
1171L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or
1172L<http://search.cpan.org/dist/minismokebox/> or
1173L<http://search.cpan.org/dist/CPAN-Reporter/>.
f1fac472 1174
04c692a8 1175=head1 WHAT NEXT?
a422fd2d 1176
04c692a8
DR
1177If you've read all the documentation in the document and the ones
1178listed above, you're more than ready to hack on Perl.
a422fd2d 1179
04c692a8 1180Here's some more recommendations
a422fd2d 1181
04c692a8 1182=over 4
a422fd2d
SC
1183
1184=item *
1185
1186Subscribe to perl5-porters, follow the patches and try and understand
1187them; don't be afraid to ask if there's a portion you're not clear on -
1188who knows, you may unearth a bug in the patch...
1189
1190=item *
1191
04c692a8 1192Do read the README associated with your operating system, e.g.
531e2078 1193README.aix on the IBM AIX OS. Don't hesitate to supply patches to that
04c692a8 1194README if you find anything missing or changed over a new OS release.
a1f349fd
MB
1195
1196=item *
1197
a422fd2d 1198Find an area of Perl that seems interesting to you, and see if you can
a44b8c28
S
1199work out how it works. Scan through the source, and step over it in
1200the debugger. Play, poke, investigate, fiddle! You'll probably get to
04c692a8
DR
1201understand not just your chosen area but a much wider range of
1202F<perl>'s activity as well, and probably sooner than you'd think.
a422fd2d
SC
1203
1204=back
1205
04c692a8 1206=head2 "The Road goes ever on and on, down from the door where it began."
a422fd2d 1207
04c692a8 1208If you can do these things, you've started on the long road to Perl
531e2078 1209porting. Thanks for wanting to help make Perl better - and happy
04c692a8 1210hacking!
a422fd2d 1211
4ac71550
TC
1212=head2 Metaphoric Quotations
1213
1214If you recognized the quote about the Road above, you're in luck.
1215
04c692a8 1216Most software projects begin each file with a literal description of
531e2078 1217each file's purpose. Perl instead begins each with a literary allusion
04c692a8 1218to that file's purpose.
4ac71550 1219
04c692a8 1220Like chapters in many books, all top-level Perl source files (along
9e6670f3
DR
1221with a few others here and there) begin with an epigrammatic
1222inscription that alludes, indirectly and metaphorically, to the
1223material you're about to read.
4ac71550 1224
a8d15a22 1225Quotations are taken from writings of J.R.R. Tolkien pertaining to his
531e2078 1226Legendarium, almost always from I<The Lord of the Rings>. Chapters and
4ac71550
TC
1227page numbers are given using the following editions:
1228
1229=over 4
1230
04c692a8 1231=item *
4ac71550 1232
531e2078 1233I<The Hobbit>, by J.R.R. Tolkien. The hardcover, 70th-anniversary
04c692a8
DR
1234edition of 2007 was used, published in the UK by Harper Collins
1235Publishers and in the US by the Houghton Mifflin Company.
4ac71550
TC
1236
1237=item *
1238
531e2078 1239I<The Lord of the Rings>, by J.R.R. Tolkien. The hardcover,
04c692a8
DR
124050th-anniversary edition of 2004 was used, published in the UK by
1241Harper Collins Publishers and in the US by the Houghton Mifflin
1242Company.
4ac71550
TC
1243
1244=item *
1245
04c692a8
DR
1246I<The Lays of Beleriand>, by J.R.R. Tolkien and published posthumously
1247by his son and literary executor, C.J.R. Tolkien, being the 3rd of the
531e2078 124812 volumes in Christopher's mammoth I<History of Middle Earth>. Page
04c692a8
DR
1249numbers derive from the hardcover edition, first published in 1983 by
1250George Allen & Unwin; no page numbers changed for the special 3-volume
1251omnibus edition of 2002 or the various trade-paper editions, all again
1252now by Harper Collins or Houghton Mifflin.
4ac71550
TC
1253
1254=back
1255
04c692a8
DR
1256Other JRRT books fair game for quotes would thus include I<The
1257Adventures of Tom Bombadil>, I<The Silmarillion>, I<Unfinished Tales>,
1258and I<The Tale of the Children of Hurin>, all but the first
531e2078 1259posthumously assembled by CJRT. But I<The Lord of the Rings> itself is
04c692a8
DR
1260perfectly fine and probably best to quote from, provided you can find a
1261suitable quote there.
4ac71550 1262
04c692a8
DR
1263So if you were to supply a new, complete, top-level source file to add
1264to Perl, you should conform to this peculiar practice by yourself
1265selecting an appropriate quotation from Tolkien, retaining the original
1266spelling and punctuation and using the same format the rest of the
531e2078 1267quotes are in. Indirect and oblique is just fine; remember, it's a
04c692a8 1268metaphor, so being meta is, after all, what it's for.
4ac71550 1269
e8cd7eae
GS
1270=head1 AUTHOR
1271
04c692a8
DR
1272This document was originally written by Nathan Torkington, and is
1273maintained by the perl5-porters mailing list.