that describe the individual changes that have happened since the last
public release are available at this location:
+ http://public.activestate.com/gsar/APC/
ftp://ftp.linux.activestate.com/pub/staff/gsar/APC/
+If you're looking for a particular change, or a change that affected
+a particular set of files, you may find the B<Perl Repository Browser>
+useful:
+
+ http://public.activestate.com/cgi-bin/perlbrowse
+
+You may also want to subscribe to the perl5-changes mailing list to
+receive a copy of each patch that gets submitted to the maintenance
+and development "branches" of the perl repository. See
+http://lists.perl.org/ for subscription information.
+
If you are a member of the perl5-porters mailing list, it is a good
thing to keep in touch with the most recent changes. If not only to
verify if what you would have posted as a bug report isn't already
Since you don't have to apply the patches yourself, you are sure all
files in the source tree are in the right state.
-=item It's more recent
-
-According to Gurusamy Sarathy:
-
- "... The rsync mirror is automatic and syncs with the repository
- every five minutes.
-
- "Updating the patch area still requires manual intervention
- (with all the goofiness that implies, which you've noted) and
- is typically on a daily cycle. Making this process automatic
- is on my tuit list, but don't ask me when."
-
=item It's more reliable
-Well, since the patches are updated by hand, I don't have to say any
-more ... (see Sarathy's remark).
+While both the rsync-able source and patch areas are automatically
+updated every few minutes, keep in mind that applying patches may
+sometimes mean careful hand-holding, especially if your version of
+the C<patch> program does not understand how to deal with new files,
+files with 8-bit characters, or files without trailing newlines.
=back
=back
-=head2 Perlbug remote interface
-
-=over 4
-
-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
-
-
-B<The interfaces:>
-
-
-=item 1 http://bugs.perl.org
-
-Login via the web, (remove B<admin/> 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
-
- To: bugdb@perl.org
- Subject: -h
+=head2 Perlbug administration
+There is a single remote administrative interface for modifying bug status,
+category, open issues etc. using the B<RT> I<bugtracker> system, maintained
+by I<Robert Spier>. Become an administrator, and close any bugs you can get
+your sticky mitts on:
-=item 3 commands_and_bugdids@bugs.perl.org
+ http://rt.perl.org
-Where the address itself is the source for the commands:
+The bugtracker mechanism for B<perl5> bugs in particular is at:
- To: close_bugid1_bugid2_aix@bugs.perl.org
+ http://bugs6.perl.org/perlbug
- To: help@bugs.perl.org
+To email the bug system administrators:
+ "perlbug-admin" <perlbug-admin@perl.org>
-=item notes, patches, tests
-
-For patches and tests, the message body is assigned to the appropriate bug/s and forwarded to p5p for their attention.
-
- To: test_<bugid1>_aix_close@bugs.perl.org
- Subject: this is a test for the (now closed) aix bug
-
- Test is the body of the mail
-
-=back
=head2 Submitting patches
the searchable archives.
The CPAN testers ( http://testers.cpan.org/ ) are a group of
-volunteers who test CPAN modules on a variety of platforms. Perl Labs
-( http://labs.perl.org/ ) automatically tests Perl source releases on
-platforms and gives feedback to the CPAN testers mailing list. Both
-efforts welcome volunteers.
+volunteers who test CPAN modules on a variety of platforms. Perl
+Smokers ( http://archives.develooper.com/daily-build@perl.org/ )
+automatically tests Perl source releases on platforms with various
+configurations. Both efforts welcome volunteers.
It's a good idea to read and lurk for a while before chipping in.
That way you'll get to see the dynamic of the conversations, learn the
=item The perl5-porters FAQ
-This is posted to perl5-porters at the beginning on every month, and
-should be available from http://perlhacker.org/p5p-faq ; alternatively,
-you can get the FAQ emailed to you by sending mail to
-C<perl5-porters-faq@perl.org>. It contains hints on reading
-perl5-porters, information on how perl5-porters works and how Perl
-development in general works.
+This should be available from http://simon-cozens.org/writings/p5p-faq ;
+alternatively, you can get the FAQ emailed to you by sending mail to
+C<perl5-porters-faq@perl.org>. It contains hints on reading perl5-porters,
+information on how perl5-porters works and how Perl development in general
+works.
=back
The easiest way to examine the op tree is to stop Perl after it has
finished parsing, and get it to dump out the tree. This is exactly what
-the compiler backends L<B::Terse|B::Terse> and L<B::Debug|B::Debug> do.
+the compiler backends L<B::Terse|B::Terse>, L<B::Concise|B::Concise>
+and L<B::Debug|B::Debug> do.
Let's have a look at how Perl sees C<$a = $b + $c>:
to L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for information on
the C<[pad]THX_?> macros.
+=head2 The .i Targets
+
+You can expand the macros in a F<foo.c> 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
=item print
Execute the given C code and print its results. B<WARNING>: Perl makes
-heavy use of macros, and F<gdb> 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<gdb> does not necessarily support macros
+(see later L</"gdb macro support">). You'll have to substitute them
+yourself, or to invoke cpp on the source code files
+(see L</"The .i Targets">)
+So, for instance, you can't say
print SvPV_nolen(sv)
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 the macros for you.
+recursively apply those macros for you.
+
+=head2 gdb macro support
+
+Recent versions of F<gdb> 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<gcc> version 3.1, this
+means configuring with C<-Doptimize=-g3>. Other compilers might use a
+different switch (if they support debugging macros at all).
=back
this when you post your patch to P5P; the pumpking needs to know this.
When you write your new code, please be conscious of existing code
-conventions used in the perl source files. See <perlstyle> for
+conventions used in the perl source files. See L<perlstyle> for
details. Although most of the guidelines discussed seem to focus on
Perl code, rather than c, they all apply (except when they don't ;).
See also I<Porting/patching.pod> file in the Perl source distribution
Testing features of how perl actually runs, including exit codes and
handling of PERL* environment variables.
+=item F<t/uni/>
+
+Tests for the core support of Unicode.
+
+=item F<t/win32/>
+
+Windows-specific tests.
+
+=item F<t/x2p>
+
+A test suite for the s2p converter.
+
=back
The core uses the same testing style as the rest of Perl, a simple
boils down to using File::Spec and avoiding things like C<fork()> and
C<system()> unless absolutely necessary.
+=head2 Special Make Test Targets
+
+There are various special make targets that can be used to test Perl
+slightly differently than the standard "test" target. Not all them
+are expected to give a 100% success rate. Many of them have several
+aliases.
+
+=over 4
+
+=item coretest
+
+Run F<perl> on all core tests (F<t/*> and F<lib/[a-z]*> pragma tests).
+
+=item test.deparse
+
+Run all the tests through the B::Deparse. Not all tests will succeed.
+
+=item minitest
+
+Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>,
+F<t/op>, and F<t/uni> tests.
+
+=item test.third check.third utest.third ucheck.third
+
+(Only in Tru64) Run all the tests using the memory leak + naughty
+memory access tool "Third Degree". The log files will be named
+F<perl3.log.testname>.
+
+=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, F<t/japh/abigail.t>.
+
+You can also run the torture test with F<t/harness> by giving
+C<-torture> argument to F<t/harness>.
+
+=item utest ucheck test.utf8 check.utf8
+
+Run all the tests with -Mutf8. Not all tests will succeed.
+
+=item test_harness
+
+Run the test suite with the F<t/harness> controlling program, instead of
+F<t/TEST>. F<t/harness> is more sophisticated, and uses the
+L<Test::Harness> 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<t/TEST>, 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<t/> 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</PERL_DESTRUCT_LEVEL>)
+
+=item PERL
+
+(used only by F<t/TEST>) 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
In Bourne-type shells:
- PURIFY_OPTIONS="..."
- export PURIFY_OPTIONS
+ PURIFYOPTIONS="..."
+ export PURIFYOPTIONS
or if you have the "env" utility:
- env PURIFY_OPTIONS="..." ../pureperl ...
+ env PURIFYOPTIONS="..." ../pureperl ...
=head2 Purify on NT
which would instrument Perl in memory, run Perl on test.pl,
then finally report any memory problems.
-=head2 Compaq's/Digital's Third Degree
+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 Compaq's/Digital's/HP's Third Degree
Third Degree is a tool for memory leak detection and memory access checks.
It is one of the many tools in the ATOM toolkit. The toolkit is only
documentation is available in the Compaq "Tru64 UNIX Programmer's
Guide", chapter "Debugging Programs with Third Degree".
-The "test.third" leaves a lot of files named F<perl.3log.*> in the t/
+The "test.third" leaves a lot of files named F<foo_bar.3log> in the t/
subdirectory. There is a problem with these files: Third Degree is so
effective that it finds problems also in the system libraries.
-Therefore there are certain types of errors that you should ignore in
-your debugging. Errors with stack traces matching
-
- __actual_atof|__catgets|_doprnt|__exc_|__exec|_findio|__localtime|setlocale|__sia_|__strxfrm
-
-(all in libc.so) are known to be non-serious. You can also
-ignore the combinations
-
- Perl_gv_fetchfile() calling strcpy()
- S_doopen_pmc() calling strcmp()
-
-causing "rih" (reading invalid heap) errors.
+Therefore you should used the Porting/thirdclean script to cleanup
+the F<*.3log> files.
There are also leaks that for given certain definition of a leak,
aren't. See L</PERL_DESTRUCT_LEVEL> for more information.
env PERL_DESTRUCT_LEVEL=2 ./perl.third -Ilib t/foo/bar.t
+(Note: the mod_perl apache module uses also this environment variable
+for its own purposes and extended its semantics. Refer to the mod_perl
+documentation for more information. Also, spawned threads do the
+equivalent of setting this variable to the value 1.)
+
+If, at the end of a run you get the message I<N scalars leaked>, you can
+recompile with C<-DDEBUG_LEAKING_SCALARS>, which will cause
+the addresses of all those leaked SVs to be dumped; it also converts
+C<new_SV()> from a macro into a real function, so you can use your
+favourite debugger to discover where those pesky SVs were allocated.
+
=head2 Profiling
Depending on your platform there are various of profiling Perl.
Note: you can define up to 20 conversion shortcuts in the gdb
section.
+=item *
+
+If you see in a debugger a memory area mysteriously full of 0xabababab,
+you may be seeing the effect of the Poison() macro, see L<perlclib>.
+
=back
=head2 CONCLUSION