This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix typos in HACKERS; add clarification
[perl5.git] / dist / 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 backport something
15
16 First, make sure that what you want to backport is documented.  If it's worth
17 backporting, it surely is worth documenting.  Send a documentation patch to 
18 L<perlbug@perl.org|mailto:perlbug@perl.org> if necessary.  Also,
19 C<Devel::PPPort> cannot automatically generate proper information about the
20 item without at least knowing its API prototype.  It can get this from
21 F<embed.fnc> if the item is a function, but if it is a macro, there needs to be
22 at least a S<C<=for apidoc>> line for C<Devel::PPPort> to be able to figure
23 things out on its own.
24
25 Next, figure out where to place your implementation.  Look at all the files in
26 F<parts/inc/> for one that fits what you're planning.  If there isn't one,
27 just start a new one and remember to include it from within F<PPPort_pm.PL>.
28 If you do create a new file, it's usually the best approach to just copy an
29 existing file and use it as a template.
30
31 Each file holds all relevant data for implementing a certain part
32 of the API:
33
34 =over 2
35
36 =item *
37
38 A list of the provided API in the C<=provides> section.
39
40 =item *
41
42 The optional C<=dontwarn> section is used to suppress warnings about particular
43 API elements.  Don't use this unless you get such a warning, and be sure to
44 think about using other other alternatives before resorting to adding something
45 in this section.
46
47 =item *
48
49 The implementation to add to F<ppport.h> in the C<=implementation>
50 section.  See L</Implementation Section Details>.
51
52 =item *
53
54 The code required to add to PPPort.xs for testing the implementation.
55 This code goes into the C<=xshead>, C<=xsinit>, C<=xsmisc>, C<=xsboot>
56 and C<=xsubs> section. Have a look at the template at the bottom
57 of F<RealPPPort_xs.PL> to see where the code ends up.
58
59 =item *
60
61 The tests in the C<=tests> section. Remember not to use any fancy
62 modules or syntax elements, as the test code needs to be able to run
63 with Perl 5.003.  (This is because Devel::PPPort itself will run all test files
64 in the process of generating the information about when a feature came into
65 existence.)  This means, for example
66
67 =over
68
69 =item C<my> isn't supported in C<for>-loops
70
71     for my $x (1, 2, 3) { }    # won't work with 5.003
72
73 Instead declare C<$x> just before the statement
74
75 =item The postfix C<for> statement modifier isn't supported
76
77     foo for 1..2
78
79 won't compile.  Instead enclose C<foo> in a loop.
80
81 =item You can't use plain C<qr//>
82
83 Instead, wrap it in a string eval C<eval "qr//">, and be sure it's skipped at
84 execution time on perls earlier than 5.005
85
86 =back
87
88 You can use C<ok()> to report success or failure:
89
90  ok($got, $expected, 'name');
91  ok($got == 42);     # Doesn't give good runtime diagnostics
92
93  ok($got, eval "qr/foo/", 'name') # But don't execute this statement
94                                   # on perls earlier than 5.005
95
96 =back
97
98 In all sections, lines that begin with C<##> are completely ignored.
99
100 =head2 Implementation Section Details
101
102 You can implement API elements via C functions or macros, or simple variables.
103 For a function, just place its body in this C<=implementation> section.  But it
104 is preferable to use a macro if feasible.  Otherwise, the user must explicitly
105 request that it get loaded, by defining a C<NEED_I<function>> (or I<variable>)
106 as described in F<ppport.h>.
107
108 =over
109
110 =item __UNDEFINED__
111
112 If you add the line C<__UNDEFINED__> to the C<=provides> section, you can use
113 lines like this in the C<=implementation> section:
114
115   __UNDEFINED__ macro    some definition
116
117 to both define C<macro> and indicate that it is provided by F<ppport.h>.  This
118 replaces these C<=implementation> section lines:
119
120   #ifndef macro
121   #  define macro    some definition
122   #endif
123
124 besides automagically making it be considered to be provided.  C<macro> can
125 have optional arguments and the definition can even span multiple lines, like
126 in
127
128   __UNDEFINED__ SvMAGIC_set(sv, val) \
129                 STMT_START { assert(SvTYPE(sv) >= SVt_PVMG); \
130                 (((XPVMG*) SvANY(sv))->xmg_magic = (val)); } \
131                 STMT_END
132
133 This usually makes the code more compact and readable.
134
135 But you should only use this on things that you plan to publicly provide.  If
136 something, such as a mnemonic for a constant needs to be defined but isn't
137 really needed for the public at large to know about, you should use
138
139  __UNDEF_NOT_PROVIDED__ macro   some definition
140
141 instead.  To avoid name space conflicts, follow what's in L</Helper macros>,
142 below.
143
144 =item Helper macros
145
146 If you need to define a helper macro which is not part of C<Devel::PPPort> API
147 and its usage is only for the definition of other C<Devel::PPPort> macros, then
148 use the C<D_PPP_> prefix for this macro name (e.g. C<D_PPP_SVPV_NOLEN_LP_ARG>).
149 This suppresses any warnings when a macro is defined which is not part of the
150 Perl public API.
151
152 =item Version numbers
153
154 Version checking can be tricky to get correct.
155 You can use
156
157   #if { VERSION < 5.9.3 }
158
159 instead of
160
161   #if ((PERL_VERSION < 9) \
162     || (PERL_VERSION == 9 && PERL_SUBVERSION < 3))
163
164 The version number can be either of the new form C<5.x.x> or the older
165 form C<5.00x_yy>. Both are translated into the correct preprocessor
166 statements. It is also possible to combine this with other statements:
167
168   #if { VERSION >= 5.004 } && !defined(sv_vcatpvf)
169     /* a */
170   #elif { VERSION < 5.004_63 } && { VERSION != 5.004_05 }
171     /* b */
172   #endif
173
174 This not only works in the C<=implementation> section, but also in
175 the C<=xsubs>, C<=xsinit>, C<=xsmisc>, C<=xshead> and C<=xsboot> sections.
176
177 =item Hints
178
179 If you add a comment like so:
180
181  /* Hint: PL_expect, PL_copline, PL_rsfp
182     paragraphs of stuff about foo you want to have
183     shown when ppport.h outputs something about PL_expect or
184     PL_copline or PL_rsfp
185  */
186
187 Earlier versions of F<ppport.h> required an asterisk at the beginning of every
188 continuation line, or else the content would be silently dropped.
189
190 =item Warnings
191
192 A more serious caution about C<foo> can be displayed by instead saying
193
194  /* Warning: PL_expect, PL_copline, PL_rsfp
195     paragraphs of stuff about foo you want to have
196     shown when ppport.h outputs something about PL_expect or
197     PL_copline or PL_rsfp
198  */
199
200 Earlier versions of F<ppport.h> required an asterisk at the beginning of every
201 continuation line, or else the content would be silently dropped.
202
203 =item Replace
204
205 When F<ppport.h> is run on a file(s), you can cause it to automatically flag
206 occurrences of the constructs you specify, encouraging the author to replace
207 them with different (presumably better) ones.  These also are used in any
208 suggested edits and generated patches.
209
210 There are three ways to do this
211
212 =over 4
213
214 =item in-line comment
215
216 You can add a trailing comment like so:
217
218  #define bar foo    /* Replace */
219  __UNDEFINED__ bar foo  /* Replace */
220
221 These say that C<foo> should be replaced by C<bar>.  NOT the other way around.
222
223 =item separate comment
224
225 For situations not amenable to the above, you can say
226
227  /* Replace foo with bar */
228
229 =item define a replacement region
230
231 It you have several replacements, you can group them together like so:
232
233  /* Replace: 1 */
234  #define foo bar
235  #define bat baz
236  /* Replace: 0 */
237
238 These replace C<foo> with C<bar>; C<bat> with C<baz>.
239
240 =back
241
242 =item Dependencies
243
244 F<ppport.h> automatically gathers information as to what functions are
245 dependent on what other things from inspecting the source, but if this is
246 insufficient for you, you can add lines like the following:
247
248  /* foo, bar depends on baz, bat */
249
250 Each of C<foo>, C<bar> depends on each of C<baz>, C<bat>.
251
252 =back
253
254 =head2 Testing
255
256 After you have furnished your implementation, you need to test it.
257
258 =head2 Special Makefile targets
259
260 You can use
261
262     make regen
263
264 to regenerate all of the autogenerated files. To get rid of all
265 generated files (except for F<parts/todo/*> and F<parts/base/*>),
266 use
267
268     make purge_all
269
270 That's it.
271
272 To automatically test C<Devel::PPPort> with lots of different Perl
273 versions, you can use the F<soak> script. Just pass it a list of
274 all Perl binaries you want to test.
275
276 =head2 Regenerating F<ppport.h> and F<PPPort.pm>
277
278 C<Devel::PPPort> keeps two directories of generated files, in F<parts/base> and
279 F<parts/todo>.  The files in each are named after Perl version numbers.  When a
280 function or macro came into existence is indicated by placing its name in the
281 corresponding file in F<parts/base>.  The files in F<parts/todo> are the same,
282 except they indicate the earliest release that F<ppport.h> supports the
283 element.  The delta is effectively what F<ppport.h> buys you.
284
285 The generation process described in this section creates these files.  It does
286 so by examining as many perl versions as are available to it.  It tries to make
287 sure each element actually compiles, and it runs the test scripts you have
288 furnished on every version.
289
290 Ideally, this should be done before every release that includes new backporting
291 and/or when blead has added new public API.  At a minimum, it should be done as
292 the next major Perl release comes out.
293
294 The process isn't platform independent. It has currently been tested only under
295 Linux, and it definitely requires at least C<gcc> and the C<nm> utility.
296 The process used to be problematic, with random failures.  But it has now been
297 fixed to be reliable.
298
299 Before starting the regeneration, you need to have gathered certain data.
300 (Options listed below apply to the tools that eventually will use the data, and
301 which are described further below).
302
303 =over 4
304
305 =item *
306
307 You will first need a whole bunch of different Perls, the more, the better, but
308 only one per version tag (which one is random) will actually get used.
309 dromedary has a sufficient set.  They should all have the same Configure
310 options with respect to what functions and macros are enabled.  For example,
311 they should all be threaded, or all non-threaded.  A mixture will screw up the
312 results.  Similarly, they should all or none have quad math (at least as far
313 back as that became available).  You can use F<devel/buildperl.pl> to build
314 them.
315
316 Previous maintainers of this module kept those perls in
317 F</tmp/perl/install/default>, so most of the tools use this as a default, but
318 you'll likely simply use the C<--install=> option to specify where.  This
319 should be a path where a S<C<make install>> has been done, so has immediate
320 subdirectories of C</bin> and C</lib>.  C</bin> should contain the binaries.
321 It will use all files in this directory whose names begin with C<perl5>.
322
323 Actually, not all the binaries need be in this directory.  You can specify
324 additional places to look since C<--install=> takes a comma separated list of
325 directories.
326
327 =item *
328
329 You also need a freshly built bleadperl.  The C<--blead=I<path>> option should
330 be used to specify it.  (Some of the tools have a default of C<bleadperl-debug>
331 if this option is omitted.)  Again, it needs the same Configure options as the
332 earlier versions had.
333
334 =item *
335
336 And you will need updated API information. Copy the latest F<embed.fnc> file
337 from bleadperl to the F<parts> directory and run F<devel/mkapidoc.pl> to
338 collect the remaining information in F<parts/apidoc.fnc>.
339
340 =item *
341
342 The final step before regenerating everything is to run
343 F</devel/mkppport_fnc.pl> to update the F</parts/ppport.fnc> file.
344
345 =back
346
347 Having done this, run F<devel/regenerate> which wraps the following steps
348 (which you could instead do by hand, but it's easy to forget things):
349
350 =over
351
352 =item *
353
354 It first does some sanity checking
355
356 =item *
357
358 Then it asks you if it's ok to remove all existing todo files in the
359 F<parts/base> and F<parts/todo> directories.  If you answer no, the process
360 aborts.
361
362 This is crtical to getting accurate results.
363
364 =item *
365
366 It builds the new baseline by running
367
368     perl devel/mktodo --base
369
370 in the root directory of the distribution.
371
372 If there are warnings in blead, it will ask you to examine them, and to ok if
373 it's all right to go ahead.  If there are issues with blead, everything
374 following could be wrong.
375
376 =item *
377
378 It builds the new todo files by running
379
380     perl devel/mktodo
381
382 in the root directory of the distribution.
383
384 =item *
385
386 Finally, it adds the remaining information by running
387
388     perl Makefile.PL && make
389     perl devel/scanprov --mode=write
390
391 =back
392
393 =head2 How to build gobs of versions of Perl
394
395 C<Devel::PPPort> supports Perl versions between 5.003 and bleadperl.
396 To guarantee this support, its good to have as many versions as possible to
397 test on.  dromedary currently has many such versions.
398
399 There is a tool to build all the different
400 versions and configurations. You can find it in F<devel/buildperl.pl>.
401 It can currently build the following Perl releases:
402
403     5.003
404     5.004 - 5.004_05
405     5.005 - 5.005_04
406     5.6.x
407     5.7.x
408     5.8.x
409     5.9.x
410     5.1x.x
411     5.2x.x
412     5.3x.x
413
414 =head2 Implementation
415
416 Knowing which parts of the API are not backwards compatible and
417 probably need C<Devel::PPPort> support is another problem that's
418 not easy to deal with manually. If you run
419
420     perl Makefile.PL --with-apicheck
421
422 a C file is generated by F<parts/apicheck.pl> that is compiled
423 and linked with C<Devel::PPPort>. This C file has the purpose of
424 using each of the public API functions/macros once.
425
426 The required information is derived from F<parts/embed.fnc> (just
427 a copy of bleadperl's F<embed.fnc>), F<parts/apidoc.fnc> (which
428 is generated by F<devel/mkapidoc.sh> and simply collects the rest
429 of the apidoc entries spread over the Perl source code) and
430 F<parts/ppport.fnc> (which lists the API provided purely by
431 Devel::PPPort, along with other elements that are tested only using
432 F<ppport.h>).
433
434 The generated C file (usually, F<apicheck.c>) won't compile as-is
435 with older perls. And even if it compiles, there's still a good chance of the
436 dynamic linker failing at C<make test> time. But that's on purpose!
437
438 We can use these failures to find changes in the API automatically.
439 The Perl script F<devel/mktodo> calls another script F<devel/mktodo.pl>
440 repeatedly to run C<Devel::PPPort> on version after version of perl, in
441 decreasing version order, so we start with blead and work backwards.  The
442 latter script generates an F<apicheck.c>.  It starts with the code that
443 successfully worked in the previously tested Perl version, which should be the
444 version one higher than the current one.  Call the current one I<n>, and the
445 previous one I<n+1>.  The items that fail to compile in I<n>, but did compile
446 in I<n+1> must have become available in I<n+1>.  We run the Linux command C<nm>
447 to find those undefined symbols in I<n>.  We change F<apicheck.c> to ignore
448 (through C<#ifdef>'s) those and recompile, repeating until F<apicheck.c>
449 successfully compiles, the dynamic linker is happy, and C<make test> runs on
450 this version.  Then we repeat the process for I<n-1>, and so on.  (Actually,
451 this process may generate false positives, so by default each failing API call
452 is checked again.  If possible, this is done by generating an F<apicheck.c> for
453 just the one failing API.)  Note that the make test is run using F<ppport.h>
454 during both passes.
455
456 Running F<devel/mktodo> currently takes a couple hours on dromedary.
457
458 If you run it with the C<--nocheck> option, it won't recheck the API calls
459 that failed in the compilation stage and it'll take significantly less time.
460 No one currently associated with maintaining this module understands under what
461 circumstances it is safe to run with C<--nocheck>.
462
463 By repeating the process over and over, we build up information on when every
464 element first became supported.  This information is stored in files in the
465 F<parts/base> directory, one file per version.  The file for version I<n+1> is
466 generated by running version I<n> of perl.
467
468 We actually want a second piece of information, which is how much F<ppport.h>
469 buys you.  What happens when regenerating is actually two entire runs through
470 all the perls.  The first is accomplished by calling F<devel/mktodo> with the
471 C<--base> option.  It automically will call F<devel/mktodo.pl> with each
472 version of perl, NOT using anything in F<ppport.h>.  When done the results
473 indicate  when each API element became available in stock perl, without using
474 F<ppport.h>.
475
476 And then the whole process is repeated, but this time F<ppport.h> is included.
477 The files are placed in F<parts/todo>.  Thus, at the end, we know when each
478 element became available in modified perl, using F<ppport.h>.
479
480 However, only the public API that is implemented as functions (and must appear
481 in F<embed.fnc>) plus macros whose calling sequence is documented can be
482 checked this way.  The final step in the process is calling F<devel/scanprov>.
483 It looks through the header files for when all the symbols provided by
484 C<Devel::PPPort> first became defined.  It doesn't test the symbols or try to
485 compile them, as it doesn't generally know the API, but it can tell that
486 something exists in release I<n+1> but not I<n> (by scanning the include files
487 in the F<CORE> directory of various Perl versions).  (It does know if a macro
488 has zero arguments or non-zero arguments, so it does get extra information from
489 the zero argument ones.)
490
491 =head2 Files
492
493 Residing in F<parts/inc/> is the "heart" of C<Devel::PPPort>. Each
494 of the files implements a part of the supported API, along with
495 hints, dependency information, XS code and tests.
496 The files are in a POD-like format that is parsed using the
497 functions in F<parts/ppptools.pl>.
498
499 The scripts F<PPPort_pm.PL>, F<RealPPPort_xs.PL> and F<mktests.PL> all
500 use the information in F<parts/inc/> to generate the main module
501 F<PPPort.pm>, the XS code in F<RealPPPort.xs> and various test files
502 in F<t/>.
503
504 You can get extra information from F<PPPort_pm.PL> by setting the environment
505 variable C<DPPP_CHECK_LEVEL> to 1 or 2.
506
507 All of these files could be generated on the fly while building
508 C<Devel::PPPort>, but not having the tests in F<t/> will confuse
509 TEST/harness in the core. Not having F<PPPort.pm> will be bad for
510 viewing the docs on C<search.cpan.org>. So unfortunately, it's
511 unavoidable to put some redundancy into the package.
512
513 =head2 Submitting Patches
514
515 If you've added some functionality to C<Devel::PPPort>, please
516 consider submitting a patch with your work to P5P by sending a pull request to
517
518 L<https://github.com/Dual-Life/Devel-PPPort/pulls>.
519
520 When submitting patches, please only add the relevant changes
521 and don't include the differences of the generated files. You
522 can use the C<purge_all> target to delete all autogenerated
523 files.
524
525 =head2 Integrating into the Perl core
526
527 When integrating this module into the Perl core, be sure to
528 remove the following files from the distribution. They are
529 either not needed or generated on the fly when building this
530 module in the core:
531
532   MANIFEST
533   META.yml
534   PPPort.pm
535
536 =head1 BUGS
537
538 No known bugs.
539
540 =head1 COPYRIGHT
541
542 Version 3.x, Copyright (C) 2004-2019, Marcus Holland-Moritz
543 and Perl 5 porters
544
545 Version 2.x, Copyright (C) 2001, Paul Marquess.
546
547 Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
548
549 This program is free software; you can redistribute it and/or
550 modify it under the same terms as Perl itself.
551
552 =head1 SEE ALSO
553
554 See F<ppport.h> and F<devel/regenerate>.
555
556 =cut