=over 4
-=item It's easier
+=item It's easier to rsync the source tree
Since you don't have to apply the patches yourself, you are sure all
files in the source tree are in the right state.
=over 4
-=item It's easier
+=item It's easier to rsync the patches
If you have more than one machine that you want to keep in track with
bleadperl, it's easier to rsync the patches only once and then apply
}
}
-< finish this later >
+# finish this later #
=head2 Patching
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:
+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.
+
+t/op/pack.t has a sensible ok() function, but if it didn't we could
+write one easily.
+
+ my $test = 1;
+ sub ok {
+ my($ok, $name) = @_;
+
+ # You have to do it this way or VMS will get confused.
+ print $ok ? "ok $test - $name\n" : "not ok $test - $name\n";
+
+ printf "# Failed test at line %d\n", (caller)[2] unless $ok;
+
+ $test++;
+ return $ok;
+ }
+
+so instead of this:
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 (somewhat) more sensible:
+
+ ok( "1.20.300.4000" eq sprintf "%vd", pack("U*",1,20,300,4000),
+ "U* produces unicode" );
+
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++;
+ ok( "1.20.300.4000" eq sprintf "%vd", pack(" U*",1,20,300,4000),
+ " 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:
- print 'not ' unless v1.20.300.4000 ne
- sprintf "%vd", pack("C0U*",1,20,300,4000);
- print "ok $test\n"; $test++;
+ ok( v1.20.300.4000 ne sprintf "%vd", pack("C0U*",1,20,300,4000),
+ "U* not first isn't unicode" );
Mustn't forget to change the number of tests which appears at the top, or
else the automated tester will get confused:
maintainer keep the CPAN version in sync with the core version without
constantly scanning p5p.
+=head2 Adding a new function to the core
+
+If, as part of a patch to fix a bug, or just because you have an
+especially good idea, you decide to add a new function to the core,
+discuss your ideas on p5p well before you start work. It may be that
+someone else has already attempted to do what you are considering and
+can give lots of good advice or even provide you with bits of code
+that they already started (but never finished).
+
+You have to follow all of the advice given above for patching. It is
+extremely important to test any addition thoroughly and add new tests
+to explore all boundary conditions that your new function is expected
+to handle. If your new function is used only by one module (e.g. toke),
+then it should probably be named S_your_function (for static); on the
+other hand, if you expect it to accessable from other functions in
+Perl, you should name it Perl_your_function. See L<perlguts/Internal Functions>
+for more details.
+
+The location of any new code is also an important consideration. Don't
+just create a new top level .c file and put your code there; you would
+have to make changes to Configure (so the Makefile is created properly),
+as well as possibly lots of include files. This is strictly pumpking
+business.
+
+It is better to add your function to one of the existing top level
+source code files, but your choice is complicated by the nature of
+the Perl distribution. Only the files that are marked as compiled
+static are located in the perl executable. Everything else is located
+in the shared library (or DLL if you are running under WIN32). So,
+for example, if a function was only used by functions located in
+toke.c, then your code can go in toke.c. If, however, you want to call
+the function from universal.c, then you should put your code in another
+location, for example util.c.
+
+In addition to writing your c-code, you will need to create an
+appropriate entry in embed.pl describing your function, then run
+'make regen_headers' to create the entries in the numerous header
+files that perl needs to compile correctly. See L<perlguts/Internal Functions>
+for information on the various options that you can set in embed.pl.
+You will forget to do this a few (or many) times and you will get
+warnings during the compilation phase. Make sure that you mention
+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
+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.
+
+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
+Configure options as you can (e.g. MULTIPLICITY). If you have
+profiling or memory tools, see L<EXTERNAL TOOLS FOR DEBUGGING PERL>
+below for how to use them to futher test your code. Remember that
+most of the people on P5P are doing this on their own time and
+don't have the time to debug your code.
=head2 Writing a test
Depending on your platform there are various of profiling Perl.
There are two commonly used techniques of profiling executables:
-E<statistical time-sampling> and E<basic-block counting>.
+I<statistical time-sampling> and I<basic-block counting>.
The first method takes periodically samples of the CPU program
counter, and since the program counter can be correlated with the code
good idea for profiling), the second problem is usually kept in guard
by the profiling tools themselves.
-The second method divides up the generated code into E<basic blocks>.
+The second method divides up the generated code into I<basic blocks>.
Basic blocks are sections of code that are entered only in the
beginning and exited only at the end. For example, a conditional jump
starts a basic block. Basic block profiling usually works by
-E<instrumenting> the code by adding E<enter basic block #nnnn>
+I<instrumenting> the code by adding I<enter basic block #nnnn>
book-keeping code to the generated code. During the execution of the
code the basic block counters are then updated appropriately. The
caveat is that the added extra code can skew the results: again, the
=head2 GCC gcov Profiling
-Starting from GCC 3.0 E<basic block profiling> is officially available
+Starting from GCC 3.0 I<basic block profiling> is officially available
for the GNU CC.
You can build a profiled version of perl called F<perl.gcov> by
Pixie is a profiling tool available on IRIX and Tru64 (aka Digital
UNIX aka DEC OSF/1) platforms. Pixie does its profiling using
-E<basic-block counting>.
+I<basic-block counting>.
You can build a profiled version of perl called F<perl.pixie> by
invoking the make target "perl.pixie" (what is required is that Perl
projects / p5sagit/p5-mst-13.2.git / blobdiff