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