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