X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlhack.pod;h=f0b2ead4d1f5e0de0629ff733d325c97b668b60e;hb=6168cf9995a8bfcfe4ab9350ebc7de70215ae9af;hp=ffe81671e80e77a540ef456e71c47e9c353493e3;hpb=287a822c675abc6308357941862beda584b38a68;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlhack.pod b/pod/perlhack.pod index ffe8167..f0b2ead 100644 --- a/pod/perlhack.pod +++ b/pod/perlhack.pod @@ -38,12 +38,14 @@ releases of Perl are shepherded by a ``pumpking'', a porter responsible for gathering patches, deciding on a patch-by-patch feature-by-feature basis what will and will not go into the release. For instance, Gurusamy Sarathy was the pumpking for the 5.6 release of -Perl, and Jarkko Hietaniemi is the pumpking for the 5.8 release, and -Hugo van der Sanden will be the pumpking for the 5.10 release. +Perl, and Jarkko Hietaniemi was the pumpking for the 5.8 release, and +Hugo van der Sanden and Rafael Garcia-Suarez share the pumpking for +the 5.10 release. In addition, various people are pumpkings for different things. For -instance, Andy Dougherty and Jarkko Hietaniemi share the I -pumpkin. +instance, Andy Dougherty and Jarkko Hietaniemi did a grand job as the +I pumpkin up till the 5.8 release. For the 5.10 release +H.Merijn Brand took over. Larry sees Perl development along the lines of the US government: there's the Legislature (the porters), the Executive branch (the @@ -479,64 +481,111 @@ for reference. =back +=head2 Working with the source + +Because you cannot use the Perforce client, you cannot easily generate +diffs against the repository, nor will merges occur when you update +via rsync. If you edit a file locally and then rsync against the +latest source, changes made in the remote copy will I your +local versions! + +The best way to deal with this is to maintain a tree of symlinks to +the rsync'd source. Then, when you want to edit a file, you remove +the symlink, copy the real file into the other tree, and edit it. You +can then diff your edited file against the original to generate a +patch, and you can safely update the original tree. + +Perl's F script can generate this tree of symlinks for you. +The following example assumes that you have used rsync to pull a copy +of the Perl source into the F directory. In the directory +above that one, you can execute the following commands: + + mkdir perl-dev + cd perl-dev + ../perl-rsync/Configure -Dmksymlinks -Dusedevel -D"optimize=-g" + +This will start the Perl configuration process. After a few prompts, +you should see something like this: + + Symbolic links are supported. + + Checking how to test for symbolic links... + Your builtin 'test -h' may be broken. + Trying external '/usr/bin/test -h'. + You can test for symbolic links with '/usr/bin/test -h'. + + Creating the symbolic links... + (First creating the subdirectories...) + (Then creating the symlinks...) + +The specifics may vary based on your operating system, of course. +After you see this, you can abort the F script, and you +will see that the directory you are in has a tree of symlinks to the +F directories and files. + +If you plan to do a lot of work with the Perl source, here are some +Bourne shell script functions that can make your life easier: + + function edit { + if [ -L $1 ]; then + mv $1 $1.orig + cp $1.orig $1 + vi $1 + else + /bin/vi $1 + fi + } -=head2 Perlbug remote interface - -There are three (3) remote administrative interfaces for modifying bug -status, category, etc. In all cases an admin must be first registered -with the Perlbug database by sending an email request to -richard@perl.org or bugmongers@perl.org. - -The main requirement is the willingness to classify, (with the -emphasis on closing where possible :), outstanding bugs. Further -explanation can be garnered from the web at http://bugs.perl.org/ , or -by asking on the admin mailing list at: bugmongers@perl.org - -For more info on the web see - - http://bugs.perl.org/perlbug.cgi?req=spec - -=over 4 - -=item 1 http://bugs.perl.org - -Login via the web, (remove B if only browsing), where interested -Cc's, tests, patches and change-ids, etc. may be assigned. - - http://bugs.perl.org/admin/index.html - - -=item 2 bugdb@perl.org - -Where the subject line is used for commands: - - To: bugdb@perl.org - Subject: -a close bugid1 bugid2 aix install + function unedit { + if [ -L $1.orig ]; then + rm $1 + mv $1.orig $1 + fi + } - To: bugdb@perl.org - Subject: -h +Replace "vi" with your favorite flavor of editor. + +Here is another function which will quickly generate a patch for the +files which have been edited in your symlink tree: + + mkpatchorig() { + local diffopts + for f in `find . -name '*.orig' | sed s,^\./,,` + do + case `echo $f | sed 's,.orig$,,;s,.*\.,,'` in + c) diffopts=-p ;; + pod) diffopts='-F^=' ;; + *) diffopts= ;; + esac + diff -du $diffopts $f `echo $f | sed 's,.orig$,,'` + done + } +This function produces patches which include enough context to make +your changes obvious. This makes it easier for the Perl pumpking(s) +to review them when you send them to the perl5-porters list, and that +means they're more likely to get applied. -=item 3 commands_and_bugdids@bugs.perl.org +This function assumed a GNU diff, and may require some tweaking for +other diff variants. -Where the address itself is the source for the commands: +=head2 Perlbug administration - To: close_bugid1_bugid2_aix@bugs.perl.org +There is a single remote administrative interface for modifying bug status, +category, open issues etc. using the B I system, maintained +by I. Become an administrator, and close any bugs you can get +your sticky mitts on: - To: help@bugs.perl.org + http://rt.perl.org +The bugtracker mechanism for B bugs in particular is at: -=item notes, patches, tests + http://bugs6.perl.org/perlbug -For patches and tests, the message body is assigned to the appropriate -bugs and forwarded to p5p for their attention. +To email the bug system administrators: - To: test__aix_close@bugs.perl.org - Subject: this is a test for the (now closed) aix bug + "perlbug-admin" - Test is the body of the mail - -=back =head2 Submitting patches @@ -915,7 +964,7 @@ C<"\0">. Line 13 manipulates the flags; since we've changed the PV, any IV or NV values will no longer be valid: if we have C<$a=10; $a.="6";> we don't -want to use the old IV of 10. C is a special UTF8-aware +want to use the old IV of 10. C is a special UTF-8-aware version of C, a macro which turns off the IOK and NOK flags and turns on POK. The final C is a macro which launders tainted data if taint mode is turned on. @@ -1256,6 +1305,14 @@ important ones are explained in L as well. Pay special attention to L for information on the C<[pad]THX_?> macros. +=head2 The .i Targets + +You can expand the macros in a F file by saying + + make foo.i + +which will expand the macros using cpp. Don't be scared by the results. + =head2 Poking at Perl To really poke around with Perl, you'll probably want to build Perl for @@ -1349,8 +1406,11 @@ blessing when stepping through miles of source code. =item print Execute the given C code and print its results. B: Perl makes -heavy use of macros, and F is not aware of macros. You'll have to -substitute them yourself. So, for instance, you can't say +heavy use of macros, and F does not necessarily support macros +(see later L). You'll have to substitute them +yourself, or to invoke cpp on the source code files +(see L) +So, for instance, you can't say print SvPV_nolen(sv) @@ -1358,11 +1418,19 @@ but you have to say print Perl_sv_2pv_nolen(sv) +=back + You may find it helpful to have a "macro dictionary", which you can produce by saying C. Even then, F won't -recursively apply the macros for you. +recursively apply those macros for you. -=back +=head2 gdb macro support + +Recent versions of F have fairly good macro support, but +in order to use it you'll need to compile perl with macro definitions +included in the debugging information. Using F version 3.1, this +means configuring with C<-Doptimize=-g3>. Other compilers might use a +different switch (if they support debugging macros at all). =head2 Dumping Perl Data Structures @@ -1460,7 +1528,7 @@ some things you'll need to know when fiddling with them. Let's now get on and create a simple patch. Here's something Larry suggested: if a C is the first active format during a C, (for example, C) then the resulting string should be treated as -UTF8 encoded. +UTF-8 encoded. How do we prepare to fix this up? First we locate the code in question - the C happens at runtime, so it's going to be in one of the F @@ -1509,7 +1577,7 @@ of C: while (pat < patend) { Now if we see a C which was at the start of the string, we turn on -the UTF8 flag for the output SV, C: +the C flag for the output SV, C: + if (datumtype == 'U' && pat==patcopy+1) + SvUTF8_on(cat); @@ -1595,10 +1663,10 @@ this text in the description of C: =item * If the pattern begins with a C, the resulting string will be treated - as Unicode-encoded. You can force UTF8 encoding on in a string with an - initial C, and the bytes that follow will be interpreted as Unicode - characters. If you don't want this to happen, you can begin your pattern - with C (or anything else) to force Perl not to UTF8 encode your + as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a string + with an initial C, and the bytes that follow will be interpreted as + Unicode characters. If you don't want this to happen, you can begin your + pattern with C (or anything else) to force Perl not to UTF-8 encode your string, and then follow this with a C somewhere in your pattern. All done. Now let's create the patch. F tells us @@ -1759,6 +1827,18 @@ modules hanging around in here that need to be moved out into F. Testing features of how perl actually runs, including exit codes and handling of PERL* environment variables. +=item F + +Tests for the core support of Unicode. + +=item F + +Windows-specific tests. + +=item F + +A test suite for the s2p converter. + =back The core uses the same testing style as the rest of Perl, a simple @@ -1819,13 +1899,24 @@ Run F on all core tests (F and F pragma tests). =item test.deparse -Run all the tests through the B::Deparse. Not all tests will succeed. +Run all the tests through B::Deparse. Not all tests will succeed. + +=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). =item minitest Run F on F, F, F, F, F, F, and F 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. + =item test.third check.third utest.third ucheck.third (Only in Tru64) Run all the tests using the memory leak + naughty @@ -1835,7 +1926,7 @@ F. =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, t/japh/abigail.t. +only extra tests are Abigail's JAPHs, F. You can also run the torture test with F by giving C<-torture> argument to F. @@ -1844,6 +1935,67 @@ C<-torture> argument to F. Run all the tests with -Mutf8. Not all tests will succeed. +=item minitest.utf16 test.utf16 + +Runs the tests with UTF-16 encoded scripts, encoded with different +versions of this encoding. + +C runs the test suite with a combination of C<-utf8> and +C<-utf16> arguments to F. + +=item test_harness + +Run the test suite with the F controlling program, instead of +F. F is more sophisticated, and uses the +L 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, it +doesn't redirect stderr to stdout. + +=back + +=head2 Running tests by hand + +You can run part of the test suite by hand by using one the following +commands from the F 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.) + +You can run an individual test by a command similar to + + ./perl -I../lib patho/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 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) + +=item PERL + +(used only by F) 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 =head1 EXTERNAL TOOLS FOR DEBUGGING PERL @@ -1854,6 +2006,38 @@ some common testing and debugging tools with Perl. This is meant as a guide to interfacing these tools with Perl, not as any kind of guide to the use of the tools themselves. +B: Running under memory debuggers such as Purify, valgrind, or +Third Degree greatly slows down the execution: seconds become minutes, +minutes become hours. For example as of Perl 5.8.1, the +ext/Encode/t/Unicode.t takes extraordinarily long to complete under +e.g. Purify, Third Degree, and valgrind. Under valgrind it takes more +than six hours, even on a snappy computer-- the said test must be +doing something that is quite unfriendly for memory debuggers. If you +don't feel like waiting, that you can simply kill away the perl +process. + +B: To minimize the number of memory leak false alarms (see +L for more information), you have to have +environment variable PERL_DESTRUCT_LEVEL set to 2. The F +and harness scripts do that automatically. But if you are running +some of the tests manually-- for csh-like shells: + + setenv PERL_DESTRUCT_LEVEL 2 + +and for Bourne-type shells: + + PERL_DESTRUCT_LEVEL=2 + export PERL_DESTRUCT_LEVEL + +or in UNIXy environments you can also use the C command: + + env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ... + +B: There are known memory leaks when there are compile-time +errors within eval or require, seeing C in the call stack +is a good sign of these. Fixing these leaks is non-trivial, +unfortunately, but they must be fixed eventually. + =head2 Rational Software's Purify Purify is a commercial tool that is helpful in identifying @@ -1862,11 +2046,6 @@ badness. Perl must be compiled in a specific way for optimal testing with Purify. Purify is available under Windows NT, Solaris, HP-UX, SGI, and Siemens Unix. -The only currently known leaks happen when there are -compile-time errors within eval or require. (Fixing these -is non-trivial, unfortunately, but they must be fixed -eventually.) - =head2 Purify on Unix On Unix, Purify creates a new Perl binary. To get the most @@ -1915,17 +2094,6 @@ which creates a binary named 'pureperl' that has been Purify'ed. This binary is used in place of the standard 'perl' binary when you want to debug Perl memory problems. -To minimize the number of memory leak false alarms -(see L), set environment variable -PERL_DESTRUCT_LEVEL to 2. - - setenv PERL_DESTRUCT_LEVEL 2 - -In Bourne-type shells: - - PERL_DESTRUCT_LEVEL=2 - export PERL_DESTRUCT_LEVEL - As an example, to show any memory leaks produced during the standard Perl testset you would create and run the Purify'ed perl as: @@ -2008,13 +2176,22 @@ standard Perl testset you would create and run Purify as: which would instrument Perl in memory, run Perl on test.pl, then finally report any memory problems. -B: as of Perl 5.8.0, the ext/Encode/t/Unicode.t takes -extraordinarily long (hours?) to complete under Purify. It has been -theorized that it would eventually finish, but nobody has so far been -patient enough :-) (This same extreme slowdown has been seen also with -the Third Degree tool, so the said test must be doing something that -is quite unfriendly for memory debuggers.) It is suggested that you -simply kill away that testing process. +=head2 valgrind + +The excellent valgrind tool can be used to find out both memory leaks +and illegal memory accesses. As of August 2003 it unfortunately works +only on x86 (ELF) Linux. The special "test.valgrind" target can be used +to run the tests under valgrind. Found errors and memory leaks are +logged in files named F. + +As system libraries (most notably glibc) are also triggering errors, +valgrind allows to suppress such errors using suppression files. The +default suppression file that comes with valgrind already catches a lot +of them. Some additional suppressions are defined in F. + +To get valgrind and for more information see + + http://developer.kde.org/~sewardj/ =head2 Compaq's/Digital's/HP's Third Degree @@ -2047,12 +2224,12 @@ aren't. See L for more information. =head2 PERL_DESTRUCT_LEVEL -If you want to run any of the tests yourself manually using the -pureperl or perl.third executables, please note that by default -perl B explicitly cleanup all the memory it has allocated -(such as global memory arenas) but instead lets the exit() of -the whole program "take care" of such allocations, also known -as "global destruction of objects". +If you want to run any of the tests yourself manually using e.g. +valgrind, or the pureperl or perl.third executables, please note that +by default perl B explicitly cleanup all the memory it has +allocated (such as global memory arenas) but instead lets the exit() +of the whole program "take care" of such allocations, also known as +"global destruction of objects". There is a way to tell perl to do complete cleanup: set the environment variable PERL_DESTRUCT_LEVEL to a non-zero value.