diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlhack.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlhack.pod | 1144 |
1 files changed, 0 insertions, 1144 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlhack.pod b/Master/tlpkg/tlperl/lib/pods/perlhack.pod deleted file mode 100644 index 63df5d5dfc3..00000000000 --- a/Master/tlpkg/tlperl/lib/pods/perlhack.pod +++ /dev/null @@ -1,1144 +0,0 @@ -=encoding utf8 - -=for comment -Consistent formatting of this file is achieved with: - perl ./Porting/podtidy pod/perlhack.pod - -=head1 NAME - -perlhack - How to hack on Perl - -=head1 DESCRIPTION - -This document explains how Perl development works. It includes details -about the Perl 5 Porters email list, the Perl repository, the Perlbug -bug tracker, patch guidelines, and commentary on Perl development -philosophy. - -=head1 SUPER QUICK PATCH GUIDE - -If you just want to submit a single small patch like a pod fix, a test -for a bug, comment fixes, etc., it's easy! Here's how: - -=over 4 - -=item * Check out the source repository - -The perl source is in a git repository. You can clone the repository -with the following command: - - % git clone git://perl5.git.perl.org/perl.git perl - -=item * Make your change - -Hack, hack, hack. - -=item * Test your change - -You can run all the tests with the following commands: - - % ./Configure -des -Dusedevel - % make test - -Keep hacking until the tests pass. - -=item * Commit your change - -Committing your work will save the change I<on your local system>: - - % git commit -a -m 'Commit message goes here' - -Make sure the commit message describes your change in a single -sentence. For example, "Fixed spelling errors in perlhack.pod". - -=item * Send your change to perlbug - -The next step is to submit your patch to the Perl core ticket system -via email. - -Assuming your patch consists of a single git commit, the following -writes the file as a MIME attachment, and sends it with a meaningful -subject: - - % git format-patch -1 --attach - % perlbug -s "[PATCH] $(git log -1 --oneline HEAD)" -f 0001-*.patch - -The perlbug program will ask you a few questions about your email -address and the patch you're submitting. Once you've answered them it -will submit your patch via email. - -=item * Thank you - -The porters appreciate the time you spent helping to make Perl better. -Thank you! - -=back - -=head1 BUG REPORTING - -If you want to report a bug in Perl, you must use the F<perlbug> -command line tool. This tool will ensure that your bug report includes -all the relevant system and configuration information. - -To browse existing Perl bugs and patches, you can use the web interface -at L<http://rt.perl.org/>. - -Please check the archive of the perl5-porters list (see below) and/or -the bug tracking system before submitting a bug report. Often, you'll -find that the bug has been reported already. - -You can log in to the bug tracking system and comment on existing bug -reports. If you have additional information regarding an existing bug, -please add it. This will help the porters fix the bug. - -=head1 PERL 5 PORTERS - -The perl5-porters (p5p) mailing list is where the Perl standard -distribution is maintained and developed. The people who maintain Perl -are also referred to as the "Perl 5 Porters", "p5p" or just the -"porters". - -A searchable archive of the list is available at -L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is -also another archive at -L<http://archive.develooper.com/perl5-porters@perl.org/>. - -=head2 perl-changes mailing list - -The perl5-changes mailing list receives a copy of each patch that gets -submitted to the maintenance and development branches of the perl -repository. See L<http://lists.perl.org/list/perl5-changes.html> for -subscription and archive information. - -=head2 #p5p on IRC - -Many porters are also active on the L<irc://irc.perl.org/#p5p> channel. -Feel free to join the channel and ask questions about hacking on the -Perl core. - -=head1 GETTING THE PERL SOURCE - -All of Perl's source code is kept centrally in a Git repository at -I<perl5.git.perl.org>. The repository contains many Perl revisions from -Perl 1 onwards and all the revisions from Perforce, the previous -version control system. - -For much more detail on using git with the Perl repository, please see -L<perlgit>. - -=head2 Read access via Git - -You will need a copy of Git for your computer. You can fetch a copy of -the repository using the git protocol: - - % git clone git://perl5.git.perl.org/perl.git perl - -This clones the repository and makes a local copy in the F<perl> -directory. - -If you cannot use the git protocol for firewall reasons, you can also -clone via http, though this is much slower: - - % git clone http://perl5.git.perl.org/perl.git perl - -=head2 Read access via the web - -You may access the repository over the web. This allows you to browse -the tree, see recent commits, subscribe to RSS feeds for the changes, -search for particular commits and more. You may access it at -L<http://perl5.git.perl.org/perl.git>. A mirror of the repository is -found at L<http://github.com/mirrors/perl>. - -=head2 Read access via rsync - -You can also choose to use rsync to get a copy of the current source -tree for the bleadperl branch and all maintenance branches: - - % rsync -avz rsync://perl5.git.perl.org/perl-current . - % rsync -avz rsync://perl5.git.perl.org/perl-5.12.x . - % rsync -avz rsync://perl5.git.perl.org/perl-5.10.x . - % rsync -avz rsync://perl5.git.perl.org/perl-5.8.x . - % rsync -avz rsync://perl5.git.perl.org/perl-5.6.x . - % rsync -avz rsync://perl5.git.perl.org/perl-5.005xx . - -(Add the C<--delete> option to remove leftover files.) - -To get a full list of the available sync points: - - % rsync perl5.git.perl.org:: - -=head2 Write access via git - -If you have a commit bit, please see L<perlgit> for more details on -using git. - -=head1 PATCHING PERL - -If you're planning to do more extensive work than a single small fix, -we encourage you to read the documentation below. This will help you -focus your work and make your patches easier to incorporate into the -Perl source. - -=head2 Submitting patches - -If you have a small patch to submit, please submit it via perlbug. You -can also send email directly to perlbug@perl.org. Please note that -messages sent to perlbug may be held in a moderation queue, so you -won't receive a response immediately. - -You'll know your submission has been processed when you receive an -email from our ticket tracking system. This email will give you a -ticket number. Once your patch has made it to the ticket tracking -system, it will also be sent to the perl5-porters@perl.org list. - -Patches are reviewed and discussed on the p5p list. Simple, -uncontroversial patches will usually be applied without any discussion. -When the patch is applied, the ticket will be updated and you will -receive email. In addition, an email will be sent to the p5p list. - -In other cases, the patch will need more work or discussion. That will -happen on the p5p list. - -You are encouraged to participate in the discussion and advocate for -your patch. Sometimes your patch may get lost in the shuffle. It's -appropriate to send a reminder email to p5p if no action has been taken -in a month. Please remember that the Perl 5 developers are all -volunteers, and be polite. - -Changes are always applied directly to the main development branch, -called "blead". Some patches may be backported to a maintenance branch. -If you think your patch is appropriate for the maintenance branch, -please explain why when you submit it. - -=head2 Getting your patch accepted - -If you are submitting a code patch there are several things that you -can do to help the Perl 5 Porters accept your patch. - -=head3 Patch style - -If you used git to check out the Perl source, then using C<git -format-patch> will produce a patch in a style suitable for Perl. The -C<format-patch> command produces one patch file for each commit you -made. If you prefer to send a single patch for all commits, you can use -C<git diff>. - - % git checkout blead - % git pull - % git diff blead my-branch-name - -This produces a patch based on the difference between blead and your -current branch. It's important to make sure that blead is up to date -before producing the diff, that's why we call C<git pull> first. - -We strongly recommend that you use git if possible. It will make your -life easier, and ours as well. - -However, if you're not using git, you can still produce a suitable -patch. You'll need a pristine copy of the Perl source to diff against. -The porters prefer unified diffs. Using GNU C<diff>, you can produce a -diff like this: - - % diff -Npurd perl.pristine perl.mine - -Make sure that you C<make realclean> in your copy of Perl to remove any -build artifacts, or you may get a confusing result. - -=head3 Commit message - -As you craft each patch you intend to submit to the Perl core, it's -important to write a good commit message. This is especially important -if your submission will consist of a series of commits. - -The first line of the commit message should be a short description -without a period. It should be no longer than the subject line of an -email, 50 characters being a good rule of thumb. - -A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will -only display the first line (cut off at 50 characters) when presenting -commit summaries. - -The commit message should include a description of the problem that the -patch corrects or new functionality that the patch adds. - -As a general rule of thumb, your commit message should help a -programmer who knows the Perl core quickly understand what you were -trying to do, how you were trying to do it, and why the change matters -to Perl. - -=over 4 - -=item * Why - -Your commit message should describe why the change you are making is -important. When someone looks at your change in six months or six -years, your intent should be clear. - -If you're deprecating a feature with the intent of later simplifying -another bit of code, say so. If you're fixing a performance problem or -adding a new feature to support some other bit of the core, mention -that. - -=item * What - -Your commit message should describe what part of the Perl core you're -changing and what you expect your patch to do. - -=item * How - -While it's not necessary for documentation changes, new tests or -trivial patches, it's often worth explaining how your change works. -Even if it's clear to you today, it may not be clear to a porter next -month or next year. - -=back - -A commit message isn't intended to take the place of comments in your -code. Commit messages should describe the change you made, while code -comments should describe the current state of the code. - -If you've just implemented a new feature, complete with doc, tests and -well-commented code, a brief commit message will often suffice. If, -however, you've just changed a single character deep in the parser or -lexer, you might need to write a small novel to ensure that future -readers understand what you did and why you did it. - -=head3 Comments, Comments, Comments - -Be sure to adequately comment your code. While commenting every line is -unnecessary, anything that takes advantage of side effects of -operators, that creates changes that will be felt outside of the -function being patched, or that others may find confusing should be -documented. If you are going to err, it is better to err on the side of -adding too many comments than too few. - -The best comments explain I<why> the code does what it does, not I<what -it does>. - -=head3 Style - -In general, please follow the particular style of the code you are -patching. - -In particular, follow these general guidelines for patching Perl -sources: - -=over 4 - -=item * - -8-wide tabs (no exceptions!) - -=item * - -4-wide indents for code, 2-wide indents for nested CPP #defines - -=item * - -Try hard not to exceed 79-columns - -=item * - -ANSI C prototypes - -=item * - -Uncuddled elses and "K&R" style for indenting control constructs - -=item * - -No C++ style (//) comments - -=item * - -Mark places that need to be revisited with XXX (and revisit often!) - -=item * - -Opening brace lines up with "if" when conditional spans multiple lines; -should be at end-of-line otherwise - -=item * - -In function definitions, name starts in column 0 (return value is on -previous line) - -=item * - -Single space after keywords that are followed by parens, no space -between function name and following paren - -=item * - -Avoid assignments in conditionals, but if they're unavoidable, use -extra paren, e.g. "if (a && (b = c)) ..." - -=item * - -"return foo;" rather than "return(foo);" - -=item * - -"if (!foo) ..." rather than "if (foo == FALSE) ..." etc. - -=back - -=head3 Test suite - -If your patch changes code (rather than just changing documentation), -you should also include one or more test cases which illustrate the bug -you're fixing or validate the new functionality you're adding. In -general, you should update an existing test file rather than create a -new one. - -Your test suite additions should generally follow these guidelines -(courtesy of Gurusamy Sarathy <gsar@activestate.com>): - -=over 4 - -=item * - -Know what you're testing. Read the docs, and the source. - -=item * - -Tend to fail, not succeed. - -=item * - -Interpret results strictly. - -=item * - -Use unrelated features (this will flush out bizarre interactions). - -=item * - -Use non-standard idioms (otherwise you are not testing TIMTOWTDI). - -=item * - -Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT -found in t/op/tie.t is much more maintainable, and gives better failure -reports). - -=item * - -Give meaningful error messages when a test fails. - -=item * - -Avoid using qx// and system() unless you are testing for them. If you -do use them, make sure that you cover _all_ perl platforms. - -=item * - -Unlink any temporary files you create. - -=item * - -Promote unforeseen warnings to errors with $SIG{__WARN__}. - -=item * - -Be sure to use the libraries and modules shipped with the version being -tested, not those that were already installed. - -=item * - -Add comments to the code explaining what you are testing for. - -=item * - -Make updating the '1..42' string unnecessary. Or make sure that you -update it. - -=item * - -Test _all_ behaviors of a given operator, library, or function. - -Test all optional arguments. - -Test return values in various contexts (boolean, scalar, list, lvalue). - -Use both global and lexical variables. - -Don't forget the exceptional, pathological cases. - -=back - -=head2 Patching a core module - -This works just like patching anything else, with one extra -consideration. - -Modules in the F<cpan/> directory of the source tree are maintained -outside of the Perl core. When the author updates the module, the -updates are simply copied into the core. See that module's -documentation or its listing on L<http://search.cpan.org/> for more -information on reporting bugs and submitting patches. - -In most cases, patches to modules in F<cpan/> should be sent upstream -and should not be applied to the Perl core individually. If a patch to -a file in F<cpan/> absolutely cannot wait for the fix to be made -upstream, released to CPAN and copied to blead, you must add (or -update) a C<CUSTOMIZED> entry in the F<"Porting/Maintainers.pl"> file -to flag that a local modification has been made. See -F<"Porting/Maintainers.pl"> for more details. - -In contrast, modules in the F<dist/> directory are maintained in the -core. - -=head2 Updating perldelta - -For changes significant enough to warrant a F<pod/perldelta.pod> entry, -the porters will greatly appreciate it if you submit a delta entry -along with your actual change. Significant changes include, but are not -limited to: - -=over 4 - -=item * - -Adding, deprecating, or removing core features - -=item * - -Adding, deprecating, removing, or upgrading core or dual-life modules - -=item * - -Adding new core tests - -=item * - -Fixing security issues and user-visible bugs in the core - -=item * - -Changes that might break existing code, either on the perl or C level - -=item * - -Significant performance improvements - -=item * - -Adding, removing, or significantly changing documentation in the -F<pod/> directory - -=item * - -Important platform-specific changes - -=back - -Please make sure you add the perldelta entry to the right section -within F<pod/perldelta.pod>. More information on how to write good -perldelta entries is available in the C<Style> section of -F<Porting/how_to_write_a_perldelta.pod>. - -=head2 What makes for a good patch? - -New features and extensions to the language can be contentious. There -is no specific set of criteria which determine what features get added, -but here are some questions to consider when developing a patch: - -=head3 Does the concept match the general goals of Perl? - -Our goals include, but are not limited to: - -=over 4 - -=item 1. - -Keep it fast, simple, and useful. - -=item 2. - -Keep features/concepts as orthogonal as possible. - -=item 3. - -No arbitrary limits (platforms, data sizes, cultures). - -=item 4. - -Keep it open and exciting to use/patch/advocate Perl everywhere. - -=item 5. - -Either assimilate new technologies, or build bridges to them. - -=back - -=head3 Where is the implementation? - -All the talk in the world is useless without an implementation. In -almost every case, the person or people who argue for a new feature -will be expected to be the ones who implement it. Porters capable of -coding new features have their own agendas, and are not available to -implement your (possibly good) idea. - -=head3 Backwards compatibility - -It's a cardinal sin to break existing Perl programs. New warnings can -be contentious--some say that a program that emits warnings is not -broken, while others say it is. Adding keywords has the potential to -break programs, changing the meaning of existing token sequences or -functions might break programs. - -The Perl 5 core includes mechanisms to help porters make backwards -incompatible changes more compatible such as the L<feature> and -L<deprecate> modules. Please use them when appropriate. - -=head3 Could it be a module instead? - -Perl 5 has extension mechanisms, modules and XS, specifically to avoid -the need to keep changing the Perl interpreter. You can write modules -that export functions, you can give those functions prototypes so they -can be called like built-in functions, you can even write XS code to -mess with the runtime data structures of the Perl interpreter if you -want to implement really complicated things. - -Whenever possible, new features should be prototyped in a CPAN module -before they will be considered for the core. - -=head3 Is the feature generic enough? - -Is this something that only the submitter wants added to the language, -or is it broadly useful? Sometimes, instead of adding a feature with a -tight focus, the porters might decide to wait until someone implements -the more generalized feature. - -=head3 Does it potentially introduce new bugs? - -Radical rewrites of large chunks of the Perl interpreter have the -potential to introduce new bugs. - -=head3 How big is it? - -The smaller and more localized the change, the better. Similarly, a -series of small patches is greatly preferred over a single large patch. - -=head3 Does it preclude other desirable features? - -A patch is likely to be rejected if it closes off future avenues of -development. For instance, a patch that placed a true and final -interpretation on prototypes is likely to be rejected because there are -still options for the future of prototypes that haven't been addressed. - -=head3 Is the implementation robust? - -Good patches (tight code, complete, correct) stand more chance of going -in. Sloppy or incorrect patches might be placed on the back burner -until the pumpking has time to fix, or might be discarded altogether -without further notice. - -=head3 Is the implementation generic enough to be portable? - -The worst patches make use of system-specific features. It's highly -unlikely that non-portable additions to the Perl language will be -accepted. - -=head3 Is the implementation tested? - -Patches which change behaviour (fixing bugs or introducing new -features) must include regression tests to verify that everything works -as expected. - -Without tests provided by the original author, how can anyone else -changing perl in the future be sure that they haven't unwittingly -broken the behaviour the patch implements? And without tests, how can -the patch's author be confident that his/her hard work put into the -patch won't be accidentally thrown away by someone in the future? - -=head3 Is there enough documentation? - -Patches without documentation are probably ill-thought out or -incomplete. No features can be added or changed without documentation, -so submitting a patch for the appropriate pod docs as well as the -source code is important. - -=head3 Is there another way to do it? - -Larry said "Although the Perl Slogan is I<There's More Than One Way to -Do It>, I hesitate to make 10 ways to do something". This is a tricky -heuristic to navigate, though--one man's essential addition is another -man's pointless cruft. - -=head3 Does it create too much work? - -Work for the pumpking, work for Perl programmers, work for module -authors, ... Perl is supposed to be easy. - -=head3 Patches speak louder than words - -Working code is always preferred to pie-in-the-sky ideas. A patch to -add a feature stands a much higher chance of making it to the language -than does a random feature request, no matter how fervently argued the -request might be. This ties into "Will it be useful?", as the fact that -someone took the time to make the patch demonstrates a strong desire -for the feature. - -=head1 TESTING - -The core uses the same testing style as the rest of Perl, a simple -"ok/not ok" run through Test::Harness, but there are a few special -considerations. - -There are three ways to write a test in the core. L<Test::More>, -F<t/test.pl> and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">. The -decision of which to use depends on what part of the test suite you're -working on. This is a measure to prevent a high-level failure (such as -Config.pm breaking) from causing basic functionality tests to fail. - -The F<t/test.pl> library provides some of the features of -L<Test::More>, but avoids loading most modules and uses as few core -features as possible. - -If you write your own test, use the L<Test Anything -Protocol|http://testanything.org>. - -=over 4 - -=item * F<t/base> and F<t/comp> - -Since we don't know if require works, or even subroutines, use ad hoc -tests for these two. Step carefully to avoid using the feature being -tested. - -=item * F<t/cmd>, F<t/run>, F<t/io> and F<t/op> - -Now that basic require() and subroutines are tested, you can use the -F<t/test.pl> library. - -You can also use certain libraries like Config conditionally, but be -sure to skip the test gracefully if it's not there. - -=item * Everything else - -Now that the core of Perl is tested, L<Test::More> can and should be -used. You can also use the full suite of core modules in the tests. - -=back - -When you say "make test", Perl uses the F<t/TEST> program to run the -test suite (except under Win32 where it uses F<t/harness> instead). All -tests are run from the F<t/> directory, B<not> the directory which -contains the test. This causes some problems with the tests in F<lib/>, -so here's some opportunity for some patching. - -You must be triply conscious of cross-platform concerns. This usually -boils down to using L<File::Spec> and avoiding things like C<fork()> -and C<system()> unless absolutely necessary. - -=head2 Special C<make test> targets - -There are various special make targets that can be used to test Perl -slightly differently than the standard "test" target. Not all them are -expected to give a 100% success rate. Many of them have several -aliases, and many of them are not available on certain operating -systems. - -=over 4 - -=item * test_porting - -This runs some basic sanity tests on the source tree and helps catch -basic errors before you submit a patch. - -=item * coretest - -Run F<perl> on all core tests (F<t/*> and F<lib/[a-z]*> pragma tests). - -(Not available on Win32) - -=item * test.deparse - -Run all the tests through L<B::Deparse>. Not all tests will succeed. - -(Not available on Win32) - -=item * test.taintwarn - -Run all tests with the B<-t> command-line switch. Not all tests are -expected to succeed (until they're specifically fixed, of course). - -(Not available on Win32) - -=item * minitest - -Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>, -F<t/op>, F<t/uni> and F<t/mro> tests. - -=item * test.valgrind check.valgrind utest.valgrind ucheck.valgrind - -(Only in Linux) Run all the tests using the memory leak + naughty -memory access tool "valgrind". The log files will be named -F<testname.valgrind>. - -=item * test.torture torturetest - -Run all the usual tests and some extra tests. As of Perl 5.8.0, the -only extra tests are Abigail's JAPHs, F<t/japh/abigail.t>. - -You can also run the torture test with F<t/harness> by giving -C<-torture> argument to F<t/harness>. - -=item * utest ucheck test.utf8 check.utf8 - -Run all the tests with -Mutf8. Not all tests will succeed. - -(Not available on Win32) - -=item * minitest.utf16 test.utf16 - -Runs the tests with UTF-16 encoded scripts, encoded with different -versions of this encoding. - -C<make utest.utf16> runs the test suite with a combination of C<-utf8> -and C<-utf16> arguments to F<t/TEST>. - -(Not available on Win32) - -=item * test_harness - -Run the test suite with the F<t/harness> controlling program, instead -of F<t/TEST>. F<t/harness> is more sophisticated, and uses the -L<Test::Harness> module, thus using this test target supposes that perl -mostly works. The main advantage for our purposes is that it prints a -detailed summary of failed tests at the end. Also, unlike F<t/TEST>, it -doesn't redirect stderr to stdout. - -Note that under Win32 F<t/harness> is always used instead of F<t/TEST>, -so there is no special "test_harness" target. - -Under Win32's "test" target you may use the TEST_SWITCHES and -TEST_FILES environment variables to control the behaviour of -F<t/harness>. This means you can say - - nmake test TEST_FILES="op/*.t" - nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t" - -=item * test-notty test_notty - -Sets PERL_SKIP_TTY_TEST to true before running normal test. - -=back - -=head2 Parallel tests - -The core distribution can now run its regression tests in parallel on -Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> -in your environment to the number of tests to run in parallel, and run -C<make test_harness>. On a Bourne-like shell, this can be done as - - TEST_JOBS=3 make test_harness # Run 3 tests in parallel - -An environment variable is used, rather than parallel make itself, -because L<TAP::Harness> needs to be able to schedule individual -non-conflicting test scripts itself, and there is no standard interface -to C<make> utilities to interact with their job schedulers. - -Note that currently some test scripts may fail when run in parallel -(most notably F<ext/IO/t/io_dir.t>). If necessary, run just the failing -scripts again sequentially and see if the failures go away. - -=head2 Running tests by hand - -You can run part of the test suite by hand by using one of the -following commands from the F<t/> directory: - - ./perl -I../lib TEST list-of-.t-files - -or - - ./perl -I../lib harness list-of-.t-files - -(If you don't specify test scripts, the whole test suite will be run.) - -=head2 Using F<t/harness> for testing - -If you use C<harness> for testing, you have several command line -options available to you. The arguments are as follows, and are in the -order that they must appear if used together. - - harness -v -torture -re=pattern LIST OF FILES TO TEST - harness -v -torture -re LIST OF PATTERNS TO MATCH - -If C<LIST OF FILES TO TEST> is omitted, the file list is obtained from -the manifest. The file list may include shell wildcards which will be -expanded out. - -=over 4 - -=item * -v - -Run the tests under verbose mode so you can see what tests were run, -and debug output. - -=item * -torture - -Run the torture tests as well as the normal set. - -=item * -re=PATTERN - -Filter the file list so that all the test files run match PATTERN. Note -that this form is distinct from the B<-re LIST OF PATTERNS> form below -in that it allows the file list to be provided as well. - -=item * -re LIST OF PATTERNS - -Filter the file list so that all the test files run match -/(LIST|OF|PATTERNS)/. Note that with this form the patterns are joined -by '|' and you cannot supply a list of files, instead the test files -are obtained from the MANIFEST. - -=back - -You can run an individual test by a command similar to - - ./perl -I../lib path/to/foo.t - -except that the harnesses set up some environment variables that may -affect the execution of the test: - -=over 4 - -=item * PERL_CORE=1 - -indicates that we're running this test as part of the perl core test -suite. This is useful for modules that have a dual life on CPAN. - -=item * PERL_DESTRUCT_LEVEL=2 - -is set to 2 if it isn't set already (see -L<perlhacktips/PERL_DESTRUCT_LEVEL>). - -=item * PERL - -(used only by F<t/TEST>) if set, overrides the path to the perl -executable that should be used to run the tests (the default being -F<./perl>). - -=item * PERL_SKIP_TTY_TEST - -if set, tells to skip the tests that need a terminal. It's actually set -automatically by the Makefile, but can also be forced artificially by -running 'make test_notty'. - -=back - -=head3 Other environment variables that may influence tests - -=over 4 - -=item * PERL_TEST_Net_Ping - -Setting this variable runs all the Net::Ping modules tests, otherwise -some tests that interact with the outside world are skipped. See -L<perl58delta>. - -=item * PERL_TEST_NOVREXX - -Setting this variable skips the vrexx.t tests for OS2::REXX. - -=item * PERL_TEST_NUMCONVERTS - -This sets a variable in op/numconvert.t. - -=back - -See also the documentation for the Test and Test::Harness modules, for -more environment variables that affect testing. - -=head1 MORE READING FOR GUTS HACKERS - -To hack on the Perl guts, you'll need to read the following things: - -=over 4 - -=item * L<perlsource> - -An overview of the Perl source tree. This will help you find the files -you're looking for. - -=item * L<perlinterp> - -An overview of the Perl interpreter source code and some details on how -Perl does what it does. - -=item * L<perlhacktut> - -This document walks through the creation of a small patch to Perl's C -code. If you're just getting started with Perl core hacking, this will -help you understand how it works. - -=item * L<perlhacktips> - -More details on hacking the Perl core. This document focuses on lower -level details such as how to write tests, compilation issues, -portability, debugging, etc. - -If you plan on doing serious C hacking, make sure to read this. - -=item * L<perlguts> - -This is of paramount importance, since it's the documentation of what -goes where in the Perl source. Read it over a couple of times and it -might start to make sense - don't worry if it doesn't yet, because the -best way to study it is to read it in conjunction with poking at Perl -source, and we'll do that later on. - -Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very -helpful pictures: - -L<http://search.cpan.org/dist/illguts/> - -=item * L<perlxstut> and L<perlxs> - -A working knowledge of XSUB programming is incredibly useful for core -hacking; XSUBs use techniques drawn from the PP code, the portion of -the guts that actually executes a Perl program. It's a lot gentler to -learn those techniques from simple examples and explanation than from -the core itself. - -=item * L<perlapi> - -The documentation for the Perl API explains what some of the internal -functions do, as well as the many macros used in the source. - -=item * F<Porting/pumpkin.pod> - -This is a collection of words of wisdom for a Perl porter; some of it -is only useful to the pumpkin holder, but most of it applies to anyone -wanting to go about Perl development. - -=item * The perl5-porters FAQ - -This should be available from -http://dev.perl.org/perl5/docs/p5p-faq.html . It contains hints on -reading perl5-porters, information on how perl5-porters works and how -Perl development in general works. - -=back - -=head1 CPAN TESTERS AND PERL SMOKERS - -The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers -who test CPAN modules on a variety of platforms. - -Perl Smokers ( http://www.nntp.perl.org/group/perl.daily-build/ and -http://www.nntp.perl.org/group/perl.daily-build.reports/ ) -automatically test Perl source releases on platforms with various -configurations. - -Both efforts welcome volunteers. In order to get involved in smoke -testing of the perl itself visit -L<http://search.cpan.org/dist/Test-Smoke/>. In order to start smoke -testing CPAN modules visit -L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or -L<http://search.cpan.org/dist/minismokebox/> or -L<http://search.cpan.org/dist/CPAN-Reporter/>. - -=head1 WHAT NEXT? - -If you've read all the documentation in the document and the ones -listed above, you're more than ready to hack on Perl. - -Here's some more recommendations - -=over 4 - -=item * - -Subscribe to perl5-porters, follow the patches and try and understand -them; don't be afraid to ask if there's a portion you're not clear on - -who knows, you may unearth a bug in the patch... - -=item * - -Do read the README associated with your operating system, e.g. -README.aix on the IBM AIX OS. Don't hesitate to supply patches to that -README if you find anything missing or changed over a new OS release. - -=item * - -Find an area of Perl that seems interesting to you, and see if you can -work out how it works. Scan through the source, and step over it in the -debugger. Play, poke, investigate, fiddle! You'll probably get to -understand not just your chosen area but a much wider range of -F<perl>'s activity as well, and probably sooner than you'd think. - -=back - -=head2 "The Road goes ever on and on, down from the door where it began." - -If you can do these things, you've started on the long road to Perl -porting. Thanks for wanting to help make Perl better - and happy -hacking! - -=head2 Metaphoric Quotations - -If you recognized the quote about the Road above, you're in luck. - -Most software projects begin each file with a literal description of -each file's purpose. Perl instead begins each with a literary allusion -to that file's purpose. - -Like chapters in many books, all top-level Perl source files (along -with a few others here and there) begin with an epigrammatic -inscription that alludes, indirectly and metaphorically, to the -material you're about to read. - -Quotations are taken from writings of J.R.R. Tolkien pertaining to his -Legendarium, almost always from I<The Lord of the Rings>. Chapters and -page numbers are given using the following editions: - -=over 4 - -=item * - -I<The Hobbit>, by J.R.R. Tolkien. The hardcover, 70th-anniversary -edition of 2007 was used, published in the UK by Harper Collins -Publishers and in the US by the Houghton Mifflin Company. - -=item * - -I<The Lord of the Rings>, by J.R.R. Tolkien. The hardcover, -50th-anniversary edition of 2004 was used, published in the UK by -Harper Collins Publishers and in the US by the Houghton Mifflin -Company. - -=item * - -I<The Lays of Beleriand>, by J.R.R. Tolkien and published posthumously -by his son and literary executor, C.J.R. Tolkien, being the 3rd of the -12 volumes in Christopher's mammoth I<History of Middle Earth>. Page -numbers derive from the hardcover edition, first published in 1983 by -George Allen & Unwin; no page numbers changed for the special 3-volume -omnibus edition of 2002 or the various trade-paper editions, all again -now by Harper Collins or Houghton Mifflin. - -=back - -Other JRRT books fair game for quotes would thus include I<The -Adventures of Tom Bombadil>, I<The Silmarillion>, I<Unfinished Tales>, -and I<The Tale of the Children of Hurin>, all but the first -posthumously assembled by CJRT. But I<The Lord of the Rings> itself is -perfectly fine and probably best to quote from, provided you can find a -suitable quote there. - -So if you were to supply a new, complete, top-level source file to add -to Perl, you should conform to this peculiar practice by yourself -selecting an appropriate quotation from Tolkien, retaining the original -spelling and punctuation and using the same format the rest of the -quotes are in. Indirect and oblique is just fine; remember, it's a -metaphor, so being meta is, after all, what it's for. - -=head1 AUTHOR - -This document was originally written by Nathan Torkington, and is -maintained by the perl5-porters mailing list. - |