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