perlhack.pod

MSYS在windows下模拟了一个类unix的终端

C<datum_type>. Then for each possible format character, we swallow up
the other arguments in the pattern (a field width, an asterisk, and so
on) and convert the next chunk input into the specified format, adding
it onto the output SV C<cat>.

How do we know if the C<U> is the first format in the C<pat>? Well, if
we have a pointer to the start of C<pat> then, if we see a C<U> we can
test whether we're still at the start of the string. So, here's where
C<pat> is set up:

    STRLEN fromlen;
    register char *pat = SvPVx(*++MARK, fromlen);
    register char *patend = pat + fromlen;
    register I32 len;
    I32 datumtype;
    SV *fromstr;

We'll have another string pointer in there:

    STRLEN fromlen;
    register char *pat = SvPVx(*++MARK, fromlen);
    register char *patend = pat + fromlen;
 +  char *patcopy;
    register I32 len;
    I32 datumtype;
    SV *fromstr;

And just before we start the loop, we'll set C<patcopy> to be the start
of C<pat>:

    items = SP - MARK;
    MARK++;
    sv_setpvn(cat, "", 0);
 +  patcopy = pat;
    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>:

 +  if (datumtype == 'U' && pat==patcopy+1)
 +      SvUTF8_on(cat);
    if (datumtype == '#') {
        while (pat < patend && *pat != '\n')
            pat++;

Remember that it has to be C<patcopy+1> because the first character of
the string is the C<U> which has been swallowed into C<datumtype!>

Oops, we forgot one thing: what if there are spaces at the start of the
pattern? C<pack("  U*", @stuff)> will have C<U> as the first active
character, even though it's not the first thing in the pattern. In this
case, we have to advance C<patcopy> along with C<pat> when we see spaces:

    if (isSPACE(datumtype))
        continue;

needs to become

    if (isSPACE(datumtype)) {
        patcopy++;
        continue;
    }

OK. That's the C part done. Now we must do two additional things before
this patch is ready to go: we've changed the behaviour of Perl, and so
we must document that change. We must also provide some more regression
tests to make sure our patch works and doesn't create a bug somewhere
else along the line.

The regression tests for each operator live in F<t/op/>, and so we make
a copy of F<t/op/pack.t> to F<t/op/pack.t~>. Now we can add our tests
to the end. First, we'll test that the C<U> does indeed create Unicode
strings:

 print 'not ' unless "1.20.300.4000" eq sprintf "%vd", pack("U*",1,20,300,4000);
 print "ok $test\n"; $test++;

Now we'll test that we got that space-at-the-beginning business right:

 print 'not ' unless "1.20.300.4000" eq
                     sprintf "%vd", pack("  U*",1,20,300,4000);
 print "ok $test\n"; $test++;

And finally we'll test that we don't make Unicode strings if C<U> is B<not>
the first active format:

 print 'not ' unless v1.20.300.4000 ne
                     sprintf "%vd", pack("C0U*",1,20,300,4000);
 print "ok $test\n"; $test++;

Mustn't forget to change the number of tests which appears at the top, or
else the automated tester will get confused:

 -print "1..156\n";
 +print "1..159\n";

We now compile up Perl, and run it through the test suite. Our new
tests pass, hooray!

Finally, the documentation. The job is never done until the paperwork is
over, so let's describe the change we've just made. The relevant place
is F<pod/perlfunc.pod>; again, we make a copy, and then we'll insert
this text in the description of C<pack>:

 =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
 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
that if we're making major changes, we should copy the entire directory
to somewhere safe before we begin fiddling, and then do

    diff -ruN old new > patch

However, we know which files we've changed, and we can simply do this:

    diff -u pp.c~             pp.c             >  patch
    diff -u t/op/pack.t~      t/op/pack.t      >> patch
    diff -u pod/perlfunc.pod~ pod/perlfunc.pod >> patch

We end up with a patch looking a little like this:

    --- pp.c~       Fri Jun 02 04:34:10 2000
    +++ pp.c        Fri Jun 16 11:37:25 2000
    @@ -4375,6 +4375,7 @@
         register I32 items;
         STRLEN fromlen;
         register char *pat = SvPVx(*++MARK, fromlen);
    +    char *patcopy;
         register char *patend = pat + fromlen;
         register I32 len;
         I32 datumtype;
    @@ -4405,6 +4406,7 @@
    ...

And finally, we submit it, with our rationale, to perl5-porters. Job
done!

=head1 EXTERNAL TOOLS FOR DEBUGGING PERL

Sometimes it helps to use external tools while debugging and
testing Perl.  This section tries to guide you through using
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.

=head2 Rational Software's Purify

Purify is a commercial tool that is helpful in identifying
memory overruns, wild pointers, memory leaks and other such
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
benefit out of Purify, you should create the perl to Purify
using:

    sh Configure -Accflags=-DPURIFY -Doptimize='-g' \
     -Uusemymalloc -Dusemultiplicity

where these arguments mean:

=over 4

=item -Accflags=-DPURIFY

Disables Perl's arena memory allocation functions, as well as
forcing use of memory allocation functions derived from the
system malloc.

=item -Doptimize='-g'

Adds debugging information so that you see the exact source
statements where the problem occurs.  Without this flag, all
you will see is the source filename of where the error occurred.

=item -Uusemymalloc

Disable Perl's malloc so that Purify can more closely monitor
allocations and leaks.  Using Perl's malloc will make Purify
report most leaks in the "potential" leaks category.

=item -Dusemultiplicity

Enabling the multiplicity option allows perl to clean up
thoroughly when the interpreter shuts down, which reduces the
number of bogus leak reports from Purify.

=back

Once you've compiled a perl suitable for Purify'ing, then you
can just:

    make pureperl   

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.

As an example, to show any memory leaks produced during the
standard Perl testset you would create and run the Purify'ed
perl as:

    make pureperl
    cd t
    ../pureperl -I../lib harness 

which would run Perl on test.pl and report any memory problems.

Purify outputs messages in "Viewer" windows by default.  If
you don't have a windowing environment or if you simply
want the Purify output to unobtrusively go to a log file
instead of to the interactive window, use these following
options to output to the log file "perl.log":

    setenv PURIFYOPTIONS "-chain-length=25 -windows=no \
     -log-file=perl.log -append-logfile=yes"

If you plan to use the "Viewer" windows, then you only need this option:

    setenv PURIFYOPTIONS "-chain-length=25"

=head2 Purify on NT

Purify on Windows NT instruments the Perl binary 'perl.exe'
on the fly.  There are several options in the makefile you
should change to get the most use out of Purify:

=over 4

=item DEFINES

You should add -DPURIFY to the DEFINES line so the DEFINES
line looks something like:

    DEFINES = -DWIN32 -D_CONSOLE -DNO_STRICT $(CRYPT_FLAG) -DPURIFY=1 

to disable Perl's arena memory allocation functions, as
well as to force use of memory allocation functions derived
from the system malloc.

=item USE_MULTI = define

Enabling the multiplicity option allows perl to clean up
thoroughly when the interpreter shuts down, which reduces the
number of bogus leak reports from Purify.

=item #PERL_MALLOC = define

Disable Perl's malloc so that Purify can more closely monitor
allocations and leaks.  Using Perl's malloc will make Purify
report most leaks in the "potential" leaks category.

=item CFG = Debug

Adds debugging information so that you see the exact source
statements where the problem occurs.  Without this flag, all
you will see is the source filename of where the error occurred.

=back

As an example, to show any memory leaks produced during the
standard Perl testset you would create and run Purify as:

    cd win32
    make
    cd ../t
    purify ../perl -I../lib harness 

which would instrument Perl in memory, run Perl on test.pl,
then finally report any memory problems.

=head2 CONCLUSION

We've had a brief look around the Perl source, an overview of the stages
F<perl> goes through when it's running your code, and how to use a
debugger to poke at the Perl guts. We took a very simple problem and
demonstrated how to solve it fully - with documentation, regression
tests, and finally a patch for submission to p5p.  Finally, we talked
about how to use external tools to debug and test Perl.

I'd now suggest you read over those references again, and then, as soon
as possible, get your hands dirty. The best way to learn is by doing,
so: 

=over 3

=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 *

Keep up to date with the bleeding edge Perl distributions and get
familiar with the changes. Try and get an idea of what areas people are
working on and the changes they're making.

=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

=over 3

=item I<The Road goes ever on and on, down from the door where it began.>

=back

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!

=head1 AUTHOR

This document was written by Nathan Torkington, and is maintained by
the perl5-porters mailing list.