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