X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlhack.pod;h=f0b2ead4d1f5e0de0629ff733d325c97b668b60e;hb=6168cf9995a8bfcfe4ab9350ebc7de70215ae9af;hp=2d05fc3841a07f6a1634a7042ea88e0cb8ade5ff;hpb=37c0adebee4df35675070b1f30e9578094f823d7;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlhack.pod b/pod/perlhack.pod index 2d05fc3..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,6 +481,93 @@ 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 + } + + function unedit { + if [ -L $1.orig ]; then + rm $1 + mv $1.orig $1 + fi + } + +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. + +This function assumed a GNU diff, and may require some tweaking for +other diff variants. =head2 Perlbug administration @@ -875,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. @@ -1439,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 @@ -1488,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); @@ -1574,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 @@ -1810,7 +1899,12 @@ 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 @@ -1841,6 +1935,14 @@ 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