ext/Devel/PPPort/HACKERS

   1 =head1 NAME
   2
   3 HACKERS - Devel::PPPort internals for hackers
   4
   5 =head1 SYNOPSIS
   6
   7 So you probably want to hack C<Devel::PPPort>?
   8
   9 Well, here's some information to get you started with what's
  10 lying around in this distribution.
  11
  12 =head1 DESCRIPTION
  13
  14 =head2 How to build 105 versions of Perl
  15
  16 C<Devel::PPPort> supports Perl versions between 5.003 and bleadperl.
  17 To guarantee this support, I need some of these versions on my
  18 machine. I currently have 105 different Perl version/configuration
  19 combinations installed on my laptop.
  20
  21 As many of the old Perl distributions need patching to compile
  22 cleanly on newer systems (and because building 105 Perls by hand
  23 just isn't fun), I wrote a tool to build all the different
  24 versions and configurations. You can find it in F<devel/buildperl.pl>.
  25 It can currently build the following Perl releases:
  26
  27     5.003
  28     5.004 - 5.004_05
  29     5.005 - 5.005_04
  30     5.6.x
  31     5.7.x
  32     5.8.x
  33     5.9.x
  34
  35 =head2 Fully automatic API checks
  36
  37 Knowing which parts of the API are not backwards compatible and
  38 probably need C<Devel::PPPort> support is another problem that's
  39 not easy to deal with manually. If you run
  40
  41     perl Makefile.PL --with-apicheck
  42
  43 a C file is generated by F<parts/apicheck.pl> that is compiled
  44 and linked with C<Devel::PPPort>. This C file has the purpose of
  45 using each of the public API functions/macros once.
  46
  47 The required information is derived from C<parts/embed.fnc> (just
  48 a copy of bleadperl's C<embed.fnc>) and C<parts/apidoc.fnc> (which
  49 is generated by F<devel/mkapidoc.sh> and simply collects the rest
  50 of the apidoc entries spread over the Perl source code).
  51 The generated C file C<apicheck.c> is currently about 500k in size
  52 and takes quite a while to compile.
  53
  54 Usually, C<apicheck.c> won't compile with older perls. And even if
  55 it compiles, there's still a good chance of the dynamic linker
  56 failing at C<make test> time. But that's on purpose!
  57
  58 We can use these failures to find changes in the API automatically.
  59 The two Perl scripts F<devel/mktodo> and F<devel/mktodo.pl>
  60 repeatedly run C<Devel::PPPort> with the apicheck code through
  61 all different versions of perl. Scanning the output of the compiler
  62 and the dynamic linker for errors, the files in F<parts/todo/> are
  63 generated. These files list all parts of the public API that don't
  64 work with less than a certain version of Perl.
  65
  66 This information is in turn used by F<parts/apicheck.pl> to mask
  67 API calls in the generated C file for these versions, so the
  68 process can be stopped by the time F<apicheck.c> compiles cleanly
  69 and the dynamic linker is happy. (Actually, this process may generate
  70 false positives, so by default each API call is checked once more
  71 afterwards.)
  72
  73 Running C<devel/mktodo> takes about an hour, depending of course
  74 on the machine you're running it on. If you run it with
  75 the C<--nocheck> option, it won't recheck the API calls that failed
  76 in the compilation stage and it'll take significantly less time.
  77 Running with C<--nocheck> should usually be safe.
  78
  79 When running C<devel/mktodo> with the C<--base> option, it will
  80 generate the I<baseline> todo files by disabling all functionality
  81 provided by C<Devel::PPPort>. These are required for implementing
  82 the C<--compat-version> option of the C<ppport.h> script. The
  83 baseline todo files hold the information about which version of
  84 Perl lacks a certain part of the API.
  85
  86 However, only the documented public API can be checked this way.
  87 And since C<Devel::PPPort> provides more macros, these would not be
  88 affected by C<--compat-version>. It's the job of F<devel/scanprov>
  89 to figure out the baseline information for all remaining provided
  90 macros by scanning the include files in the F<CORE> directory of
  91 various Perl versions.
  92
  93 The whole process isn't platform independent. It has currently been
  94 tested only under Linux, and it definitely requires at least C<gcc> and
  95 the C<nm> utility.
  96
  97 It's not very often that one has to regenerate the baseline and todo
  98 files. If you have to, you can either run F<devel/regenerate> or just
  99 execute the following steps by hand:
 100
 101 =over 4
 102
 103 =item *
 104
 105 You need a whole bunch of different Perls. The more, the better.
 106 You can use F<devel/buildperl.pl> to build them. I keep my perls
 107 in F</tmp/perl>, so most of the tools take this as a default.
 108
 109 =item *
 110
 111 Remove all existing todo files in the F<parts/base> and
 112 F<parts/todo> directories.
 113
 114 =item *
 115
 116 Update the API information. Copy the latest F<embed.fnc> file from
 117 bleadperl to the F<parts> directory and run F<devel/mkapidoc.sh> to
 118 collect the remaining information in F<parts/apidoc.fnc>.
 119
 120 =item *
 121
 122 Build the new baseline by running
 123
 124     perl devel/mktodo --base
 125
 126 in the root directory of the distribution. When it's finished,
 127 move all files from the F<parts/todo> directory to F<parts/base>.
 128
 129 =item *
 130
 131 Build the new todo files by running
 132
 133     perl devel/mktodo
 134
 135 in the root directory of the distribution.
 136
 137 =item *
 138
 139 Finally, add the remaining baseline information by running
 140
 141     perl Makefile.PL && make
 142     perl devel/scanprov write
 143
 144 =back
 145
 146 =head2 Implementation
 147
 148 Residing in F<parts/inc/> is the "heart" of C<Devel::PPPort>. Each
 149 of the files implements a part of the supported API, along with
 150 hints, dependency information, XS code and tests.
 151 The files are in a POD-like format that is parsed using the
 152 functions in F<parts/ppptools.pl>.
 153
 154 The scripts F<PPPort_pm.PL>, F<PPPort_xs.PL> and F<mktests.PL> all
 155 use the information in F<parts/inc/> to generate the main module
 156 F<PPPort.pm>, the XS code in F<PPPort.xs> and various test files
 157 in F<t/>.
 158
 159 All of these files could be generated on the fly while building
 160 C<Devel::PPPort>, but not having the tests in C<t/> and not having
 161 F<PPPort.xs> will confuse Configure and TEST/harness in the core.
 162 Not having F<PPPort.pm> will be bad for viewing the docs on
 163 C<search.cpan.org>. So unfortunately, it's unavoidable to put
 164 some redundancy into the package.
 165
 166 =head2 Adding stuff to Devel::PPPort
 167
 168 First, check if the code you plan to add fits into one of the
 169 existing files in F<parts/inc/>. If not, just start a new one and
 170 remember to include it from within F<PPPort_pm.PL>.
 171
 172 Each file holds all relevant data for implementing a certain part
 173 of the API:
 174
 175 =over 2
 176
 177 =item *
 178
 179 A list of the provided API in the C<=provides> section.
 180
 181 =item *
 182
 183 The implementation to add to F<ppport.h> in the C<=implementation>
 184 section.
 185
 186 =item *
 187
 188 The code required to add to PPPort.xs for testing the implementation.
 189 This code goes into the C<=xshead>, C<=xsinit>, C<=xsmisc>, C<=xsboot>
 190 and C<=xsubs> section. Have a look at the template at the bottom
 191 of F<PPPort_xs.PL> to see where the code ends up.
 192
 193 =item *
 194
 195 The tests in the C<=tests> section. Remember not to use any fancy
 196 modules or syntax elements, as the test code should be able to run
 197 with Perl 5.003, which, for example, doesn't support C<my> in
 198 C<for>-loops:
 199
 200     for my $x (1, 2, 3) { }    # won't work with 5.003
 201
 202 You can use C<ok()> to report success or failure:
 203
 204     ok($got == 42);
 205     ok($got, $expected);
 206
 207 Regular expressions are not supported as the second argument to C<ok>,
 208 because older perls do not support the C<qr> operator.
 209
 210 =back
 211
 212 It's usually the best approach to just copy an existing file and
 213 use it as a template.
 214
 215 =head2 Implementation Hints
 216
 217 In the C<=implementation> section, you can use
 218
 219   __UNDEFINED__ macro    some definition
 220
 221 instead of
 222
 223   #ifndef macro
 224   #  define macro    some definition
 225   #endif
 226
 227 The macro can have optional arguments and the definition can even
 228 span multiple lines, like in
 229
 230   __UNDEFINED__ SvMAGIC_set(sv, val) \
 231                 STMT_START { assert(SvTYPE(sv) >= SVt_PVMG); \
 232                 (((XPVMG*) SvANY(sv))->xmg_magic = (val)); } STMT_END
 233
 234 This usually makes the code more compact and readable. And you
 235 only have to add C<__UNDEFINED__> to the C<=provided> section.
 236
 237 Version checking can be tricky if you want to do it correct.
 238 You can use
 239
 240   #if { VERSION < 5.9.3 }
 241
 242 instead of
 243
 244   #if ((PERL_VERSION < 9) || (PERL_VERSION == 9 && PERL_SUBVERSION < 3))
 245
 246 The version number can be either of the new form C<5.x.x> or of the older
 247 form C<5.00x_yy>. Both are translated into the correct preprocessor
 248 statements. It is also possible to combine this with other statements:
 249
 250   #if { VERSION >= 5.004 } && !defined(sv_vcatpvf)
 251     /* a */
 252   #elif { VERSION < 5.004_63 } && { VERSION != 5.004_05 }
 253     /* b */
 254   #endif
 255
 256 This not only works in the C<=implementation> section, but also in
 257 the C<=xsubs>, C<=xsinit>, C<=xsmisc>, C<=xshead> and C<=xsboot> sections.
 258
 259 =head2 Testing
 260
 261 To automatically test C<Devel::PPPort> with lots of different Perl
 262 versions, you can use the F<soak> script. Just pass it a list of
 263 all Perl binaries you want to test.
 264
 265 =head2 Special Makefile targets
 266
 267 You can use
 268
 269     make regen
 270
 271 to regenerate all of the autogenerated files. To get rid of all
 272 generated files (except for F<parts/todo/*> and F<parts/base/*>),
 273 use
 274
 275     make purge_all
 276
 277 That's it.
 278
 279 =head2 Submitting Patches
 280
 281 If you've added some functionality to C<Devel::PPPort>, please
 282 consider submitting a patch with your work to either the author
 283 (E<lt>mhx@cpan.orgE<gt>) or to the CPAN Request Tracker at
 284 L<http://rt.cpan.org>.
 285
 286 When submitting patches, please only add the relevant changes
 287 and don't include the differences of the generated files. You
 288 can use the C<purge_all> target to delete all autogenerated
 289 files.
 290
 291 =head1 COPYRIGHT
 292
 293 Version 3.x, Copyright (C) 2004-2006, Marcus Holland-Moritz.
 294
 295 Version 2.x, Copyright (C) 2001, Paul Marquess.
 296
 297 Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
 298
 299 This program is free software; you can redistribute it and/or
 300 modify it under the same terms as Perl itself.
 301
 302 =head1 SEE ALSO
 303
 304 See L<ppport.h> and L<devel/regenerate>.
 305
 306 =cut
 307