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