From f7e1e956b6cd2661c1f96b493843e270bfa22aed Mon Sep 17 00:00:00 2001 From: "Michael G. Schwern" Date: Mon, 16 Jul 2001 14:20:31 -0400 Subject: [PATCH] Sections on writing tests & patching core mods Message-Id: <20010716182031.A1128@blackrider> p4raw-id: //depot/perl@11397 --- pod/perlhack.pod | 134 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 118 insertions(+), 16 deletions(-) diff --git a/pod/perlhack.pod b/pod/perlhack.pod index f44036d..3eb44bf 100644 --- a/pod/perlhack.pod +++ b/pod/perlhack.pod @@ -350,7 +350,7 @@ from Andreas K =back -=head3 Why rsync the source tree +=head2 Why rsync the source tree =over 4 @@ -378,7 +378,7 @@ more ... (see Sarathy's remark). =back -=head3 Why rsync the patches +=head2 Why rsync the patches =over 4 @@ -469,20 +469,23 @@ for reference. =head2 Submitting patches -Always submit patches to I. This lets other -porters review your patch, which catches a surprising number of errors -in patches. Either use the diff program (available in source code -form from I), or use Johan Vromans' -I (available from I). Unified diffs -are preferred, but context diffs are accepted. Do not send RCS-style -diffs or diffs without context lines. More information is given in -the I file in the Perl source distribution. -Please patch against the latest B version (e.g., if -you're fixing a bug in the 5.005 track, patch against the latest -5.005_5x version). Only patches that survive the heat of the -development branch get applied to maintenance versions. - -Your patch should update the documentation and test suite. +Always submit patches to I. If you're +patching a core module and there's an author listed, send the author a +copy (see L). This lets other porters review +your patch, which catches a surprising number of errors in patches. +Either use the diff program (available in source code form from +I), or use Johan Vromans' I +(available from I). Unified diffs are preferred, +but context diffs are accepted. Do not send RCS-style diffs or diffs +without context lines. More information is given in the +I file in the Perl source distribution. Please +patch against the latest B version (e.g., if you're +fixing a bug in the 5.005 track, patch against the latest 5.005_5x +version). Only patches that survive the heat of the development +branch get applied to maintenance versions. + +Your patch should update the documentation and test suite. See +L. To report a bug in Perl, use the program I which comes with Perl (if you can't get Perl to work, send mail to the address @@ -570,6 +573,13 @@ Modules shipped as part of the Perl core live in the F and F subdirectories: F is for the pure-Perl modules, and F contains the core XS modules. +=item Tests + +There are tests for nearly all the modules, built-ins and major bits +of functionality. Test files all have a .t suffix. Module tests live +in the F and F directories next to the module being +tested. Others live in F. See L + =item Documentation Documentation maintenance includes looking after everything in the @@ -1535,6 +1545,98 @@ We end up with a patch looking a little like this: And finally, we submit it, with our rationale, to perl5-porters. Job done! +=head2 Patching a core module + +This works just like patching anything else, with an extra +consideration. Many core modules also live on CPAN. If this is so, +patch the CPAN version instead of the core and send the patch off to +the module maintainer (with a copy to p5p). This will help the module +maintainer keep the CPAN version in sync with the core version without +constantly scanning p5p. + + +=head2 Writing a test + +Every module and built-in function has an associated test file (or +should...). If you add or change functionality, you have to write a +test. If you fix a bug, you have to write a test so that bug never +comes back. If you alter the docs, it would be nice to test what the +new documentation says. + +In short, if you submit a patch you probably also have to patch the +tests. + +For modules, the test file is right next to the module itself. +F tests F. This is a recent innovation, +so there are some snags (and it would be wonderful for you to brush +them out), but it basically works that way. Everything else lives in +F. + +=over 3 + +=item F + +Testing of the absolute basic functionality of Perl. Things like +C, basic file reads and writes, simple regexes, etc. These are +run first in the test suite and if any of them fail, something is +I broken. + +=item F + +These test the basic control structures, C, C, +subroutines, etc... + +=item F + +Tests basic issues of how Perl parses and compiles itself. + +=item F + +Tests for built-in IO functions, including command line arguments. + +=item F + +The old home for the module tests, you shouldn't put anything new in +here. There are still some bits and pieces hanging around in here +that need to be moved. Perhaps you could move them? Thanks! + +=item F + +Tests for perl's built in functions that don't fit into any of the +other directories. + +=item F + +Tests for POD directives. There are still some tests for the Pod +modules hanging around in here that need to be moved out into F. + +=item F + +Testing features of how perl actually runs, including exit codes and +handling of PERL* environment variables. + +=back + +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. + +For most libraries and extensions, you'll want to use the Test::More +library rather than rolling your own test functions. If a module test +doesn't use Test::More, consider rewriting it so it does. For the +rest its best to use a simple C style to avoid +broken core functionality from causing the whole test to collapse. + +When you say "make test" Perl uses the F program to run the +test suite. All tests are run from the F directory, B the +directory which contains the test. This causes some problems with the +tests in F, so here's some opportunity for some patching. + +You must be triply conscious of cross-platform concerns. This usually +boils down to using File::Spec and avoiding things like C and +C unless absolutely necessary. + + =head1 EXTERNAL TOOLS FOR DEBUGGING PERL Sometimes it helps to use external tools while debugging and -- 2.7.4