Upgrade to Devel::PPPort 3.07

[p5sagit/p5-mst-13.2.git] / ext / Devel / PPPort / HACKERS

diff --git a/ext/Devel/PPPort/HACKERS b/ext/Devel/PPPort/HACKERS
index 7e386bd..42acd38 100644 (file)
--- a/ext/Devel/PPPort/HACKERS
+++ b/ext/Devel/PPPort/HACKERS
@@ -178,8 +178,8 @@ section.
 
 The code required to add to PPPort.xs for testing the implementation.
 This code goes into the C<=xshead>, C<=xsinit>, C<=xsmisc>, C<=xsboot>
-and C<=xsubs> section. Have a look at the template in F<PPPort_xs.PL>
-to see where the code ends up.
+and C<=xsubs> section. Have a look at the template at the bottom
+of F<PPPort_xs.PL> to see where the code ends up.
 
 =item *
 
@@ -188,15 +188,65 @@ modules or syntax elements, as the test code should be able to run
 with Perl 5.003, which, for example, doesn't support C<my> in
 C<for>-loops:
 
-    for my $x (1, 2, 3) { }    # won't work
+    for my $x (1, 2, 3) { }    # won't work with 5.003
 
-You can use C<ok()> to report success or failure.
+You can use C<ok()> to report success or failure:
+
+    ok($got == 42);
+    ok($got, $expected);
+
+Regular expressions are not supported as the second argument to C<ok>,
+because older perls do not support the C<qr> operator.
 
 =back
 
 It's usually the best approach to just copy an existing file and
 use it as a template.
 
+=head2 Implementation Hints
+
+In the C<=implementation> section, you can use
+
+  __UNDEFINED__ macro    some definition
+
+instead of
+
+  #ifndef macro
+  #  define macro    some definition
+  #endif
+
+The macro can have optional arguments and the definition can even
+span multiple lines, like in
+
+  __UNDEFINED__ SvMAGIC_set(sv, val) \
+                STMT_START { assert(SvTYPE(sv) >= SVt_PVMG); \
+                (((XPVMG*) SvANY(sv))->xmg_magic = (val)); } STMT_END
+
+This usually makes the code more compact and readable. And you
+only have to add C<__UNDEFINED__> to the C<=provided> section.
+
+Version checking can be tricky if you want to do it correct.
+You can use
+
+  #if { VERSION < 5.9.3 }
+
+instead of
+
+  #if ((PERL_VERSION < 9) || (PERL_VERSION == 9 && PERL_SUBVERSION < 3))
+
+The version number can be either of the new form C<5.x.x> or of the older
+form C<5.00x_yy>. Both are translated into the correct preprocessor
+statements. It is also possible to combine this with other statements:
+
+  #if { VERSION >= 5.004 } && !defined(sv_vcatpvf)
+    /* a */ 
+  #elif { VERSION < 5.004_63 } && { VERSION != 5.004_05 }
+    /* b */
+  #endif
+
+This not only works in the C<=implementation> section, but also in
+the C<=xsubs>, C<=xsinit>, C<=xsmisc>, C<=xshead> and C<=xsboot> sections.
+
 =head2 Testing
 
 To automatically test C<Devel::PPPort> with lots of different Perl
@@ -217,9 +267,21 @@ use
 
 That's it.
 
+=head2 Submitting Patches
+
+If you've added some functionality to C<Devel::PPPort>, please
+consider submitting a patch with your work to either the author
+(E<lt>mhx@cpan.orgE<gt>) or to the CPAN Request Tracker at
+L<http://rt.cpan.org>.
+
+When submitting patches, please only add the relevant changes
+and don't include the differences of the generated files. You
+can use the C<purge_all> target to delete all autogenerated
+files.
+
 =head1 COPYRIGHT
 
-Version 3.x, Copyright (C) 2004-2005, Marcus Holland-Moritz.
+Version 3.x, Copyright (C) 2004-2006, Marcus Holland-Moritz.
 
 Version 2.x, Copyright (C) 2001, Paul Marquess.