This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #71000] Wrong variable name in warning
[perl5.git] / pod / perlhack.pod
index dde67a3..73dec46 100644 (file)
@@ -214,7 +214,7 @@ changes.
 How to clone and use the git perl repository is described in L<perlrepository>.
 
 You can also choose to use rsync to get a copy of the current source tree
-for the bleadperl branch and all maintainance branches :
+for the bleadperl branch and all maintenance branches :
 
     $ rsync -avz rsync://perl5.git.perl.org/APC/perl-current .
     $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.10.x .
@@ -263,7 +263,7 @@ you're fixing a bug in the 5.8 track, patch against the C<blead> branch in
 the git repository.)
 
 If changes are accepted, they are applied to the development branch. Then
-the maintainance pumpking decides which of those patches is to be
+the maintenance pumpking decides which of those patches is to be
 backported to the maint branch.  Only patches that survive the heat of the
 development branch get applied to maintenance versions.
 
@@ -296,8 +296,8 @@ automatically test Perl source releases on platforms with various
 configurations.  Both efforts welcome volunteers. In order to get
 involved in smoke testing of the perl itself visit
 L<http://search.cpan.org/dist/Test-Smoke>. In order to start smoke
-testing CPAN modules visit L<http://search.cpan.org/dist/CPAN-YACSmoke/>
-or L<http://search.cpan.org/dist/POE-Component-CPAN-YACSmoke/> or
+testing CPAN modules visit L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/>
+or L<http://search.cpan.org/dist/minismokebox/> or
 L<http://search.cpan.org/dist/CPAN-Reporter/>.
 
 It's a good idea to read and lurk for a while before chipping in.
@@ -321,10 +321,12 @@ might start to make sense - don't worry if it doesn't yet, because the
 best way to study it is to read it in conjunction with poking at Perl
 source, and we'll do that later on.
 
-You might also want to look at Gisle Aas's illustrated perlguts -
-there's no guarantee that this will be absolutely up-to-date with the
-latest documentation in the Perl core, but the fundamentals will be
-right. ( http://gisle.aas.no/perl/illguts/ )
+Gisle Aas's illustrated perlguts (also known as I<illguts>) is wonderful,
+although a little out of date with regard to some size details; the
+various SV structures have since been reworked for smaller memory footprint.
+The fundamentals are right however, and the pictures are very helpful.
+
+L<http://www.perl.org/tpc/1998/Perl_Language_and_Modules/Perl%20Illustrated/>
 
 =item L<perlxstut> and L<perlxs>
 
@@ -363,9 +365,18 @@ correspond to files or directories in the source kit. Among the areas are:
 
 =item Core modules
 
-Modules shipped as part of the Perl core live in the F<lib/> and F<ext/>
-subdirectories: F<lib/> is for the pure-Perl modules, and F<ext/>
-contains the core XS modules.
+Modules shipped as part of the Perl core live in various subdirectories, where
+two are dedicated to core-only modules, and two are for the dual-life modules
+which live on CPAN and may be maintained separately with respect to the Perl
+core: 
+
+    lib/  is for pure-Perl modules, which exist in the core only.
+
+    ext/  is for XS extensions, and modules with special Makefile.PL requirements, which exist in the core only.
+
+    cpan/ is for dual-life modules, where the CPAN module is canonical (should be patched first).
+
+    dist/ is for dual-life modules, where the blead source is canonical.
 
 =item Tests
 
@@ -382,17 +393,29 @@ the documentation to the modules in core.
 
 =item Configure
 
-The configure process is the way we make Perl portable across the
+The Configure process is the way we make Perl portable across the
 myriad of operating systems it supports. Responsibility for the
-configure, build and installation process, as well as the overall
-portability of the core code rests with the configure pumpkin - others
-help out with individual operating systems.
+Configure, build and installation process, as well as the overall
+portability of the core code rests with the Configure pumpkin -
+others help out with individual operating systems.
+
+The three files that fall under his/her resposibility are Configure,
+config_h.SH, and Porting/Glossary (and a whole bunch of small related
+files that are less important here). The Configure pumpkin decides how
+patches to these are dealt with. Currently, the Configure pumpkin will
+accept patches in most common formats, even directly to these files.
+Other committers are allowed to commit to these files under the strict
+condition that they will inform the Configure pumpkin, either on IRC
+(if he/she happens to be around) or through (personal) e-mail.
 
 The files involved are the operating system directories, (F<win32/>,
 F<os2/>, F<vms/> and so on) the shell scripts which generate F<config.h>
 and F<Makefile>, as well as the metaconfig files which generate
 F<Configure>. (metaconfig isn't included in the core distribution.)
 
+See http://perl5.git.perl.org/metaconfig.git/blob/HEAD:/README for a
+description of the full process involved.
+
 =item Interpreter
 
 And of course, there's the core of the Perl interpreter itself. Let's
@@ -1497,6 +1520,10 @@ 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
 UTF-8 encoded.
 
+If you are working with a git clone of the Perl repository, you will want to
+create a branch for your changes. This will make creating a proper patch much
+simpler. See the L<perlrepository> for details on how to do this.
+
 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>
 files. Sure enough, C<pp_pack> is in F<pp.c>. Since we're going to be
@@ -1636,36 +1663,6 @@ this text in the description of C<pack>:
  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
-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!
-
 =head2 Patching a core module
 
 This works just like patching anything else, with an extra
@@ -1725,9 +1722,8 @@ When you write your new code, please be conscious of existing code
 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
-for lots of details about both formatting and submitting patches of
-your changes.
+Also see I<perlrepository> for lots of details about both formatting and
+submitting patches of your changes.
 
 Lastly, TEST TEST TEST TEST TEST any code before posting to p5p.
 Test on as many platforms as you can find.  Test as many perl
@@ -1754,6 +1750,9 @@ so there are some snags (and it would be wonderful for you to brush
 them out), but it basically works that way.  Everything else lives in
 F<t/>.
 
+If you add a new test directory under F<t/>, it is imperative that you 
+add that directory to F<t/HARNESS> and F<t/TEST>.
+
 =over 3
 
 =item F<t/base/>
@@ -1792,10 +1791,10 @@ Tests for perl's method resolution order implementations
 Tests for perl's built in functions that don't fit into any of the
 other directories.
 
-=item F<t/pod/>
+=item F<t/re/>
 
-Tests for POD directives.  There are still some tests for the Pod
-modules hanging around in here that need to be moved out into F<lib/>.
+Tests for regex related functions or behaviour. (These used to live
+in t/op).
 
 =item F<t/run/>
 
@@ -1949,6 +1948,23 @@ you can say
     nmake test TEST_FILES="op/*.t"
     nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t"
 
+=item Parallel tests
+
+The core distribution can now run its regression tests in parallel on
+Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> in
+your environment to the number of tests to run in parallel, and run
+C<make test_harness>. On a Bourne-like shell, this can be done as
+
+    TEST_JOBS=3 make test_harness  # Run 3 tests in parallel
+
+An environment variable is used, rather than parallel make itself, because
+L<TAP::Harness> needs to be able to schedule individual non-conflicting test
+scripts itself, and there is no standard interface to C<make> utilities to
+interact with their job schedulers.
+
+Note that currently some test scripts may fail when run in parallel (most
+notably C<ext/IO/t/io_dir.t>). If necessary run just the failing scripts
+again sequentially and see if the failures go away.
 =item test-notty test_notty
 
 Sets PERL_SKIP_TTY_TEST to true before running normal test.
@@ -1986,7 +2002,7 @@ expanded out.
 =item -v
 
 Run the tests under verbose mode so you can see what tests were run,
-and debug outbut.
+and debug output.
 
 =item -torture
 
@@ -2332,16 +2348,17 @@ about other ranges.
 Many of the comments in the existing code ignore the possibility of EBCDIC,
 and may be wrong therefore, even if the code works.
 This is actually a tribute to the successful transparent insertion of being
-able to handle EBCDIC without having to change pre-existing code.
+able to handle EBCDIC without having to change pre-existing code.
 
 UTF-8 and UTF-EBCDIC are two different encodings used to represent Unicode
 code points as sequences of bytes.  Macros 
 with the same names (but different definitions)
 in C<utf8.h> and C<utfebcdic.h>
-are used to allow the calling code think that there is only one such encoding.
-This is almost always referred to as C<utf8>, but it means the EBCDIC
-version as well.  Comments in the code may well be wrong even if the code
-itself is right.
+are used to allow the calling code to think that there is only one such
+encoding.
+This is almost always referred to as C<utf8>, but it means the EBCDIC version
+as well.  Again, comments in the code may well be wrong even if the code itself
+is right.
 For example, the concept of C<invariant characters> differs between ASCII and
 EBCDIC.
 On ASCII platforms, only characters that do not have the high-order
@@ -2939,27 +2956,29 @@ by C<-DPERL_MEM_LOG> instead.
 
 =head2 PERL_MEM_LOG
 
-If compiled with C<-DPERL_MEM_LOG>, all Newx() and Renew() allocations
-and Safefree() in the Perl core go through logging functions, which is
-handy for breakpoint setting.  If also compiled with C<-DPERL_MEM_LOG_STDERR>,
-the allocations and frees are logged to STDERR (or more precisely, to the
-file descriptor 2) in these logging functions, with the calling source code
-file and line number (and C function name, if supported by the C compiler).
+If compiled with C<-DPERL_MEM_LOG>, both memory and SV allocations go
+through logging functions, which is handy for breakpoint setting.
+
+Unless C<-DPERL_MEM_LOG_NOIMPL> is also compiled, the logging
+functions read $ENV{PERL_MEM_LOG} to determine whether to log the
+event, and if so how:
 
-This logging is somewhat similar to C<-Dm> but independent of C<-DDEBUGGING>,
-and at a higher level (the C<-Dm> is directly at the point of C<malloc()>,
-while the C<PERL_MEM_LOG> is at the level of C<New()>).
+    $ENV{PERL_MEM_LOG} =~ /m/          Log all memory ops
+    $ENV{PERL_MEM_LOG} =~ /s/          Log all SV ops
+    $ENV{PERL_MEM_LOG} =~ /t/          include timestamp in Log
+    $ENV{PERL_MEM_LOG} =~ /^(\d+)/     write to FD given (default is 2)
 
-In addition to memory allocations, SV allocations will be logged, just as
-with C<-Dm>. However, since the logging doesn't use PerlIO, all SV allocations
-are logged and no extra SV allocations are introduced by enabling the logging.
-If compiled with C<-DDEBUG_LEAKING_SCALARS>, the serial number for each SV
-allocation is also logged.
+Memory logging is somewhat similar to C<-Dm> but is independent of
+C<-DDEBUGGING>, and at a higher level; all uses of Newx(), Renew(),
+and Safefree() are logged with the caller's source code file and line
+number (and C function name, if supported by the C compiler).  In
+contrast, C<-Dm> is directly at the point of C<malloc()>.  SV logging
+is similar.
 
-You can control the logging from your environment if you compile with
-C<-DPERL_MEM_LOG_ENV>. Then you need to explicitly set C<PERL_MEM_LOG> and/or
-C<PERL_SV_LOG> to a non-zero value to enable logging of memory and/or SV
-allocations.
+Since the logging doesn't use PerlIO, all SV allocations are logged
+and no extra SV allocations are introduced by enabling the logging.
+If compiled with C<-DDEBUG_LEAKING_SCALARS>, the serial number for
+each SV allocation is also logged.
 
 =head2 Profiling
 
@@ -3040,9 +3059,9 @@ formats, see your own local documentation of gprof.
 
 quick hint:
 
-    $ sh Configure -des -Dusedevel -Doptimize='-g' -Accflags='-pg' -Aldflags='-pg' && make
-    $ ./perl someprog # creates gmon.out in current directory
-    $ gprof perl > out
+    $ sh Configure -des -Dusedevel -Doptimize='-pg' && make perl.gprof
+    $ ./perl.gprof someprog # creates gmon.out in current directory
+    $ gprof ./perl.gprof > out
     $ view out
 
 =head2 GCC gcov Profiling