1PERLHACK(1) Perl Programmers Reference Guide PERLHACK(1)
2
6 perlhack - How to hack on Perl
7
9 This document explains how Perl development works. It includes details
10 about the Perl 5 Porters email list, the Perl repository, the Perlbug
11 bug tracker, patch guidelines, and commentary on Perl development
12 philosophy.
13
15 If you just want to submit a single small patch like a pod fix, a test
16 for a bug, comment fixes, etc., it's easy! Here's how:
17 · Check out the source repository
19 The perl source is in a git repository. You can clone the
21 repository with the following command:
22 % git clone git://perl5.git.perl.org/perl.git perl
24 · Make your change
26 Hack, hack, hack.
28 · Test your change
30 You can run all the tests with the following commands:
32 % ./Configure -des -Dusedevel
34 % make test
35 Keep hacking until the tests pass.
37 · Commit your change
39 Committing your work will save the change on your local system:
41 % git commit -a -m 'Commit message goes here'
43 Make sure the commit message describes your change in a single
45 sentence. For example, "Fixed spelling errors in perlhack.pod".
46 · Send your change to perlbug
48 The next step is to submit your patch to the Perl core ticket
50 system via email.
51 Assuming your patch consists of a single git commit, the following
53 writes the file as a MIME attachment, and sends it with a
54 meaningful subject:
55 % git format-patch -1 --attach
57 % perlbug -s "[PATCH] $(git log -1 --oneline HEAD)" -f 0001-*.patch
58 The perlbug program will ask you a few questions about your email
60 address and the patch you're submitting. Once you've answered them
61 it will submit your patch via email.
62 · Thank you
64 The porters appreciate the time you spent helping to make Perl
66 better. Thank you!
67
69 If you want to report a bug in Perl, you must use the perlbug command
70 line tool. This tool will ensure that your bug report includes all the
71 relevant system and configuration information.
72 To browse existing Perl bugs and patches, you can use the web interface
74 at <http://rt.perl.org/>.
75 Please check the archive of the perl5-porters list (see below) and/or
77 the bug tracking system before submitting a bug report. Often, you'll
78 find that the bug has been reported already.
79 You can log in to the bug tracking system and comment on existing bug
81 reports. If you have additional information regarding an existing bug,
82 please add it. This will help the porters fix the bug.
83
85 The perl5-porters (p5p) mailing list is where the Perl standard
86 distribution is maintained and developed. The people who maintain Perl
87 are also referred to as the "Perl 5 Porters", "p5p" or just the
88 "porters".
89 A searchable archive of the list is available at
91 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/
92 <http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is
93 also another archive at
94 http://archive.develooper.com/perl5-porters@perl.org/
95 <http://archive.develooper.com/perl5-porters@perl.org/>.
96 perl-changes mailing list
98 The perl5-changes mailing list receives a copy of each patch that gets
99 submitted to the maintenance and development branches of the perl
100 repository. See http://lists.perl.org/list/perl5-changes.html
101 <http://lists.perl.org/list/perl5-changes.html> for subscription and
102 archive information.
103 #p5p on IRC
105 Many porters are also active on the <irc://irc.perl.org/#p5p> channel.
106 Feel free to join the channel and ask questions about hacking on the
107 Perl core.
108
110 All of Perl's source code is kept centrally in a Git repository at
111 perl5.git.perl.org. The repository contains many Perl revisions from
112 Perl 1 onwards and all the revisions from Perforce, the previous
113 version control system.
114 For much more detail on using git with the Perl repository, please see
116 perlgit.
117 Read access via Git
119 You will need a copy of Git for your computer. You can fetch a copy of
120 the repository using the git protocol:
121 % git clone git://perl5.git.perl.org/perl.git perl
123 This clones the repository and makes a local copy in the perl
125 directory.
126 If you cannot use the git protocol for firewall reasons, you can also
128 clone via http, though this is much slower:
129 % git clone http://perl5.git.perl.org/perl.git perl
131 Read access via the web
133 You may access the repository over the web. This allows you to browse
134 the tree, see recent commits, subscribe to RSS feeds for the changes,
135 search for particular commits and more. You may access it at
136 <http://perl5.git.perl.org/perl.git>. A mirror of the repository is
137 found at <http://github.com/mirrors/perl>.
138 Read access via rsync
140 You can also choose to use rsync to get a copy of the current source
141 tree for the bleadperl branch and all maintenance branches:
142 % rsync -avz rsync://perl5.git.perl.org/perl-current .
144 % rsync -avz rsync://perl5.git.perl.org/perl-5.12.x .
145 % rsync -avz rsync://perl5.git.perl.org/perl-5.10.x .
146 % rsync -avz rsync://perl5.git.perl.org/perl-5.8.x .
147 % rsync -avz rsync://perl5.git.perl.org/perl-5.6.x .
148 % rsync -avz rsync://perl5.git.perl.org/perl-5.005xx .
149 (Add the "--delete" option to remove leftover files.)
151 To get a full list of the available sync points:
153 % rsync perl5.git.perl.org::
155 Write access via git
157 If you have a commit bit, please see perlgit for more details on using
158 git.
159
161 If you're planning to do more extensive work than a single small fix,
162 we encourage you to read the documentation below. This will help you
163 focus your work and make your patches easier to incorporate into the
164 Perl source.
165 Submitting patches
167 If you have a small patch to submit, please submit it via perlbug. You
168 can also send email directly to perlbug@perl.org. Please note that
169 messages sent to perlbug may be held in a moderation queue, so you
170 won't receive a response immediately.
171 You'll know your submission has been processed when you receive an
173 email from our ticket tracking system. This email will give you a
174 ticket number. Once your patch has made it to the ticket tracking
175 system, it will also be sent to the perl5-porters@perl.org list.
176 Patches are reviewed and discussed on the p5p list. Simple,
178 uncontroversial patches will usually be applied without any discussion.
179 When the patch is applied, the ticket will be updated and you will
180 receive email. In addition, an email will be sent to the p5p list.
181 In other cases, the patch will need more work or discussion. That will
183 happen on the p5p list.
184 You are encouraged to participate in the discussion and advocate for
186 your patch. Sometimes your patch may get lost in the shuffle. It's
187 appropriate to send a reminder email to p5p if no action has been taken
188 in a month. Please remember that the Perl 5 developers are all
189 volunteers, and be polite.
190 Changes are always applied directly to the main development branch,
192 called "blead". Some patches may be backported to a maintenance branch.
193 If you think your patch is appropriate for the maintenance branch,
194 please explain why when you submit it.
195 Getting your patch accepted
197 If you are submitting a code patch there are several things that you
198 can do to help the Perl 5 Porters accept your patch.
199 Patch style
201 If you used git to check out the Perl source, then using "git
203 format-patch" will produce a patch in a style suitable for Perl. The
204 "format-patch" command produces one patch file for each commit you
205 made. If you prefer to send a single patch for all commits, you can use
206 "git diff".
207 % git checkout blead
209 % git pull
210 % git diff blead my-branch-name
211 This produces a patch based on the difference between blead and your
213 current branch. It's important to make sure that blead is up to date
214 before producing the diff, that's why we call "git pull" first.
215 We strongly recommend that you use git if possible. It will make your
217 life easier, and ours as well.
218 However, if you're not using git, you can still produce a suitable
220 patch. You'll need a pristine copy of the Perl source to diff against.
221 The porters prefer unified diffs. Using GNU "diff", you can produce a
222 diff like this:
223 % diff -Npurd perl.pristine perl.mine
225 Make sure that you "make realclean" in your copy of Perl to remove any
227 build artifacts, or you may get a confusing result.
228 Commit message
230 As you craft each patch you intend to submit to the Perl core, it's
232 important to write a good commit message. This is especially important
233 if your submission will consist of a series of commits.
234 The first line of the commit message should be a short description
236 without a period. It should be no longer than the subject line of an
237 email, 50 characters being a good rule of thumb.
238 A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will
240 only display the first line (cut off at 50 characters) when presenting
241 commit summaries.
242 The commit message should include a description of the problem that the
244 patch corrects or new functionality that the patch adds.
245 As a general rule of thumb, your commit message should help a
247 programmer who knows the Perl core quickly understand what you were
248 trying to do, how you were trying to do it, and why the change matters
249 to Perl.
250 · Why
252 Your commit message should describe why the change you are making
254 is important. When someone looks at your change in six months or
255 six years, your intent should be clear.
256 If you're deprecating a feature with the intent of later
258 simplifying another bit of code, say so. If you're fixing a
259 performance problem or adding a new feature to support some other
260 bit of the core, mention that.
261 · What
263 Your commit message should describe what part of the Perl core
265 you're changing and what you expect your patch to do.
266 · How
268 While it's not necessary for documentation changes, new tests or
270 trivial patches, it's often worth explaining how your change works.
271 Even if it's clear to you today, it may not be clear to a porter
272 next month or next year.
273 A commit message isn't intended to take the place of comments in your
275 code. Commit messages should describe the change you made, while code
276 comments should describe the current state of the code.
277 If you've just implemented a new feature, complete with doc, tests and
279 well-commented code, a brief commit message will often suffice. If,
280 however, you've just changed a single character deep in the parser or
281 lexer, you might need to write a small novel to ensure that future
282 readers understand what you did and why you did it.
283 Comments, Comments, Comments
285 Be sure to adequately comment your code. While commenting every line is
287 unnecessary, anything that takes advantage of side effects of
288 operators, that creates changes that will be felt outside of the
289 function being patched, or that others may find confusing should be
290 documented. If you are going to err, it is better to err on the side of
291 adding too many comments than too few.
292 The best comments explain why the code does what it does, not what it
294 does.
295 Style
297 In general, please follow the particular style of the code you are
299 patching.
300 In particular, follow these general guidelines for patching Perl
302 sources:
303 · 8-wide tabs (no exceptions!)
305 · 4-wide indents for code, 2-wide indents for nested CPP #defines
307 · Try hard not to exceed 79-columns
309 · ANSI C prototypes
311 · Uncuddled elses and "K&R" style for indenting control constructs
313 · No C++ style (//) comments
315 · Mark places that need to be revisited with XXX (and revisit often!)
317 · Opening brace lines up with "if" when conditional spans multiple
319 lines; should be at end-of-line otherwise
320 · In function definitions, name starts in column 0 (return value is
322 on previous line)
323 · Single space after keywords that are followed by parens, no space
325 between function name and following paren
326 · Avoid assignments in conditionals, but if they're unavoidable, use
328 extra paren, e.g. "if (a && (b = c)) ..."
329 · "return foo;" rather than "return(foo);"
331 · "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
333 Test suite
335 If your patch changes code (rather than just changing documentation),
337 you should also include one or more test cases which illustrate the bug
338 you're fixing or validate the new functionality you're adding. In
339 general, you should update an existing test file rather than create a
340 new one.
341 Your test suite additions should generally follow these guidelines
343 (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
344 · Know what you're testing. Read the docs, and the source.
346 · Tend to fail, not succeed.
348 · Interpret results strictly.
350 · Use unrelated features (this will flush out bizarre interactions).
352 · Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
354 · Avoid using hardcoded test numbers whenever possible (the
356 EXPECTED/GOT found in t/op/tie.t is much more maintainable, and
357 gives better failure reports).
358 · Give meaningful error messages when a test fails.
360 · Avoid using qx// and system() unless you are testing for them. If
362 you do use them, make sure that you cover _all_ perl platforms.
363 · Unlink any temporary files you create.
365 · Promote unforeseen warnings to errors with $SIG{__WARN__}.
367 · Be sure to use the libraries and modules shipped with the version
369 being tested, not those that were already installed.
370 · Add comments to the code explaining what you are testing for.
372 · Make updating the '1..42' string unnecessary. Or make sure that you
374 update it.
375 · Test _all_ behaviors of a given operator, library, or function.
377 Test all optional arguments.
379 Test return values in various contexts (boolean, scalar, list,
381 lvalue).
382 Use both global and lexical variables.
384 Don't forget the exceptional, pathological cases.
386 Patching a core module
388 This works just like patching anything else, with one extra
389 consideration.
390 Modules in the cpan/ directory of the source tree are maintained
392 outside of the Perl core. When the author updates the module, the
393 updates are simply copied into the core. See that module's
394 documentation or its listing on <http://search.cpan.org/> for more
395 information on reporting bugs and submitting patches.
396 In most cases, patches to modules in cpan/ should be sent upstream and
398 should not be applied to the Perl core individually. If a patch to a
399 file in cpan/ absolutely cannot wait for the fix to be made upstream,
400 released to CPAN and copied to blead, you must add (or update) a
401 "CUSTOMIZED" entry in the "Porting/Maintainers.pl" file to flag that a
402 local modification has been made. See "Porting/Maintainers.pl" for
403 more details.
404 In contrast, modules in the dist/ directory are maintained in the core.
406 Updating perldelta
408 For changes significant enough to warrant a pod/perldelta.pod entry,
409 the porters will greatly appreciate it if you submit a delta entry
410 along with your actual change. Significant changes include, but are not
411 limited to:
412 · Adding, deprecating, or removing core features
414 · Adding, deprecating, removing, or upgrading core or dual-life
416 modules
417 · Adding new core tests
419 · Fixing security issues and user-visible bugs in the core
421 · Changes that might break existing code, either on the perl or C
423 level
424 · Significant performance improvements
426 · Adding, removing, or significantly changing documentation in the
428 pod/ directory
429 · Important platform-specific changes
431 Please make sure you add the perldelta entry to the right section
433 within pod/perldelta.pod. More information on how to write good
434 perldelta entries is available in the "Style" section of
435 Porting/how_to_write_a_perldelta.pod.
436 What makes for a good patch?
438 New features and extensions to the language can be contentious. There
439 is no specific set of criteria which determine what features get added,
440 but here are some questions to consider when developing a patch:
441 Does the concept match the general goals of Perl?
443 Our goals include, but are not limited to:
445 1. Keep it fast, simple, and useful.
447 2. Keep features/concepts as orthogonal as possible.
449 3. No arbitrary limits (platforms, data sizes, cultures).
451 4. Keep it open and exciting to use/patch/advocate Perl everywhere.
453 5. Either assimilate new technologies, or build bridges to them.
455 Where is the implementation?
457 All the talk in the world is useless without an implementation. In
459 almost every case, the person or people who argue for a new feature
460 will be expected to be the ones who implement it. Porters capable of
461 coding new features have their own agendas, and are not available to
462 implement your (possibly good) idea.
463 Backwards compatibility
465 It's a cardinal sin to break existing Perl programs. New warnings can
467 be contentious--some say that a program that emits warnings is not
468 broken, while others say it is. Adding keywords has the potential to
469 break programs, changing the meaning of existing token sequences or
470 functions might break programs.
471 The Perl 5 core includes mechanisms to help porters make backwards
473 incompatible changes more compatible such as the feature and deprecate
474 modules. Please use them when appropriate.
475 Could it be a module instead?
477 Perl 5 has extension mechanisms, modules and XS, specifically to avoid
479 the need to keep changing the Perl interpreter. You can write modules
480 that export functions, you can give those functions prototypes so they
481 can be called like built-in functions, you can even write XS code to
482 mess with the runtime data structures of the Perl interpreter if you
483 want to implement really complicated things.
484 Whenever possible, new features should be prototyped in a CPAN module
486 before they will be considered for the core.
487 Is the feature generic enough?
489 Is this something that only the submitter wants added to the language,
491 or is it broadly useful? Sometimes, instead of adding a feature with a
492 tight focus, the porters might decide to wait until someone implements
493 the more generalized feature.
494 Does it potentially introduce new bugs?
496 Radical rewrites of large chunks of the Perl interpreter have the
498 potential to introduce new bugs.
499 How big is it?
501 The smaller and more localized the change, the better. Similarly, a
503 series of small patches is greatly preferred over a single large patch.
504 Does it preclude other desirable features?
506 A patch is likely to be rejected if it closes off future avenues of
508 development. For instance, a patch that placed a true and final
509 interpretation on prototypes is likely to be rejected because there are
510 still options for the future of prototypes that haven't been addressed.
511 Is the implementation robust?
513 Good patches (tight code, complete, correct) stand more chance of going
515 in. Sloppy or incorrect patches might be placed on the back burner
516 until the pumpking has time to fix, or might be discarded altogether
517 without further notice.
518 Is the implementation generic enough to be portable?
520 The worst patches make use of system-specific features. It's highly
522 unlikely that non-portable additions to the Perl language will be
523 accepted.
524 Is the implementation tested?
526 Patches which change behaviour (fixing bugs or introducing new
528 features) must include regression tests to verify that everything works
529 as expected.
530 Without tests provided by the original author, how can anyone else
532 changing perl in the future be sure that they haven't unwittingly
533 broken the behaviour the patch implements? And without tests, how can
534 the patch's author be confident that his/her hard work put into the
535 patch won't be accidentally thrown away by someone in the future?
536 Is there enough documentation?
538 Patches without documentation are probably ill-thought out or
540 incomplete. No features can be added or changed without documentation,
541 so submitting a patch for the appropriate pod docs as well as the
542 source code is important.
543 Is there another way to do it?
545 Larry said "Although the Perl Slogan is There's More Than One Way to Do
547 It, I hesitate to make 10 ways to do something". This is a tricky
548 heuristic to navigate, though--one man's essential addition is another
549 man's pointless cruft.
550 Does it create too much work?
552 Work for the pumpking, work for Perl programmers, work for module
554 authors, ... Perl is supposed to be easy.
555 Patches speak louder than words
557 Working code is always preferred to pie-in-the-sky ideas. A patch to
559 add a feature stands a much higher chance of making it to the language
560 than does a random feature request, no matter how fervently argued the
561 request might be. This ties into "Will it be useful?", as the fact that
562 someone took the time to make the patch demonstrates a strong desire
563 for the feature.
564
566 The core uses the same testing style as the rest of Perl, a simple
567 "ok/not ok" run through Test::Harness, but there are a few special
568 considerations.
569 There are three ways to write a test in the core. Test::More, t/test.pl
571 and ad hoc "print $test ? "ok 42\n" : "not ok 42\n"". The decision of
572 which to use depends on what part of the test suite you're working on.
573 This is a measure to prevent a high-level failure (such as Config.pm
574 breaking) from causing basic functionality tests to fail.
575 The t/test.pl library provides some of the features of Test::More, but
577 avoids loading most modules and uses as few core features as possible.
578 If you write your own test, use the Test Anything Protocol
580 <http://testanything.org>.
581 · t/base and t/comp
583 Since we don't know if require works, or even subroutines, use ad
585 hoc tests for these two. Step carefully to avoid using the feature
586 being tested.
587 · t/cmd, t/run, t/io and t/op
589 Now that basic require() and subroutines are tested, you can use
591 the t/test.pl library.
592 You can also use certain libraries like Config conditionally, but
594 be sure to skip the test gracefully if it's not there.
595 · Everything else
597 Now that the core of Perl is tested, Test::More can and should be
599 used. You can also use the full suite of core modules in the tests.
600 When you say "make test", Perl uses the t/TEST program to run the test
602 suite (except under Win32 where it uses t/harness instead). All tests
603 are run from the t/ directory, not the directory which contains the
604 test. This causes some problems with the tests in lib/, so here's some
605 opportunity for some patching.
606 You must be triply conscious of cross-platform concerns. This usually
608 boils down to using File::Spec and avoiding things like "fork()" and
609 "system()" unless absolutely necessary.
610 Special "make test" targets
612 There are various special make targets that can be used to test Perl
613 slightly differently than the standard "test" target. Not all them are
614 expected to give a 100% success rate. Many of them have several
615 aliases, and many of them are not available on certain operating
616 systems.
617 · test_porting
619 This runs some basic sanity tests on the source tree and helps
621 catch basic errors before you submit a patch.
622 · coretest
624 Run perl on all core tests (t/* and lib/[a-z]* pragma tests).
626 (Not available on Win32)
628 · test.deparse
630 Run all the tests through B::Deparse. Not all tests will succeed.
632 (Not available on Win32)
634 · test.taintwarn
636 Run all tests with the -t command-line switch. Not all tests are
638 expected to succeed (until they're specifically fixed, of course).
639 (Not available on Win32)
641 · minitest
643 Run miniperl on t/base, t/comp, t/cmd, t/run, t/io, t/op, t/uni and
645 t/mro tests.
646 · test.valgrind check.valgrind utest.valgrind ucheck.valgrind
648 (Only in Linux) Run all the tests using the memory leak + naughty
650 memory access tool "valgrind". The log files will be named
651 testname.valgrind.
652 · test.torture torturetest
654 Run all the usual tests and some extra tests. As of Perl 5.8.0, the
656 only extra tests are Abigail's JAPHs, t/japh/abigail.t.
657 You can also run the torture test with t/harness by giving
659 "-torture" argument to t/harness.
660 · utest ucheck test.utf8 check.utf8
662 Run all the tests with -Mutf8. Not all tests will succeed.
664 (Not available on Win32)
666 · minitest.utf16 test.utf16
668 Runs the tests with UTF-16 encoded scripts, encoded with different
670 versions of this encoding.
671 "make utest.utf16" runs the test suite with a combination of
673 "-utf8" and "-utf16" arguments to t/TEST.
674 (Not available on Win32)
676 · test_harness
678 Run the test suite with the t/harness controlling program, instead
680 of t/TEST. t/harness is more sophisticated, and uses the
681 Test::Harness module, thus using this test target supposes that
682 perl mostly works. The main advantage for our purposes is that it
683 prints a detailed summary of failed tests at the end. Also, unlike
684 t/TEST, it doesn't redirect stderr to stdout.
685 Note that under Win32 t/harness is always used instead of t/TEST,
687 so there is no special "test_harness" target.
688 Under Win32's "test" target you may use the TEST_SWITCHES and
690 TEST_FILES environment variables to control the behaviour of
691 t/harness. This means you can say
692 nmake test TEST_FILES="op/*.t"
694 nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t"
695 · test-notty test_notty
697 Sets PERL_SKIP_TTY_TEST to true before running normal test.
699 Parallel tests
701 The core distribution can now run its regression tests in parallel on
702 Unix-like platforms. Instead of running "make test", set "TEST_JOBS" in
703 your environment to the number of tests to run in parallel, and run
704 "make test_harness". On a Bourne-like shell, this can be done as
705 TEST_JOBS=3 make test_harness # Run 3 tests in parallel
707 An environment variable is used, rather than parallel make itself,
709 because TAP::Harness needs to be able to schedule individual non-
710 conflicting test scripts itself, and there is no standard interface to
711 "make" utilities to interact with their job schedulers.
712 Note that currently some test scripts may fail when run in parallel
714 (most notably ext/IO/t/io_dir.t). If necessary, run just the failing
715 scripts again sequentially and see if the failures go away.
716 Running tests by hand
718 You can run part of the test suite by hand by using one of the
719 following commands from the t/ directory:
720 ./perl -I../lib TEST list-of-.t-files
722 or
724 ./perl -I../lib harness list-of-.t-files
726 (If you don't specify test scripts, the whole test suite will be run.)
728 Using t/harness for testing
730 If you use "harness" for testing, you have several command line options
731 available to you. The arguments are as follows, and are in the order
732 that they must appear if used together.
733 harness -v -torture -re=pattern LIST OF FILES TO TEST
735 harness -v -torture -re LIST OF PATTERNS TO MATCH
736 If "LIST OF FILES TO TEST" is omitted, the file list is obtained from
738 the manifest. The file list may include shell wildcards which will be
739 expanded out.
740 · -v
742 Run the tests under verbose mode so you can see what tests were
744 run, and debug output.
745 · -torture
747 Run the torture tests as well as the normal set.
749 · -re=PATTERN
751 Filter the file list so that all the test files run match PATTERN.
753 Note that this form is distinct from the -re LIST OF PATTERNS form
754 below in that it allows the file list to be provided as well.
755 · -re LIST OF PATTERNS
757 Filter the file list so that all the test files run match
759 /(LIST|OF|PATTERNS)/. Note that with this form the patterns are
760 joined by '|' and you cannot supply a list of files, instead the
761 test files are obtained from the MANIFEST.
762 You can run an individual test by a command similar to
764 ./perl -I../lib path/to/foo.t
766 except that the harnesses set up some environment variables that may
768 affect the execution of the test:
769 · PERL_CORE=1
771 indicates that we're running this test as part of the perl core
773 test suite. This is useful for modules that have a dual life on
774 CPAN.
775 · PERL_DESTRUCT_LEVEL=2
777 is set to 2 if it isn't set already (see "PERL_DESTRUCT_LEVEL" in
779 perlhacktips).
780 · PERL
782 (used only by t/TEST) if set, overrides the path to the perl
784 executable that should be used to run the tests (the default being
785 ./perl).
786 · PERL_SKIP_TTY_TEST
788 if set, tells to skip the tests that need a terminal. It's actually
790 set automatically by the Makefile, but can also be forced
791 artificially by running 'make test_notty'.
792 Other environment variables that may influence tests
794 · PERL_TEST_Net_Ping
796 Setting this variable runs all the Net::Ping modules tests,
798 otherwise some tests that interact with the outside world are
799 skipped. See perl58delta.
800 · PERL_TEST_NOVREXX
802 Setting this variable skips the vrexx.t tests for OS2::REXX.
804 · PERL_TEST_NUMCONVERTS
806 This sets a variable in op/numconvert.t.
808 See also the documentation for the Test and Test::Harness modules, for
810 more environment variables that affect testing.
811
813 To hack on the Perl guts, you'll need to read the following things:
814 · perlsource
816 An overview of the Perl source tree. This will help you find the
818 files you're looking for.
819 · perlinterp
821 An overview of the Perl interpreter source code and some details on
823 how Perl does what it does.
824 · perlhacktut
826 This document walks through the creation of a small patch to Perl's
828 C code. If you're just getting started with Perl core hacking, this
829 will help you understand how it works.
830 · perlhacktips
832 More details on hacking the Perl core. This document focuses on
834 lower level details such as how to write tests, compilation issues,
835 portability, debugging, etc.
836 If you plan on doing serious C hacking, make sure to read this.
838 · perlguts
840 This is of paramount importance, since it's the documentation of
842 what goes where in the Perl source. Read it over a couple of times
843 and it might start to make sense - don't worry if it doesn't yet,
844 because the best way to study it is to read it in conjunction with
845 poking at Perl source, and we'll do that later on.
846 Gisle Aas's "illustrated perlguts", also known as illguts, has very
848 helpful pictures:
849 <http://search.cpan.org/dist/illguts/>
851 · perlxstut and perlxs
853 A working knowledge of XSUB programming is incredibly useful for
855 core hacking; XSUBs use techniques drawn from the PP code, the
856 portion of the guts that actually executes a Perl program. It's a
857 lot gentler to learn those techniques from simple examples and
858 explanation than from the core itself.
859 · perlapi
861 The documentation for the Perl API explains what some of the
863 internal functions do, as well as the many macros used in the
864 source.
865 · Porting/pumpkin.pod
867 This is a collection of words of wisdom for a Perl porter; some of
869 it is only useful to the pumpkin holder, but most of it applies to
870 anyone wanting to go about Perl development.
871 · The perl5-porters FAQ
873 This should be available from
875 http://dev.perl.org/perl5/docs/p5p-faq.html . It contains hints on
876 reading perl5-porters, information on how perl5-porters works and
877 how Perl development in general works.
878
880 The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers
881 who test CPAN modules on a variety of platforms.
882 Perl Smokers ( http://www.nntp.perl.org/group/perl.daily-build/ and
884 http://www.nntp.perl.org/group/perl.daily-build.reports/ )
885 automatically test Perl source releases on platforms with various
886 configurations.
887 Both efforts welcome volunteers. In order to get involved in smoke
889 testing of the perl itself visit
890 http://search.cpan.org/dist/Test-Smoke/
891 <http://search.cpan.org/dist/Test-Smoke/>. In order to start smoke
892 testing CPAN modules visit
893 http://search.cpan.org/dist/CPANPLUS-YACSmoke/
894 <http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or
895 <http://search.cpan.org/dist/minismokebox/> or
896 http://search.cpan.org/dist/CPAN-Reporter/
897 <http://search.cpan.org/dist/CPAN-Reporter/>.
898
900 If you've read all the documentation in the document and the ones
901 listed above, you're more than ready to hack on Perl.
902 Here's some more recommendations
904 · Subscribe to perl5-porters, follow the patches and try and
906 understand them; don't be afraid to ask if there's a portion you're
907 not clear on - who knows, you may unearth a bug in the patch...
908 · Do read the README associated with your operating system, e.g.
910 README.aix on the IBM AIX OS. Don't hesitate to supply patches to
911 that README if you find anything missing or changed over a new OS
912 release.
913 · Find an area of Perl that seems interesting to you, and see if you
915 can work out how it works. Scan through the source, and step over
916 it in the debugger. Play, poke, investigate, fiddle! You'll
917 probably get to understand not just your chosen area but a much
918 wider range of perl's activity as well, and probably sooner than
919 you'd think.
920 "The Road goes ever on and on, down from the door where it began."
922 If you can do these things, you've started on the long road to Perl
923 porting. Thanks for wanting to help make Perl better - and happy
924 hacking!
925 Metaphoric Quotations
927 If you recognized the quote about the Road above, you're in luck.
928 Most software projects begin each file with a literal description of
930 each file's purpose. Perl instead begins each with a literary allusion
931 to that file's purpose.
932 Like chapters in many books, all top-level Perl source files (along
934 with a few others here and there) begin with an epigrammatic
935 inscription that alludes, indirectly and metaphorically, to the
936 material you're about to read.
937 Quotations are taken from writings of J.R.R. Tolkien pertaining to his
939 Legendarium, almost always from The Lord of the Rings. Chapters and
940 page numbers are given using the following editions:
941 · The Hobbit, by J.R.R. Tolkien. The hardcover, 70th-anniversary
943 edition of 2007 was used, published in the UK by Harper Collins
944 Publishers and in the US by the Houghton Mifflin Company.
945 · The Lord of the Rings, by J.R.R. Tolkien. The hardcover,
947 50th-anniversary edition of 2004 was used, published in the UK by
948 Harper Collins Publishers and in the US by the Houghton Mifflin
949 Company.
950 · The Lays of Beleriand, by J.R.R. Tolkien and published posthumously
952 by his son and literary executor, C.J.R. Tolkien, being the 3rd of
953 the 12 volumes in Christopher's mammoth History of Middle Earth.
954 Page numbers derive from the hardcover edition, first published in
955 1983 by George Allen & Unwin; no page numbers changed for the
956 special 3-volume omnibus edition of 2002 or the various trade-paper
957 editions, all again now by Harper Collins or Houghton Mifflin.
958 Other JRRT books fair game for quotes would thus include The Adventures
960 of Tom Bombadil, The Silmarillion, Unfinished Tales, and The Tale of
961 the Children of Hurin, all but the first posthumously assembled by
962 CJRT. But The Lord of the Rings itself is perfectly fine and probably
963 best to quote from, provided you can find a suitable quote there.
964 So if you were to supply a new, complete, top-level source file to add
966 to Perl, you should conform to this peculiar practice by yourself
967 selecting an appropriate quotation from Tolkien, retaining the original
968 spelling and punctuation and using the same format the rest of the
969 quotes are in. Indirect and oblique is just fine; remember, it's a
970 metaphor, so being meta is, after all, what it's for.
971
973 This document was originally written by Nathan Torkington, and is
974 maintained by the perl5-porters mailing list.
975perl v5.16.3 2013-03-04 PERLHACK(1)