=back
-=head2 Perlbug remote interface
+=head2 Perlbug administration
-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.
+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:
-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
+ http://rt.perl.org
-For more info on the web see
+The bugtracker mechanism for B<perl5> bugs in particular is at:
- http://bugs.perl.org/perlbug.cgi?req=spec
+ http://bugs6.perl.org/perlbug
-=over 4
-
-=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
-
-
-=item 3 commands_and_bugdids@bugs.perl.org
-
-Where the address itself is the source for the commands:
-
- To: close_bugid1_bugid2_aix@bugs.perl.org
-
- To: help@bugs.perl.org
-
-
-=item notes, patches, tests
+To email the bug system administrators:
-For patches and tests, the message body is assigned to the appropriate
-bugs and forwarded to p5p for their attention.
+ "perlbug-admin" <perlbug-admin@perl.org>
- 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
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
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
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.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<testname.valgrind>.
+
=item test.third check.third utest.third ucheck.third
(Only in Tru64) Run all the tests using the memory leak + naughty
=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<t/japh/abigail.t>.
You can also run the torture test with F<t/harness> by giving
C<-torture> argument to F<t/harness>.
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
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 get valgrind and for more information see
+
+ http://developer.kde.org/~sewardj/
+
=head2 Compaq's/Digital's/HP's Third Degree
Third Degree is a tool for memory leak detection and memory access checks.
(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 set this
-variable to the value 2.)
+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
https://perl5.git.perl.org / perl5.git / blobdiff