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