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