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