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 maintenance 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 .
- $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.8.x .
- $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.6.x .
- $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.005xx .
+ $ rsync -avz rsync://perl5.git.perl.org/perl-current .
+ $ rsync -avz rsync://perl5.git.perl.org/perl-5.12.x .
+ $ rsync -avz rsync://perl5.git.perl.org/perl-5.10.x .
+ $ rsync -avz rsync://perl5.git.perl.org/perl-5.8.x .
+ $ rsync -avz rsync://perl5.git.perl.org/perl-5.6.x .
+ $ rsync -avz rsync://perl5.git.perl.org/perl-5.005xx .
(Add the C<--delete> option to remove leftover files)
+To get a full list of the available sync points:
+
+ $ rsync perl5.git.perl.org::
+
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
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.
best way to study it is to read it in conjunction with poking at Perl
source, and we'll do that later on.
-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.
+Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very
+helpful pictures:
-L<http://www.perl.org/tpc/1998/Perl_Language_and_Modules/Perl%20Illustrated/>
+L<http://search.cpan.org/dist/illguts/>
=item L<perlxstut> and L<perlxs>
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.
+ 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).
+ 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.
+ dist/ is for dual-life modules, where the blead source is
+ canonical.
+
+For some dual-life modules it has not been discussed if the CPAN version or the
+blead source is canonical. Until that is done, those modules should be in
+F<cpan/>.
=item Tests
=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 responsibility 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
interpreter. It's quite a simple function, and the guts of it looks like
this:
- my_perl = (PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter));
+ my_perl = (PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter));
Here you see an example of Perl's system abstraction, which we'll see
later: C<PerlMem_malloc> is either your system's C<malloc>, or Perl's
Now we pass Perl the command line options, and tell it to go:
- exitstatus = perl_parse(my_perl, xs_init, argc, argv, (char **)NULL);
- if (!exitstatus)
- perl_run(my_perl);
+ exitstatus = perl_parse(my_perl, xs_init, argc, argv, (char **)NULL);
+ if (!exitstatus)
+ perl_run(my_perl);
- exitstatus = perl_destruct(my_perl);
+ exitstatus = perl_destruct(my_perl);
- perl_free(my_perl);
+ perl_free(my_perl);
C<perl_parse> is actually a wrapper around C<S_parse_body>, as defined
in F<perl.c>, which processes the command line options, sets up any
C<runops_standard> function in F<run.c>; more specifically, it's done by
these three innocent looking lines:
- while ((PL_op = CALL_FPTR(PL_op->op_ppaddr)(aTHX))) {
+ while ((PL_op = PL_op->op_ppaddr(aTHX))) {
PERL_ASYNC_CHECK();
}
=back
The C<-Wtraditional> is another example of the annoying tendency of
-gcc to bundle a lot of warnings under one switch -- it would be
-impossible to deploy in practice because it would complain a lot -- but
+gcc to bundle a lot of warnings under one switch (it would be
+impossible to deploy in practice because it would complain a lot) but
it does contain some warnings that would be beneficial to have available
on their own, such as the warning about string constants inside macros
containing the macro arguments: this behaved differently pre-ANSI
arranges for two C<NV>s to be placed into C<left> and C<right> - let's
slightly expand it:
- #define dPOPTOPnnrl_ul NV right = POPn; \
- SV *leftsv = TOPs; \
- NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0
+ #define dPOPTOPnnrl_ul NV right = POPn; \
+ SV *leftsv = TOPs; \
+ NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0
C<POPn> takes the SV from the top of the stack and obtains its NV either
directly (if C<SvNOK> is set) or by calling the C<sv_2nv> function.
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
so instead of this:
- print 'not ' unless "1.20.300.4000" eq sprintf "%vd", pack("U*",1,20,300,4000);
+ print 'not ' unless "1.20.300.4000" eq sprintf "%vd",
+ pack("U*",1,20,300,4000);
print "ok $test\n"; $test++;
we can write the more sensible (see L<Test::More> for a full
Now we'll test that we got that space-at-the-beginning business right:
is( "1.20.300.4000", sprintf "%vd", pack(" U*",1,20,300,4000),
- " with spaces at the beginning" );
+ " with spaces at the beginning" );
And finally we'll test that we don't make Unicode strings if C<U> is B<not>
the first active format:
If the pattern begins with a C<U>, the resulting string will be treated
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
-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!
+ 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.
=head2 Patching a core module
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 L<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
them out), but it basically works that way. Everything else lives in
F<t/>.
+Testing of warning messages is often separately done by using expect scripts in
+F<t/lib/warnings>. This is because much of the setup for them is already done
+for you.
+
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>.
Tests for perl's built in functions that don't fit into any of the
other directories.
-=item F<t/pod/>
-
-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/>.
-
=item F<t/re/>
Tests for regex related functions or behaviour. (These used to live
decision of which to use depends on what part of the test suite you're
working on. This is a measure to prevent a high-level failure (such
as Config.pm breaking) from causing basic functionality tests to fail.
+If you write your own test, use the L<Test Anything Protocol|TAP>.
=over 4
The following are common causes of compilation and/or execution
failures, not common to Perl as such. The C FAQ is good bedtime
reading. Please test your changes with as many C compilers and
-platforms as possible -- we will, anyway, and it's nice to save
+platforms as possible; we will, anyway, and it's nice to save
oneself from public embarrassment.
If using gcc, you can add the C<-std=c89> option which will hopefully
characters have different meanings depending on the locale. Absent a locale,
currently these extra characters are generally considered to be unassigned,
and this has presented some problems.
-This is scheduled to be changed in 5.12 so that these characters will
+This is being changed starting in 5.12 so that these characters will
be considered to be Latin-1 (ISO-8859-1).
=item *
#endif
How does the HAS_QUUX become defined where it needs to be? Well, if
-Foonix happens to be UNIXy enough to be able to run the Configure
+Foonix happens to be Unixy enough to be able to run the Configure
script, and Configure has been taught about detecting and testing
quux(), the HAS_QUUX will be correctly defined. In other platforms,
the corresponding configuration step will hopefully do the same.
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
+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:
+L</PERL_DESTRUCT_LEVEL> for more information), you have to set the
+environment variable PERL_DESTRUCT_LEVEL to 2.
+
+For csh-like shells:
setenv PERL_DESTRUCT_LEVEL 2
-and for Bourne-type shells:
+For Bourne-type shells:
PERL_DESTRUCT_LEVEL=2
export PERL_DESTRUCT_LEVEL
-or in UNIXy environments you can also use the C<env> command:
+In Unixy environments you can also use the C<env> command:
env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ...
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
+ 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
=head2 Gprof Profiling
-gprof is a profiling tool available in many UNIX platforms,
+gprof is a profiling tool available in many Unix platforms,
it uses F<statistical time-sampling>.
You can build a profiled version of perl called "perl.gprof" by
quick hint:
- $ sh Configure -des -Doptimize='-g' -Accflags='-fprofile-arcs -ftest-coverage' \
+ $ sh Configure -des -Dusedevel -Doptimize='-g' \
+ -Accflags='-fprofile-arcs -ftest-coverage' \
-Aldflags='-fprofile-arcs -ftest-coverage' && make perl.gcov
$ rm -f regexec.c.gcov regexec.gcda
$ ./perl.gcov
https://perl5.git.perl.org / perl5.git / blobdiff