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<Configure>
-pumpkin.
+instance, Andy Dougherty and Jarkko Hietaniemi did a grand job as the
+I<Configure> 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
=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<overwrite> 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<Configure> 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<perl-rsync> 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<Configure> script, and you
+will see that the directory you are in has a tree of symlinks to the
+F<perl-rsync> 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
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<SvPOK_only_utf8> is a special UTF8-aware
+want to use the old IV of 10. C<SvPOK_only_utf8> is a special UTF-8-aware
version of C<SvPOK_only>, a macro which turns off the IOK and NOK flags
and turns on POK. The final C<SvTAINT> is a macro which launders tainted
data if taint mode is turned on.
print Perl_sv_2pv_nolen(sv)
+=back
+
You may find it helpful to have a "macro dictionary", which you can
produce by saying C<cpp -dM perl.c | sort>. Even then, F<cpp> won't
recursively apply those macros for you.
means configuring with C<-Doptimize=-g3>. Other compilers might use a
different switch (if they support debugging macros at all).
-=back
-
=head2 Dumping Perl Data Structures
One way to get around this macro hell is to use the dumping functions in
on and create a simple patch. Here's something Larry suggested: if a
C<U> is the first active format during a C<pack>, (for example,
C<pack "U3C8", @stuff>) 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<pack> happens at runtime, so it's going to be in one of the F<pp>
while (pat < patend) {
Now if we see a C<U> which was at the start of the string, we turn on
-the UTF8 flag for the output SV, C<cat>:
+the C<UTF8> flag for the output SV, C<cat>:
+ if (datumtype == 'U' && pat==patcopy+1)
+ SvUTF8_on(cat);
=item *
If the pattern begins with a C<U>, the resulting string will be treated
- as Unicode-encoded. You can force UTF8 encoding on in a string with an
- initial C<U0>, 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<C0> (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<U0>, 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<C0> (or anything else) to force Perl not to UTF-8 encode your
string, and then follow this with a C<U*> somewhere in your pattern.
All done. Now let's create the patch. F<Porting/patching.pod> tells us
=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 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<make utest.utf16> runs the test suite with a combination of C<-utf8> and
+C<-utf16> arguments to F<t/TEST>.
+
=item test_harness
Run the test suite with the F<t/harness> controlling program, instead of
meant as a guide to interfacing these tools with Perl, not
as any kind of guide to the use of the tools themselves.
+B<NOTE 1>: 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<NOTE 2>: To minimize the number of memory leak false alarms (see
+L</PERL_DESTRUCT_LEVEL> for more information), you have to have
+environment variable PERL_DESTRUCT_LEVEL set to 2. The F<TEST>
+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<env> command:
+
+ env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ...
+
+B<NOTE 3>: There are known memory leaks when there are compile-time
+errors within eval or require, seeing C<S_doeval> 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
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
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</PERL_DESTRUCT_LEVEL>), 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:
which would instrument Perl in memory, run Perl on test.pl,
then finally report any memory problems.
-B<NOTE>: 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. Note that in the test script (t/TEST)
-currently (as of Perl 5.8.1) only naughty memory accesses are logged,
-not memory leaks. Found errors are logged in files named F<test.valgrind>.
-Also note that with Perl built with ithreads, the glibc (at least 2.2.5)
-seems to have a bug of its own, where a non-locked POSIX mutex is
-unlocked, and valgrind catches this, for every test-- therefore the
-test script ignores that error.
+to run the tests under valgrind. Found errors and memory leaks are
+logged in files named F<test.valgrind>.
+
+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<t/perl.supp>.
To get valgrind and for more information see
=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<does not> 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<does not> 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.
projects / p5sagit/p5-mst-13.2.git / blobdiff