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