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