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