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