| 1 | =head1 NAME |
| 2 | |
| 3 | Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl |
| 4 | |
| 5 | =head1 SYNOPSIS |
| 6 | |
| 7 | There is no simple synopsis, yet. |
| 8 | |
| 9 | =head1 DESCRIPTION |
| 10 | |
| 11 | This document attempts to begin to describe some of the considerations |
| 12 | involved in patching, porting, and maintaining perl. |
| 13 | |
| 14 | This document is still under construction, and still subject to |
| 15 | significant changes. Still, I hope parts of it will be useful, |
| 16 | so I'm releasing it even though it's not done. |
| 17 | |
| 18 | For the most part, it's a collection of anecdotal information that |
| 19 | already assumes some familiarity with the Perl sources. I really need |
| 20 | an introductory section that describes the organization of the sources |
| 21 | and all the various auxiliary files that are part of the distribution. |
| 22 | |
| 23 | =head1 Where Do I Get Perl Sources and Related Material? |
| 24 | |
| 25 | The Comprehensive Perl Archive Network (or CPAN) is the place to go. |
| 26 | There are many mirrors, but the easiest thing to use is probably |
| 27 | http://www.cpan.org/README.html , which automatically points you to a |
| 28 | mirror site "close" to you. |
| 29 | |
| 30 | =head2 Perl5-porters mailing list |
| 31 | |
| 32 | The mailing list perl5-porters@perl.org |
| 33 | is the main group working with the development of perl. If you're |
| 34 | interested in all the latest developments, you should definitely |
| 35 | subscribe. The list is high volume, but generally has a |
| 36 | fairly low noise level. |
| 37 | |
| 38 | Subscribe by sending the message (in the body of your letter) |
| 39 | |
| 40 | subscribe perl5-porters |
| 41 | |
| 42 | to perl5-porters-request@perl.org . |
| 43 | |
| 44 | Archives of the list are held at: |
| 45 | |
| 46 | http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ |
| 47 | |
| 48 | =head1 How are Perl Releases Numbered? |
| 49 | |
| 50 | Beginning with v5.6.0, even versions will stand for maintenance releases |
| 51 | and odd versions for development releases, i.e., v5.6.x for maintenance |
| 52 | releases, and v5.7.x for development releases. Before v5.6.0, subversions |
| 53 | _01 through _49 were reserved for bug-fix maintenance releases, and |
| 54 | subversions _50 through _99 for unstable development versions. |
| 55 | |
| 56 | For example, in v5.6.1, the revision number is 5, the version is 6, |
| 57 | and 1 is the subversion. |
| 58 | |
| 59 | For compatibility with the older numbering scheme the composite floating |
| 60 | point version number continues to be available as the magic variable $], |
| 61 | and amounts to C<$revision + $version/1000 + $subversion/100000>. This |
| 62 | can still be used in comparisons. |
| 63 | |
| 64 | print "You've got an old perl\n" if $] < 5.005_03; |
| 65 | |
| 66 | In addition, the version is also available as a string in $^V. |
| 67 | |
| 68 | print "You've got a new perl\n" if $^V and $^V ge v5.6.0; |
| 69 | |
| 70 | You can also require particular version (or later) with: |
| 71 | |
| 72 | use 5.006; |
| 73 | |
| 74 | or using the new syntax available only from v5.6 onward: |
| 75 | |
| 76 | use v5.6.0; |
| 77 | |
| 78 | At some point in the future, we may need to decide what to call the |
| 79 | next big revision. In the .package file used by metaconfig to |
| 80 | generate Configure, there are two variables that might be relevant: |
| 81 | $baserev=5 and $package=perl5. |
| 82 | |
| 83 | Perl releases produced by the members of perl5-porters are usually |
| 84 | available on CPAN in the F<src/5.0/maint> and F<src/5.0/devel> |
| 85 | directories. |
| 86 | |
| 87 | =head2 Maintenance and Development Subversions |
| 88 | |
| 89 | The first rule of maintenance work is "First, do no harm." |
| 90 | |
| 91 | Trial releases of bug-fix maintenance releases are announced on |
| 92 | perl5-porters. Trial releases use the new subversion number (to avoid |
| 93 | testers installing it over the previous release) and include a 'local |
| 94 | patch' entry in patchlevel.h. The distribution file contains the |
| 95 | string C<MAINT_TRIAL> to make clear that the file is not meant for |
| 96 | public consumption. |
| 97 | |
| 98 | In general, the names of official distribution files for the public |
| 99 | always match the regular expression: |
| 100 | |
| 101 | ^perl\d+\.(\d+)\.\d+(-MAINT_TRIAL_\d+)\.tar\.gz$ |
| 102 | |
| 103 | C<$1> in the pattern is always an even number for maintenance |
| 104 | versions, and odd for developer releases. |
| 105 | |
| 106 | In the past it has been observed that pumpkings tend to invent new |
| 107 | naming conventions on the fly. If you are a pumpking, before you |
| 108 | invent a new name for any of the three types of perl distributions, |
| 109 | please inform the guys from the CPAN who are doing indexing and |
| 110 | provide the trees of symlinks and the like. They will have to know |
| 111 | I<in advance> what you decide. |
| 112 | |
| 113 | =head2 Why is it called the patch pumpkin? |
| 114 | |
| 115 | Chip Salzenberg gets credit for that, with a nod to his cow orker, |
| 116 | David Croy. We had passed around various names (baton, token, hot |
| 117 | potato) but none caught on. Then, Chip asked: |
| 118 | |
| 119 | [begin quote] |
| 120 | |
| 121 | Who has the patch pumpkin? |
| 122 | |
| 123 | To explain: David Croy once told me once that at a previous job, |
| 124 | there was one tape drive and multiple systems that used it for backups. |
| 125 | But instead of some high-tech exclusion software, they used a low-tech |
| 126 | method to prevent multiple simultaneous backups: a stuffed pumpkin. |
| 127 | No one was allowed to make backups unless they had the "backup pumpkin". |
| 128 | |
| 129 | [end quote] |
| 130 | |
| 131 | The name has stuck. |
| 132 | |
| 133 | =head1 Philosophical Issues in Patching and Porting Perl |
| 134 | |
| 135 | There are no absolute rules, but there are some general guidelines I |
| 136 | have tried to follow as I apply patches to the perl sources. |
| 137 | (This section is still under construction.) |
| 138 | |
| 139 | =head2 Solve problems as generally as possible |
| 140 | |
| 141 | Never implement a specific restricted solution to a problem when you |
| 142 | can solve the same problem in a more general, flexible way. |
| 143 | |
| 144 | For example, for dynamic loading to work on some SVR4 systems, we had |
| 145 | to build a shared libperl.so library. In order to build "FAT" binaries |
| 146 | on NeXT 4.0 systems, we had to build a special libperl library. Rather |
| 147 | than continuing to build a contorted nest of special cases, I |
| 148 | generalized the process of building libperl so that NeXT and SVR4 users |
| 149 | could still get their work done, but others could build a shared |
| 150 | libperl if they wanted to as well. |
| 151 | |
| 152 | Contain your changes carefully. Assume nothing about other operating |
| 153 | systems, not even closely related ones. Your changes must not affect |
| 154 | other platforms. |
| 155 | |
| 156 | Spy shamelessly on how similar patching or porting issues have been |
| 157 | settled elsewhere. |
| 158 | |
| 159 | If feasible, try to keep filenames 8.3-compliant to humor those poor |
| 160 | souls that get joy from running Perl under such dire limitations. |
| 161 | There's a script, check83.pl, for keeping your nose 8.3-clean. |
| 162 | In a similar vein, do not create files or directories which differ only |
| 163 | in case (upper versus lower). |
| 164 | |
| 165 | =head2 Seek consensus on major changes |
| 166 | |
| 167 | If you are making big changes, don't do it in secret. Discuss the |
| 168 | ideas in advance on perl5-porters. |
| 169 | |
| 170 | =head2 Keep the documentation up-to-date |
| 171 | |
| 172 | If your changes may affect how users use perl, then check to be sure |
| 173 | that the documentation is in sync with your changes. Be sure to |
| 174 | check all the files F<pod/*.pod> and also the F<INSTALL> document. |
| 175 | |
| 176 | Consider writing the appropriate documentation first and then |
| 177 | implementing your change to correspond to the documentation. |
| 178 | |
| 179 | =head2 Avoid machine-specific #ifdef's |
| 180 | |
| 181 | To the extent reasonable, try to avoid machine-specific #ifdef's in |
| 182 | the sources. Instead, use feature-specific #ifdef's. The reason is |
| 183 | that the machine-specific #ifdef's may not be valid across major |
| 184 | releases of the operating system. Further, the feature-specific tests |
| 185 | may help out folks on another platform who have the same problem. |
| 186 | |
| 187 | =head2 Machine-specific files |
| 188 | |
| 189 | =over 4 |
| 190 | |
| 191 | =item source code |
| 192 | |
| 193 | If you have many machine-specific #defines or #includes, consider |
| 194 | creating an "osish.h" (os2ish.h, vmsish.h, and so on) and including |
| 195 | that in perl.h. If you have several machine-specific files (function |
| 196 | emulations, function stubs, build utility wrappers) you may create a |
| 197 | separate subdirectory (djgpp, win32) and put the files in there. |
| 198 | Remember to update C<MANIFEST> when you add files. |
| 199 | |
| 200 | If your system supports dynamic loading but none of the existing |
| 201 | methods at F<ext/DynaLoader/dl_*.xs> work for you, you must write |
| 202 | a new one. Study the existing ones to see what kind of interface |
| 203 | you must supply. |
| 204 | |
| 205 | =item build hints |
| 206 | |
| 207 | There are two kinds of hints: hints for building Perl and hints for |
| 208 | extensions. The former live in the C<hints> subdirectory, the latter |
| 209 | in C<ext/*/hints> subdirectories. |
| 210 | |
| 211 | The top level hints are Bourne-shell scripts that set, modify and |
| 212 | unset appropriate Configure variables, based on the Configure command |
| 213 | line options and possibly existing config.sh and Policy.sh files from |
| 214 | previous Configure runs. |
| 215 | |
| 216 | The extension hints are written in Perl (by the time they are used |
| 217 | miniperl has been built) and control the building of their respective |
| 218 | extensions. They can be used to for example manipulate compilation |
| 219 | and linking flags. |
| 220 | |
| 221 | =item build and installation Makefiles, scripts, and so forth |
| 222 | |
| 223 | Sometimes you will also need to tweak the Perl build and installation |
| 224 | procedure itself, like for example F<Makefile.SH> and F<installperl>. |
| 225 | Tread very carefully, even more than usual. Contain your changes |
| 226 | with utmost care. |
| 227 | |
| 228 | =item test suite |
| 229 | |
| 230 | Many of the tests in C<t> subdirectory assume machine-specific things |
| 231 | like existence of certain functions, something about filesystem |
| 232 | semantics, certain external utilities and their error messages. Use |
| 233 | the C<$^O> and the C<Config> module (which contains the results of the |
| 234 | Configure run, in effect the C<config.sh> converted to Perl) to either |
| 235 | skip (preferably not) or customize (preferable) the tests for your |
| 236 | platform. |
| 237 | |
| 238 | =item modules |
| 239 | |
| 240 | Certain standard modules may need updating if your operating system |
| 241 | sports for example a native filesystem naming. You may want to update |
| 242 | some or all of the modules File::Basename, File::Spec, File::Path, and |
| 243 | File::Copy to become aware of your native filesystem syntax and |
| 244 | peculiarities. |
| 245 | |
| 246 | Remember to have a $VERSION in the modules. You can use the |
| 247 | Porting/checkVERSION.pl script for checking this. |
| 248 | |
| 249 | =item documentation |
| 250 | |
| 251 | If your operating system comes from outside UNIX you almost certainly |
| 252 | will have differences in the available operating system functionality |
| 253 | (missing system calls, different semantics, whatever). Please |
| 254 | document these at F<pod/perlport.pod>. If your operating system is |
| 255 | the first B<not> to have a system call also update the list of |
| 256 | "portability-bewares" at the beginning of F<pod/perlfunc.pod>. |
| 257 | |
| 258 | A file called F<README.youros> at the top level that explains things |
| 259 | like how to install perl at this platform, where to get any possibly |
| 260 | required additional software, and for example what test suite errors |
| 261 | to expect, is nice too. Such files are in the process of being written |
| 262 | in pod format and will eventually be renamed F<INSTALL.youros>. |
| 263 | |
| 264 | You may also want to write a separate F<.pod> file for your operating |
| 265 | system to tell about existing mailing lists, os-specific modules, |
| 266 | documentation, whatever. Please name these along the lines of |
| 267 | F<perl>I<youros>.pod. [unfinished: where to put this file (the pod/ |
| 268 | subdirectory, of course: but more importantly, which/what index files |
| 269 | should be updated?)] |
| 270 | |
| 271 | =back |
| 272 | |
| 273 | =head2 Allow for lots of testing |
| 274 | |
| 275 | We should never release a main version without testing it as a |
| 276 | subversion first. |
| 277 | |
| 278 | =head2 Test popular applications and modules. |
| 279 | |
| 280 | We should never release a main version without testing whether or not |
| 281 | it breaks various popular modules and applications. A partial list of |
| 282 | such things would include majordomo, metaconfig, apache, Tk, CGI, |
| 283 | libnet, and libwww, to name just a few. Of course it's quite possible |
| 284 | that some of those things will be just plain broken and need to be fixed, |
| 285 | but, in general, we ought to try to avoid breaking widely-installed |
| 286 | things. |
| 287 | |
| 288 | =head2 Automated generation of derivative files |
| 289 | |
| 290 | The F<embed.h>, F<keywords.h>, F<opcode.h>, and F<perltoc.pod> files |
| 291 | are all automatically generated by perl scripts. In general, don't |
| 292 | patch these directly; patch the data files instead. |
| 293 | |
| 294 | F<Configure> and F<config_h.SH> are also automatically generated by |
| 295 | B<metaconfig>. In general, you should patch the metaconfig units |
| 296 | instead of patching these files directly. However, very minor changes |
| 297 | to F<Configure> may be made in between major sync-ups with the |
| 298 | metaconfig units, which tends to be complicated operations. But be |
| 299 | careful, this can quickly spiral out of control. Running metaconfig |
| 300 | is not really hard. |
| 301 | |
| 302 | Also F<Makefile> is automatically produced from F<Makefile.SH>. |
| 303 | In general, look out for all F<*.SH> files. |
| 304 | |
| 305 | Finally, the sample files in the F<Porting/> subdirectory are |
| 306 | generated automatically by the script F<U/mksample> included |
| 307 | with the metaconfig units. See L<"run metaconfig"> below for |
| 308 | information on obtaining the metaconfig units. |
| 309 | |
| 310 | =head1 How to Make a Distribution |
| 311 | |
| 312 | There really ought to be a 'make dist' target, but there isn't. |
| 313 | The 'dist' suite of tools also contains a number of tools that I haven't |
| 314 | learned how to use yet. Some of them may make this all a bit easier. |
| 315 | |
| 316 | Here are the steps I go through to prepare a patch & distribution. |
| 317 | |
| 318 | Lots of it could doubtless be automated but isn't. The Porting/makerel |
| 319 | (make release) perl script does now help automate some parts of it. |
| 320 | |
| 321 | =head2 Announce your intentions |
| 322 | |
| 323 | First, you should volunteer out loud to take the patch pumpkin. It's |
| 324 | generally counter-productive to have multiple people working in secret |
| 325 | on the same thing. |
| 326 | |
| 327 | At the same time, announce what you plan to do with the patch pumpkin, |
| 328 | to allow folks a chance to object or suggest alternatives, or do it for |
| 329 | you. Naturally, the patch pumpkin holder ought to incorporate various |
| 330 | bug fixes and documentation improvements that are posted while he or |
| 331 | she has the pumpkin, but there might also be larger issues at stake. |
| 332 | |
| 333 | One of the precepts of the subversion idea is that we shouldn't give |
| 334 | the patch pumpkin to anyone unless we have some idea what he or she |
| 335 | is going to do with it. |
| 336 | |
| 337 | =head2 refresh pod/perltoc.pod |
| 338 | |
| 339 | Presumably, you have done a full C<make> in your working source |
| 340 | directory. Before you C<make spotless> (if you do), and if you have |
| 341 | changed any documentation in any module or pod file, change to the |
| 342 | F<pod> directory and run C<make toc>. |
| 343 | |
| 344 | =head2 run installhtml to check the validity of the pod files |
| 345 | |
| 346 | =head2 update patchlevel.h |
| 347 | |
| 348 | Don't be shy about using the subversion number, even for a relatively |
| 349 | modest patch. We've never even come close to using all 99 subversions, |
| 350 | and it's better to have a distinctive number for your patch. If you |
| 351 | need feedback on your patch, go ahead and issue it and promise to |
| 352 | incorporate that feedback quickly (e.g. within 1 week) and send out a |
| 353 | second patch. |
| 354 | |
| 355 | If you update the subversion number, you may need to change the version |
| 356 | number near the top of the F<Changes> file. |
| 357 | |
| 358 | =head2 run metaconfig |
| 359 | |
| 360 | If you need to make changes to Configure or config_h.SH, it may be best to |
| 361 | change the appropriate metaconfig units instead, and regenerate Configure. |
| 362 | |
| 363 | metaconfig -m |
| 364 | |
| 365 | will regenerate Configure and config_h.SH. Much more information |
| 366 | on obtaining and running metaconfig is in the F<U/README> file |
| 367 | that comes with Perl's metaconfig units. Perl's metaconfig units |
| 368 | should be available on CPAN. A set of units that will work with |
| 369 | perl5.005 is in the file F<mc_units-5.005_00-01.tar.gz> under |
| 370 | http://www.cpan.org/authors/id/ANDYD/ . The mc_units tar file |
| 371 | should be unpacked in your main perl source directory. Note: those |
| 372 | units were for use with 5.005. There may have been changes since then. |
| 373 | Check for later versions or contact perl5-porters@perl.org to obtain a |
| 374 | pointer to the current version. |
| 375 | |
| 376 | Alternatively, do consider if the F<*ish.h> files might be a better |
| 377 | place for your changes. |
| 378 | |
| 379 | =head2 MANIFEST |
| 380 | |
| 381 | Make sure the MANIFEST is up-to-date. You can use dist's B<manicheck> |
| 382 | program for this. You can also use |
| 383 | |
| 384 | perl -w -MExtUtils::Manifest=fullcheck -e fullcheck |
| 385 | |
| 386 | Both commands will also list extra files in the directory that are not |
| 387 | listed in MANIFEST. |
| 388 | |
| 389 | The MANIFEST is normally sorted. |
| 390 | |
| 391 | If you are using metaconfig to regenerate Configure, then you should note |
| 392 | that metaconfig actually uses MANIFEST.new, so you want to be sure |
| 393 | MANIFEST.new is up-to-date too. I haven't found the MANIFEST/MANIFEST.new |
| 394 | distinction particularly useful, but that's probably because I still haven't |
| 395 | learned how to use the full suite of tools in the dist distribution. |
| 396 | |
| 397 | =head2 Check permissions |
| 398 | |
| 399 | All the tests in the t/ directory ought to be executable. The |
| 400 | main makefile used to do a 'chmod t/*/*.t', but that resulted in |
| 401 | a self-modifying distribution--something some users would strongly |
| 402 | prefer to avoid. The F<t/TEST> script will check for this |
| 403 | and do the chmod if needed, but the tests still ought to be |
| 404 | executable. |
| 405 | |
| 406 | In all, the following files should probably be executable: |
| 407 | |
| 408 | Configure |
| 409 | configpm |
| 410 | configure.gnu |
| 411 | embed.pl |
| 412 | installperl |
| 413 | installman |
| 414 | keywords.pl |
| 415 | myconfig |
| 416 | opcode.pl |
| 417 | t/TEST |
| 418 | t/*/*.t |
| 419 | *.SH |
| 420 | vms/ext/Stdio/test.pl |
| 421 | vms/ext/filespec.t |
| 422 | x2p/*.SH |
| 423 | |
| 424 | Other things ought to be readable, at least :-). |
| 425 | |
| 426 | Probably, the permissions for the files could be encoded in MANIFEST |
| 427 | somehow, but I'm reluctant to change MANIFEST itself because that |
| 428 | could break old scripts that use MANIFEST. |
| 429 | |
| 430 | I seem to recall that some SVR3 systems kept some sort of file that listed |
| 431 | permissions for system files; something like that might be appropriate. |
| 432 | |
| 433 | =head2 Run Configure |
| 434 | |
| 435 | This will build a config.sh and config.h. You can skip this if you haven't |
| 436 | changed Configure or config_h.SH at all. I use the following command |
| 437 | |
| 438 | sh Configure -Dprefix=/opt/perl -Doptimize=-O -Dusethreads \ |
| 439 | -Dcf_by='yourname' \ |
| 440 | -Dcf_email='yourname@yourhost.yourplace.com' \ |
| 441 | -Dperladmin='yourname@yourhost.yourplace.com' \ |
| 442 | -Dmydomain='.yourplace.com' \ |
| 443 | -Dmyhostname='yourhost' \ |
| 444 | -des |
| 445 | |
| 446 | =head2 Update Porting/config.sh and Porting/config_H |
| 447 | |
| 448 | [XXX |
| 449 | This section needs revision. We're currently working on easing |
| 450 | the task of keeping the vms, win32, and plan9 config.sh info |
| 451 | up-to-date. The plan is to use keep up-to-date 'canned' config.sh |
| 452 | files in the appropriate subdirectories and then generate 'canned' |
| 453 | config.h files for vms, win32, etc. from the generic config.sh file. |
| 454 | This is to ease maintenance. When Configure gets updated, the parts |
| 455 | sometimes get scrambled around, and the changes in config_H can |
| 456 | sometimes be very hard to follow. config.sh, on the other hand, can |
| 457 | safely be sorted, so it's easy to track (typically very small) changes |
| 458 | to config.sh and then propagate them to a canned 'config.h' by any |
| 459 | number of means, including a perl script in win32/ or carrying |
| 460 | config.sh and config_h.SH to a Unix system and running sh |
| 461 | config_h.SH.) Vms uses configure.com to generate its own config.sh |
| 462 | and config.h. If you want to add a new variable to config.sh check |
| 463 | with vms folk how to add it to configure.com too. |
| 464 | XXX] |
| 465 | |
| 466 | The Porting/config.sh and Porting/config_H files are provided to |
| 467 | help those folks who can't run Configure. It is important to keep |
| 468 | them up-to-date. If you have changed config_h.SH, those changes must |
| 469 | be reflected in config_H as well. (The name config_H was chosen to |
| 470 | distinguish the file from config.h even on case-insensitive file systems.) |
| 471 | Simply edit the existing config_H file; keep the first few explanatory |
| 472 | lines and then copy your new config.h below. |
| 473 | |
| 474 | It may also be necessary to update win32/config.?c, and |
| 475 | plan9/config.plan9, though you should be quite careful in doing so if |
| 476 | you are not familiar with those systems. You might want to issue your |
| 477 | patch with a promise to quickly issue a follow-up that handles those |
| 478 | directories. |
| 479 | |
| 480 | =head2 make regen_perly |
| 481 | |
| 482 | If perly.y has been edited, it is necessary to run this target to rebuild |
| 483 | perly.h, perly.act and perly.tab. In fact this target just runs the Perl |
| 484 | script regen_perly.pl. Note that perly.c is I<not> rebuilt; this is just a |
| 485 | plain static file now. |
| 486 | |
| 487 | This target relies on you having Bison installed on your system. Running |
| 488 | the target will tell you if you haven't got the right version, and if so, |
| 489 | where to get the right one. Or if you prefer, you could hack |
| 490 | regen_perly.pl to work with your version of Bison. The important things |
| 491 | are that the regexes can still extract out the right chunks of the Bison |
| 492 | output into perly.act and perly.tab, and that the contents of those two |
| 493 | files, plus perly.h, are functionally equivalent to those produced by the |
| 494 | supported version of Bison. |
| 495 | |
| 496 | Note that in the old days, you had to do C<make run_byacc> instead. |
| 497 | |
| 498 | =head2 make regen_all |
| 499 | |
| 500 | This target takes care of the regen_headers, and regen_pods targets. |
| 501 | |
| 502 | =head2 make regen_headers |
| 503 | |
| 504 | The F<embed.h>, F<keywords.h>, and F<opcode.h> files are all automatically |
| 505 | generated by perl scripts. Since the user isn't guaranteed to have a |
| 506 | working perl, we can't require the user to generate them. Hence you have |
| 507 | to, if you're making a distribution. |
| 508 | |
| 509 | I used to include rules like the following in the makefile: |
| 510 | |
| 511 | # The following three header files are generated automatically |
| 512 | # The correct versions should be already supplied with the perl kit, |
| 513 | # in case you don't have perl or 'sh' available. |
| 514 | # The - is to ignore error return codes in case you have the source |
| 515 | # installed read-only or you don't have perl yet. |
| 516 | keywords.h: keywords.pl |
| 517 | @echo "Don't worry if this fails." |
| 518 | - perl keywords.pl |
| 519 | |
| 520 | |
| 521 | However, I got B<lots> of mail consisting of people worrying because the |
| 522 | command failed. I eventually decided that I would save myself time |
| 523 | and effort by manually running C<make regen_headers> myself rather |
| 524 | than answering all the questions and complaints about the failing |
| 525 | command. |
| 526 | |
| 527 | =head2 make regen_pods |
| 528 | |
| 529 | Will run `make regen_pods` in the pod directory for indexing. |
| 530 | |
| 531 | =head2 global.sym, interp.sym and perlio.sym |
| 532 | |
| 533 | Make sure these files are up-to-date. Read the comments in these |
| 534 | files and in perl_exp.SH to see what to do. |
| 535 | |
| 536 | =head2 Binary compatibility |
| 537 | |
| 538 | If you do change F<global.sym> or F<interp.sym>, think carefully about |
| 539 | what you are doing. To the extent reasonable, we'd like to maintain |
| 540 | source and binary compatibility with older releases of perl. That way, |
| 541 | extensions built under one version of perl will continue to work with |
| 542 | new versions of perl. |
| 543 | |
| 544 | Of course, some incompatible changes may well be necessary. I'm just |
| 545 | suggesting that we not make any such changes without thinking carefully |
| 546 | about them first. If possible, we should provide |
| 547 | backwards-compatibility stubs. There's a lot of XS code out there. |
| 548 | Let's not force people to keep changing it. |
| 549 | |
| 550 | =head2 PPPort |
| 551 | |
| 552 | F<ext/Devel/PPPort/PPPort.pm> needs to be synchronized to include all |
| 553 | new macros added to .h files (normally perl.h and XSUB.h, but others |
| 554 | as well). Since chances are that when a new macro is added the |
| 555 | committer will forget to update F<PPPort.pm>, it's the best to diff for |
| 556 | changes in .h files when making a new release and making sure that |
| 557 | F<PPPort.pm> contains them all. |
| 558 | |
| 559 | The pumpking can delegate the synchronization responsibility to anybody |
| 560 | else, but the release process is the only place where we can make sure |
| 561 | that no new macros fell through the cracks. |
| 562 | |
| 563 | =head2 Changes |
| 564 | |
| 565 | Be sure to update the F<Changes> file. Try to include both an overall |
| 566 | summary as well as detailed descriptions of the changes. Your |
| 567 | audience will include other developers and users, so describe |
| 568 | user-visible changes (if any) in terms they will understand, not in |
| 569 | code like "initialize foo variable in bar function". |
| 570 | |
| 571 | There are differing opinions on whether the detailed descriptions |
| 572 | ought to go in the Changes file or whether they ought to be available |
| 573 | separately in the patch file (or both). There is no disagreement that |
| 574 | detailed descriptions ought to be easily available somewhere. |
| 575 | |
| 576 | If you update the subversion number in F<patchlevel.h>, you may need |
| 577 | to change the version number near the top of the F<Changes> file. |
| 578 | |
| 579 | =head2 Todo |
| 580 | |
| 581 | The F<pod/perltodo.pod> file contains a roughly-categorized unordered |
| 582 | list of aspects of Perl that could use enhancement, features that could |
| 583 | be added, areas that could be cleaned up, and so on. During your term |
| 584 | as pumpkin-holder, you will probably address some of these issues, and |
| 585 | perhaps identify others which, while you decide not to address them this |
| 586 | time around, may be tackled in the future. Update the file to reflect |
| 587 | the situation as it stands when you hand over the pumpkin. |
| 588 | |
| 589 | You might like, early in your pumpkin-holding career, to see if you |
| 590 | can find champions for particular issues on the to-do list: an issue |
| 591 | owned is an issue more likely to be resolved. |
| 592 | |
| 593 | There are also some more porting-specific L</Todo> items later in this |
| 594 | file. |
| 595 | |
| 596 | =head2 OS/2-specific updates |
| 597 | |
| 598 | In the os2 directory is F<diff.configure>, a set of OS/2-specific |
| 599 | diffs against B<Configure>. If you make changes to Configure, you may |
| 600 | want to consider regenerating this diff file to save trouble for the |
| 601 | OS/2 maintainer. |
| 602 | |
| 603 | You can also consider the OS/2 diffs as reminders of portability |
| 604 | things that need to be fixed in Configure. |
| 605 | |
| 606 | =head2 VMS-specific updates |
| 607 | |
| 608 | The Perl revision number appears as "perl5" in configure.com. |
| 609 | It is courteous to update that if necessary. |
| 610 | |
| 611 | =head2 Making the new distribution |
| 612 | |
| 613 | Suppose, for example, that you want to make version 5.004_08. Then you can |
| 614 | do something like the following |
| 615 | |
| 616 | mkdir ../perl5.004_08 |
| 617 | awk '{print $1}' MANIFEST | cpio -pdm ../perl5.004_08 |
| 618 | cd ../ |
| 619 | tar cf perl5.004_08.tar perl5.004_08 |
| 620 | gzip --best perl5.004_08.tar |
| 621 | |
| 622 | These steps, with extra checks, are automated by the Porting/makerel |
| 623 | script. |
| 624 | |
| 625 | =head2 Making a new patch |
| 626 | |
| 627 | I find the F<makepatch> utility quite handy for making patches. |
| 628 | You can obtain it from any CPAN archive under |
| 629 | http://www.cpan.org/authors/Johan_Vromans/ . There are a couple |
| 630 | of differences between my version and the standard one. I have mine do |
| 631 | a |
| 632 | |
| 633 | # Print a reassuring "End of Patch" note so people won't |
| 634 | # wonder if their mailer truncated patches. |
| 635 | print "\n\nEnd of Patch.\n"; |
| 636 | |
| 637 | at the end. That's because I used to get questions from people asking |
| 638 | if their mail was truncated. |
| 639 | |
| 640 | It also writes Index: lines which include the new directory prefix |
| 641 | (change Index: print, approx line 294 or 310 depending on the version, |
| 642 | to read: print PATCH ("Index: $newdir$new\n");). That helps patches |
| 643 | work with more POSIX conformant patch programs. |
| 644 | |
| 645 | Here's how I generate a new patch. I'll use the hypothetical |
| 646 | 5.004_07 to 5.004_08 patch as an example. |
| 647 | |
| 648 | # unpack perl5.004_07/ |
| 649 | gzip -d -c perl5.004_07.tar.gz | tar -xof - |
| 650 | # unpack perl5.004_08/ |
| 651 | gzip -d -c perl5.004_08.tar.gz | tar -xof - |
| 652 | makepatch perl5.004_07 perl5.004_08 > perl5.004_08.pat |
| 653 | |
| 654 | Makepatch will automatically generate appropriate B<rm> commands to remove |
| 655 | deleted files. Unfortunately, it will not correctly set permissions |
| 656 | for newly created files, so you may have to do so manually. For example, |
| 657 | patch 5.003_04 created a new test F<t/op/gv.t> which needs to be executable, |
| 658 | so at the top of the patch, I inserted the following lines: |
| 659 | |
| 660 | # Make a new test |
| 661 | touch t/op/gv.t |
| 662 | chmod +x t/opt/gv.t |
| 663 | |
| 664 | Now, of course, my patch is now wrong because makepatch didn't know I |
| 665 | was going to do that command, and it patched against /dev/null. |
| 666 | |
| 667 | So, what I do is sort out all such shell commands that need to be in the |
| 668 | patch (including possible mv-ing of files, if needed) and put that in the |
| 669 | shell commands at the top of the patch. Next, I delete all the patch parts |
| 670 | of perl5.004_08.pat, leaving just the shell commands. Then, I do the |
| 671 | following: |
| 672 | |
| 673 | cd perl5.004_07 |
| 674 | sh ../perl5.004_08.pat |
| 675 | cd .. |
| 676 | makepatch perl5.004_07 perl5.004_08 >> perl5.004_08.pat |
| 677 | |
| 678 | (Note the append to preserve my shell commands.) |
| 679 | Now, my patch will line up with what the end users are going to do. |
| 680 | |
| 681 | =head2 Testing your patch |
| 682 | |
| 683 | It seems obvious, but be sure to test your patch. That is, verify that |
| 684 | it produces exactly the same thing as your full distribution. |
| 685 | |
| 686 | rm -rf perl5.004_07 |
| 687 | gzip -d -c perl5.004_07.tar.gz | tar -xf - |
| 688 | cd perl5.004_07 |
| 689 | sh ../perl5.004_08.pat |
| 690 | patch -p1 -N < ../perl5.004_08.pat |
| 691 | cd .. |
| 692 | gdiff -r perl5.004_07 perl5.004_08 |
| 693 | |
| 694 | where B<gdiff> is GNU diff. Other diff's may also do recursive checking. |
| 695 | |
| 696 | =head2 More testing |
| 697 | |
| 698 | Again, it's obvious, but you should test your new version as widely as you |
| 699 | can. You can be sure you'll hear about it quickly if your version doesn't |
| 700 | work on both ANSI and pre-ANSI compilers, and on common systems such as |
| 701 | SunOS 4.1.[34], Solaris, and Linux. |
| 702 | |
| 703 | If your changes include conditional code, try to test the different |
| 704 | branches as thoroughly as you can. For example, if your system |
| 705 | supports dynamic loading, you can also test static loading with |
| 706 | |
| 707 | sh Configure -Uusedl |
| 708 | |
| 709 | You can also hand-tweak your config.h to try out different #ifdef |
| 710 | branches. |
| 711 | |
| 712 | =head2 Other tests |
| 713 | |
| 714 | =over 4 |
| 715 | |
| 716 | =item gcc -ansi -pedantic |
| 717 | |
| 718 | Configure -Dgccansipedantic [ -Dcc=gcc ] will enable (via the cflags script, |
| 719 | not $Config{ccflags}) the gcc strict ANSI C flags -ansi and -pedantic for |
| 720 | the compilation of the core files on platforms where it knows it can |
| 721 | do so (like Linux, see cflags.SH for the full list), and on some |
| 722 | platforms only one (Solaris can do only -pedantic, not -ansi). |
| 723 | The flag -DPERL_GCC_PEDANTIC also gets added, since gcc does not add |
| 724 | any internal cpp flag to signify that -pedantic is being used, as it |
| 725 | does for -ansi (__STRICT_ANSI__). |
| 726 | |
| 727 | Note that the -ansi and -pedantic are enabled only for version 3 (and |
| 728 | later) of gcc, since even gcc version 2.95.4 finds lots of seemingly |
| 729 | false "value computed not used" errors from Perl. |
| 730 | |
| 731 | The -ansi and -pedantic are useful in catching at least the following |
| 732 | nonportable practices: |
| 733 | |
| 734 | =over 4 |
| 735 | |
| 736 | =item * |
| 737 | |
| 738 | gcc-specific extensions |
| 739 | |
| 740 | =item * |
| 741 | |
| 742 | lvalue casts |
| 743 | |
| 744 | =item * |
| 745 | |
| 746 | // C++ comments |
| 747 | |
| 748 | =item * |
| 749 | |
| 750 | enum trailing commas |
| 751 | |
| 752 | =back |
| 753 | |
| 754 | The -Dgccansipedantic should be used only when cleaning up the code, |
| 755 | not for production builds, since otherwise gcc cannot inline certain |
| 756 | things. |
| 757 | |
| 758 | =back |
| 759 | |
| 760 | =head1 Running Purify |
| 761 | |
| 762 | Purify is a commercial tool that is helpful in identifying memory |
| 763 | overruns, wild pointers, memory leaks and other such badness. Perl |
| 764 | must be compiled in a specific way for optimal testing with Purify. |
| 765 | |
| 766 | Use the following commands to test perl with Purify: |
| 767 | |
| 768 | sh Configure -des -Doptimize=-g -Uusemymalloc -Dusemultiplicity \ |
| 769 | -Accflags=-DPURIFY |
| 770 | setenv PURIFYOPTIONS "-chain-length=25" |
| 771 | make all pureperl |
| 772 | cd t |
| 773 | ln -s ../pureperl perl |
| 774 | setenv PERL_DESTRUCT_LEVEL 2 |
| 775 | ./perl TEST |
| 776 | |
| 777 | Disabling Perl's malloc allows Purify to monitor allocations and leaks |
| 778 | more closely; using Perl's malloc will make Purify report most leaks |
| 779 | in the "potential" leaks category. Enabling the multiplicity option |
| 780 | allows perl to clean up thoroughly when the interpreter shuts down, which |
| 781 | reduces the number of bogus leak reports from Purify. The -DPURIFY |
| 782 | enables any Purify-specific debugging code in the sources. |
| 783 | |
| 784 | Purify outputs messages in "Viewer" windows by default. If you don't have |
| 785 | a windowing environment or if you simply want the Purify output to |
| 786 | unobtrusively go to a log file instead of to the interactive window, |
| 787 | use the following options instead: |
| 788 | |
| 789 | setenv PURIFYOPTIONS "-chain-length=25 -windows=no -log-file=perl.log \ |
| 790 | -append-logfile=yes" |
| 791 | |
| 792 | The only currently known leaks happen when there are compile-time errors |
| 793 | within eval or require. (Fixing these is non-trivial, unfortunately, but |
| 794 | they must be fixed eventually.) |
| 795 | |
| 796 | =head1 Common Gotchas |
| 797 | |
| 798 | =over 4 |
| 799 | |
| 800 | =item #elif |
| 801 | |
| 802 | The '#elif' preprocessor directive is not understood on all systems. |
| 803 | Specifically, I know that Pyramids don't understand it. Thus instead of the |
| 804 | simple |
| 805 | |
| 806 | #if defined(I_FOO) |
| 807 | # include <foo.h> |
| 808 | #elif defined(I_BAR) |
| 809 | # include <bar.h> |
| 810 | #else |
| 811 | # include <fubar.h> |
| 812 | #endif |
| 813 | |
| 814 | You have to do the more Byzantine |
| 815 | |
| 816 | #if defined(I_FOO) |
| 817 | # include <foo.h> |
| 818 | #else |
| 819 | # if defined(I_BAR) |
| 820 | # include <bar.h> |
| 821 | # else |
| 822 | # include <fubar.h> |
| 823 | # endif |
| 824 | #endif |
| 825 | |
| 826 | Incidentally, whitespace between the leading '#' and the preprocessor |
| 827 | command is not guaranteed, but is very portable and you may use it freely. |
| 828 | I think it makes things a bit more readable, especially once things get |
| 829 | rather deeply nested. I also think that things should almost never get |
| 830 | too deeply nested, so it ought to be a moot point :-) |
| 831 | |
| 832 | =item Probably Prefer POSIX |
| 833 | |
| 834 | It's often the case that you'll need to choose whether to do |
| 835 | something the BSD-ish way or the POSIX-ish way. It's usually not |
| 836 | a big problem when the two systems use different names for similar |
| 837 | functions, such as memcmp() and bcmp(). The perl.h header file |
| 838 | handles these by appropriate #defines, selecting the POSIX mem*() |
| 839 | functions if available, but falling back on the b*() functions, if |
| 840 | need be. |
| 841 | |
| 842 | More serious is the case where some brilliant person decided to |
| 843 | use the same function name but give it a different meaning or |
| 844 | calling sequence :-). getpgrp() and setpgrp() come to mind. |
| 845 | These are a real problem on systems that aim for conformance to |
| 846 | one standard (e.g. POSIX), but still try to support the other way |
| 847 | of doing things (e.g. BSD). My general advice (still not really |
| 848 | implemented in the source) is to do something like the following. |
| 849 | Suppose there are two alternative versions, fooPOSIX() and |
| 850 | fooBSD(). |
| 851 | |
| 852 | #ifdef HAS_FOOPOSIX |
| 853 | /* use fooPOSIX(); */ |
| 854 | #else |
| 855 | # ifdef HAS_FOOBSD |
| 856 | /* try to emulate fooPOSIX() with fooBSD(); |
| 857 | perhaps with the following: */ |
| 858 | # define fooPOSIX fooBSD |
| 859 | # else |
| 860 | # /* Uh, oh. We have to supply our own. */ |
| 861 | # define fooPOSIX Perl_fooPOSIX |
| 862 | # endif |
| 863 | #endif |
| 864 | |
| 865 | =item Think positively |
| 866 | |
| 867 | If you need to add an #ifdef test, it is usually easier to follow if you |
| 868 | think positively, e.g. |
| 869 | |
| 870 | #ifdef HAS_NEATO_FEATURE |
| 871 | /* use neato feature */ |
| 872 | #else |
| 873 | /* use some fallback mechanism */ |
| 874 | #endif |
| 875 | |
| 876 | rather than the more impenetrable |
| 877 | |
| 878 | #ifndef MISSING_NEATO_FEATURE |
| 879 | /* Not missing it, so we must have it, so use it */ |
| 880 | #else |
| 881 | /* Are missing it, so fall back on something else. */ |
| 882 | #endif |
| 883 | |
| 884 | Of course for this toy example, there's not much difference. But when |
| 885 | the #ifdef's start spanning a couple of screen fulls, and the #else's |
| 886 | are marked something like |
| 887 | |
| 888 | #else /* !MISSING_NEATO_FEATURE */ |
| 889 | |
| 890 | I find it easy to get lost. |
| 891 | |
| 892 | =item Providing Missing Functions -- Problem |
| 893 | |
| 894 | Not all systems have all the neat functions you might want or need, so |
| 895 | you might decide to be helpful and provide an emulation. This is |
| 896 | sound in theory and very kind of you, but please be careful about what |
| 897 | you name the function. Let me use the C<pause()> function as an |
| 898 | illustration. |
| 899 | |
| 900 | Perl5.003 has the following in F<perl.h> |
| 901 | |
| 902 | #ifndef HAS_PAUSE |
| 903 | #define pause() sleep((32767<<16)+32767) |
| 904 | #endif |
| 905 | |
| 906 | Configure sets HAS_PAUSE if the system has the pause() function, so |
| 907 | this #define only kicks in if the pause() function is missing. |
| 908 | Nice idea, right? |
| 909 | |
| 910 | Unfortunately, some systems apparently have a prototype for pause() |
| 911 | in F<unistd.h>, but don't actually have the function in the library. |
| 912 | (Or maybe they do have it in a library we're not using.) |
| 913 | |
| 914 | Thus, the compiler sees something like |
| 915 | |
| 916 | extern int pause(void); |
| 917 | /* . . . */ |
| 918 | #define pause() sleep((32767<<16)+32767) |
| 919 | |
| 920 | and dies with an error message. (Some compilers don't mind this; |
| 921 | others apparently do.) |
| 922 | |
| 923 | To work around this, 5.003_03 and later have the following in perl.h: |
| 924 | |
| 925 | /* Some unistd.h's give a prototype for pause() even though |
| 926 | HAS_PAUSE ends up undefined. This causes the #define |
| 927 | below to be rejected by the compiler. Sigh. |
| 928 | */ |
| 929 | #ifdef HAS_PAUSE |
| 930 | # define Pause pause |
| 931 | #else |
| 932 | # define Pause() sleep((32767<<16)+32767) |
| 933 | #endif |
| 934 | |
| 935 | This works. |
| 936 | |
| 937 | The curious reader may wonder why I didn't do the following in |
| 938 | F<util.c> instead: |
| 939 | |
| 940 | #ifndef HAS_PAUSE |
| 941 | void pause() |
| 942 | { |
| 943 | sleep((32767<<16)+32767); |
| 944 | } |
| 945 | #endif |
| 946 | |
| 947 | That is, since the function is missing, just provide it. |
| 948 | Then things would probably be been alright, it would seem. |
| 949 | |
| 950 | Well, almost. It could be made to work. The problem arises from the |
| 951 | conflicting needs of dynamic loading and namespace protection. |
| 952 | |
| 953 | For dynamic loading to work on AIX (and VMS) we need to provide a list |
| 954 | of symbols to be exported. This is done by the script F<perl_exp.SH>, |
| 955 | which reads F<global.sym> and F<interp.sym>. Thus, the C<pause> |
| 956 | symbol would have to be added to F<global.sym> So far, so good. |
| 957 | |
| 958 | On the other hand, one of the goals of Perl5 is to make it easy to |
| 959 | either extend or embed perl and link it with other libraries. This |
| 960 | means we have to be careful to keep the visible namespace "clean". |
| 961 | That is, we don't want perl's global variables to conflict with |
| 962 | those in the other application library. Although this work is still |
| 963 | in progress, the way it is currently done is via the F<embed.h> file. |
| 964 | This file is built from the F<global.sym> and F<interp.sym> files, |
| 965 | since those files already list the globally visible symbols. If we |
| 966 | had added C<pause> to global.sym, then F<embed.h> would contain the |
| 967 | line |
| 968 | |
| 969 | #define pause Perl_pause |
| 970 | |
| 971 | and calls to C<pause> in the perl sources would now point to |
| 972 | C<Perl_pause>. Now, when B<ld> is run to build the F<perl> executable, |
| 973 | it will go looking for C<perl_pause>, which probably won't exist in any |
| 974 | of the standard libraries. Thus the build of perl will fail. |
| 975 | |
| 976 | Those systems where C<HAS_PAUSE> is not defined would be ok, however, |
| 977 | since they would get a C<Perl_pause> function in util.c. The rest of |
| 978 | the world would be in trouble. |
| 979 | |
| 980 | And yes, this scenario has happened. On SCO, the function C<chsize> |
| 981 | is available. (I think it's in F<-lx>, the Xenix compatibility |
| 982 | library.) Since the perl4 days (and possibly before), Perl has |
| 983 | included a C<chsize> function that gets called something akin to |
| 984 | |
| 985 | #ifndef HAS_CHSIZE |
| 986 | I32 chsize(fd, length) |
| 987 | /* . . . */ |
| 988 | #endif |
| 989 | |
| 990 | When 5.003 added |
| 991 | |
| 992 | #define chsize Perl_chsize |
| 993 | |
| 994 | to F<embed.h>, the compile started failing on SCO systems. |
| 995 | |
| 996 | The "fix" is to give the function a different name. The one |
| 997 | implemented in 5.003_05 isn't optimal, but here's what was done: |
| 998 | |
| 999 | #ifdef HAS_CHSIZE |
| 1000 | # ifdef my_chsize /* Probably #defined to Perl_my_chsize in embed.h */ |
| 1001 | # undef my_chsize |
| 1002 | # endif |
| 1003 | # define my_chsize chsize |
| 1004 | #endif |
| 1005 | |
| 1006 | My explanatory comment in patch 5.003_05 said: |
| 1007 | |
| 1008 | Undef and then re-define my_chsize from Perl_my_chsize to |
| 1009 | just plain chsize if this system HAS_CHSIZE. This probably only |
| 1010 | applies to SCO. This shows the perils of having internal |
| 1011 | functions with the same name as external library functions :-). |
| 1012 | |
| 1013 | Now, we can safely put C<my_chsize> in F<global.sym>, export it, and |
| 1014 | hide it with F<embed.h>. |
| 1015 | |
| 1016 | To be consistent with what I did for C<pause>, I probably should have |
| 1017 | called the new function C<Chsize>, rather than C<my_chsize>. |
| 1018 | However, the perl sources are quite inconsistent on this (Consider |
| 1019 | New, Mymalloc, and Myremalloc, to name just a few.) |
| 1020 | |
| 1021 | There is a problem with this fix, however, in that C<Perl_chsize> |
| 1022 | was available as a F<libperl.a> library function in 5.003, but it |
| 1023 | isn't available any more (as of 5.003_07). This means that we've |
| 1024 | broken binary compatibility. This is not good. |
| 1025 | |
| 1026 | =item Providing missing functions -- some ideas |
| 1027 | |
| 1028 | We currently don't have a standard way of handling such missing |
| 1029 | function names. Right now, I'm effectively thinking aloud about a |
| 1030 | solution. Some day, I'll try to formally propose a solution. |
| 1031 | |
| 1032 | Part of the problem is that we want to have some functions listed as |
| 1033 | exported but not have their names mangled by embed.h or possibly |
| 1034 | conflict with names in standard system headers. We actually already |
| 1035 | have such a list at the end of F<perl_exp.SH> (though that list is |
| 1036 | out-of-date): |
| 1037 | |
| 1038 | # extra globals not included above. |
| 1039 | cat <<END >> perl.exp |
| 1040 | perl_init_ext |
| 1041 | perl_init_fold |
| 1042 | perl_init_i18nl14n |
| 1043 | perl_alloc |
| 1044 | perl_construct |
| 1045 | perl_destruct |
| 1046 | perl_free |
| 1047 | perl_parse |
| 1048 | perl_run |
| 1049 | perl_get_sv |
| 1050 | perl_get_av |
| 1051 | perl_get_hv |
| 1052 | perl_get_cv |
| 1053 | perl_call_argv |
| 1054 | perl_call_pv |
| 1055 | perl_call_method |
| 1056 | perl_call_sv |
| 1057 | perl_requirepv |
| 1058 | safecalloc |
| 1059 | safemalloc |
| 1060 | saferealloc |
| 1061 | safefree |
| 1062 | |
| 1063 | This still needs much thought, but I'm inclined to think that one |
| 1064 | possible solution is to prefix all such functions with C<perl_> in the |
| 1065 | source and list them along with the other C<perl_*> functions in |
| 1066 | F<perl_exp.SH>. |
| 1067 | |
| 1068 | Thus, for C<chsize>, we'd do something like the following: |
| 1069 | |
| 1070 | /* in perl.h */ |
| 1071 | #ifdef HAS_CHSIZE |
| 1072 | # define perl_chsize chsize |
| 1073 | #endif |
| 1074 | |
| 1075 | then in some file (e.g. F<util.c> or F<doio.c>) do |
| 1076 | |
| 1077 | #ifndef HAS_CHSIZE |
| 1078 | I32 perl_chsize(fd, length) |
| 1079 | /* implement the function here . . . */ |
| 1080 | #endif |
| 1081 | |
| 1082 | Alternatively, we could just always use C<chsize> everywhere and move |
| 1083 | C<chsize> from F<global.sym> to the end of F<perl_exp.SH>. That would |
| 1084 | probably be fine as long as our C<chsize> function agreed with all the |
| 1085 | C<chsize> function prototypes in the various systems we'll be using. |
| 1086 | As long as the prototypes in actual use don't vary that much, this is |
| 1087 | probably a good alternative. (As a counter-example, note how Configure |
| 1088 | and perl have to go through hoops to find and use get Malloc_t and |
| 1089 | Free_t for C<malloc> and C<free>.) |
| 1090 | |
| 1091 | At the moment, this latter option is what I tend to prefer. |
| 1092 | |
| 1093 | =item All the world's a VAX |
| 1094 | |
| 1095 | Sorry, showing my age:-). Still, all the world is not BSD 4.[34], |
| 1096 | SVR4, or POSIX. Be aware that SVR3-derived systems are still quite |
| 1097 | common (do you have any idea how many systems run SCO?) If you don't |
| 1098 | have a bunch of v7 manuals handy, the metaconfig units (by default |
| 1099 | installed in F</usr/local/lib/dist/U>) are a good resource to look at |
| 1100 | for portability. |
| 1101 | |
| 1102 | =back |
| 1103 | |
| 1104 | =head1 Miscellaneous Topics |
| 1105 | |
| 1106 | =head2 Autoconf |
| 1107 | |
| 1108 | Why does perl use a metaconfig-generated Configure script instead of an |
| 1109 | autoconf-generated configure script? |
| 1110 | |
| 1111 | Metaconfig and autoconf are two tools with very similar purposes. |
| 1112 | Metaconfig is actually the older of the two, and was originally written |
| 1113 | by Larry Wall, while autoconf is probably now used in a wider variety of |
| 1114 | packages. The autoconf info file discusses the history of autoconf and |
| 1115 | how it came to be. The curious reader is referred there for further |
| 1116 | information. |
| 1117 | |
| 1118 | Overall, both tools are quite good, I think, and the choice of which one |
| 1119 | to use could be argued either way. In March, 1994, when I was just |
| 1120 | starting to work on Configure support for Perl5, I considered both |
| 1121 | autoconf and metaconfig, and eventually decided to use metaconfig for the |
| 1122 | following reasons: |
| 1123 | |
| 1124 | =over 4 |
| 1125 | |
| 1126 | =item Compatibility with Perl4 |
| 1127 | |
| 1128 | Perl4 used metaconfig, so many of the #ifdef's were already set up for |
| 1129 | metaconfig. Of course metaconfig had evolved some since Perl4's days, |
| 1130 | but not so much that it posed any serious problems. |
| 1131 | |
| 1132 | =item Metaconfig worked for me |
| 1133 | |
| 1134 | My system at the time was Interactive 2.2, an SVR3.2/386 derivative that |
| 1135 | also had some POSIX support. Metaconfig-generated Configure scripts |
| 1136 | worked fine for me on that system. On the other hand, autoconf-generated |
| 1137 | scripts usually didn't. (They did come quite close, though, in some |
| 1138 | cases.) At the time, I actually fetched a large number of GNU packages |
| 1139 | and checked. Not a single one configured and compiled correctly |
| 1140 | out-of-the-box with the system's cc compiler. |
| 1141 | |
| 1142 | =item Configure can be interactive |
| 1143 | |
| 1144 | With both autoconf and metaconfig, if the script works, everything is |
| 1145 | fine. However, one of my main problems with autoconf-generated scripts |
| 1146 | was that if it guessed wrong about something, it could be B<very> hard to |
| 1147 | go back and fix it. For example, autoconf always insisted on passing the |
| 1148 | -Xp flag to cc (to turn on POSIX behavior), even when that wasn't what I |
| 1149 | wanted or needed for that package. There was no way short of editing the |
| 1150 | configure script to turn this off. You couldn't just edit the resulting |
| 1151 | Makefile at the end because the -Xp flag influenced a number of other |
| 1152 | configure tests. |
| 1153 | |
| 1154 | Metaconfig's Configure scripts, on the other hand, can be interactive. |
| 1155 | Thus if Configure is guessing things incorrectly, you can go back and fix |
| 1156 | them. This isn't as important now as it was when we were actively |
| 1157 | developing Configure support for new features such as dynamic loading, |
| 1158 | but it's still useful occasionally. |
| 1159 | |
| 1160 | =item GPL |
| 1161 | |
| 1162 | At the time, autoconf-generated scripts were covered under the GNU Public |
| 1163 | License, and hence weren't suitable for inclusion with Perl, which has a |
| 1164 | different licensing policy. (Autoconf's licensing has since changed.) |
| 1165 | |
| 1166 | =item Modularity |
| 1167 | |
| 1168 | Metaconfig builds up Configure from a collection of discrete pieces |
| 1169 | called "units". You can override the standard behavior by supplying your |
| 1170 | own unit. With autoconf, you have to patch the standard files instead. |
| 1171 | I find the metaconfig "unit" method easier to work with. Others |
| 1172 | may find metaconfig's units clumsy to work with. |
| 1173 | |
| 1174 | =back |
| 1175 | |
| 1176 | =head2 Why isn't there a directory to override Perl's library? |
| 1177 | |
| 1178 | Mainly because no one's gotten around to making one. Note that |
| 1179 | "making one" involves changing perl.c, Configure, config_h.SH (and |
| 1180 | associated files, see above), and I<documenting> it all in the |
| 1181 | INSTALL file. |
| 1182 | |
| 1183 | Apparently, most folks who want to override one of the standard library |
| 1184 | files simply do it by overwriting the standard library files. |
| 1185 | |
| 1186 | =head2 APPLLIB |
| 1187 | |
| 1188 | In the perl.c sources, you'll find an undocumented APPLLIB_EXP |
| 1189 | variable, sort of like PRIVLIB_EXP and ARCHLIB_EXP (which are |
| 1190 | documented in config_h.SH). Here's what APPLLIB_EXP is for, from |
| 1191 | a mail message from Larry: |
| 1192 | |
| 1193 | The main intent of APPLLIB_EXP is for folks who want to send out a |
| 1194 | version of Perl embedded in their product. They would set the symbol |
| 1195 | to be the name of the library containing the files needed to run or to |
| 1196 | support their particular application. This works at the "override" |
| 1197 | level to make sure they get their own versions of any library code that |
| 1198 | they absolutely must have configuration control over. |
| 1199 | |
| 1200 | As such, I don't see any conflict with a sysadmin using it for a |
| 1201 | override-ish sort of thing, when installing a generic Perl. It should |
| 1202 | probably have been named something to do with overriding though. Since |
| 1203 | it's undocumented we could still change it... :-) |
| 1204 | |
| 1205 | Given that it's already there, you can use it to override distribution modules. |
| 1206 | One way to do that is to add |
| 1207 | |
| 1208 | ccflags="$ccflags -DAPPLLIB_EXP=\"/my/override\"" |
| 1209 | |
| 1210 | to your config.over file. (You have to be particularly careful to get the |
| 1211 | double quotes in. APPLLIB_EXP must be a valid C string. It might |
| 1212 | actually be easier to just #define it yourself in perl.c.) |
| 1213 | |
| 1214 | Then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB. Perl will |
| 1215 | also search architecture-specific and version-specific subdirectories of |
| 1216 | APPLLIB_EXP. |
| 1217 | |
| 1218 | =head2 Shared libperl.so location |
| 1219 | |
| 1220 | Why isn't the shared libperl.so installed in /usr/lib/ along |
| 1221 | with "all the other" shared libraries? Instead, it is installed |
| 1222 | in $archlib, which is typically something like |
| 1223 | |
| 1224 | /usr/local/lib/perl5/archname/5.00404 |
| 1225 | |
| 1226 | and is architecture- and version-specific. |
| 1227 | |
| 1228 | The basic reason why a shared libperl.so gets put in $archlib is so that |
| 1229 | you can have more than one version of perl on the system at the same time, |
| 1230 | and have each refer to its own libperl.so. |
| 1231 | |
| 1232 | Three examples might help. All of these work now; none would work if you |
| 1233 | put libperl.so in /usr/lib. |
| 1234 | |
| 1235 | =over |
| 1236 | |
| 1237 | =item 1. |
| 1238 | |
| 1239 | Suppose you want to have both threaded and non-threaded perl versions |
| 1240 | around. Configure will name both perl libraries "libperl.so" (so that |
| 1241 | you can link to them with -lperl). The perl binaries tell them apart |
| 1242 | by having looking in the appropriate $archlib directories. |
| 1243 | |
| 1244 | =item 2. |
| 1245 | |
| 1246 | Suppose you have perl5.004_04 installed and you want to try to compile |
| 1247 | it again, perhaps with different options or after applying a patch. |
| 1248 | If you already have libperl.so installed in /usr/lib/, then it may be |
| 1249 | either difficult or impossible to get ld.so to find the new libperl.so |
| 1250 | that you're trying to build. If, instead, libperl.so is tucked away in |
| 1251 | $archlib, then you can always just change $archlib in the current perl |
| 1252 | you're trying to build so that ld.so won't find your old libperl.so. |
| 1253 | (The INSTALL file suggests you do this when building a debugging perl.) |
| 1254 | |
| 1255 | =item 3. |
| 1256 | |
| 1257 | The shared perl library is not a "well-behaved" shared library with |
| 1258 | proper major and minor version numbers, so you can't necessarily |
| 1259 | have perl5.004_04 and perl5.004_05 installed simultaneously. Suppose |
| 1260 | perl5.004_04 were to install /usr/lib/libperl.so.4.4, and perl5.004_05 |
| 1261 | were to install /usr/lib/libperl.so.4.5. Now, when you try to run |
| 1262 | perl5.004_04, ld.so might try to load libperl.so.4.5, since it has |
| 1263 | the right "major version" number. If this works at all, it almost |
| 1264 | certainly defeats the reason for keeping perl5.004_04 around. Worse, |
| 1265 | with development subversions, you certaily can't guarantee that |
| 1266 | libperl.so.4.4 and libperl.so.4.55 will be compatible. |
| 1267 | |
| 1268 | Anyway, all this leads to quite obscure failures that are sure to drive |
| 1269 | casual users crazy. Even experienced users will get confused :-). Upon |
| 1270 | reflection, I'd say leave libperl.so in $archlib. |
| 1271 | |
| 1272 | =back |
| 1273 | |
| 1274 | =head2 Indentation style |
| 1275 | |
| 1276 | Over the years Perl has become a mishmash of |
| 1277 | various indentation styles, but the original "Larry style" can |
| 1278 | probably be restored with (GNU) indent somewhat like this: |
| 1279 | |
| 1280 | indent -kr -nce -psl -sc |
| 1281 | |
| 1282 | A more ambitious solution would also specify a list of Perl specific |
| 1283 | types with -TSV -TAV -THV .. -TMAGIC -TPerlIO ... but that list would |
| 1284 | be quite ungainly. Also note that GNU indent also doesn't do aligning |
| 1285 | of consecutive assignments, which would truly wreck the layout in |
| 1286 | places like sv.c:Perl_sv_upgrade() or sv.c:Perl_clone_using(). |
| 1287 | Similarly nicely aligned &&s, ||s and ==s would not be respected. |
| 1288 | |
| 1289 | =head1 Upload Your Work to CPAN |
| 1290 | |
| 1291 | You can upload your work to CPAN if you have a CPAN id. Check out |
| 1292 | http://www.cpan.org/modules/04pause.html for information on |
| 1293 | _PAUSE_, the Perl Author's Upload Server. |
| 1294 | |
| 1295 | I typically upload both the patch file, e.g. F<perl5.004_08.pat.gz> |
| 1296 | and the full tar file, e.g. F<perl5.004_08.tar.gz>. |
| 1297 | |
| 1298 | If you want your patch to appear in the F<src/5.0/unsupported> |
| 1299 | directory on CPAN, send e-mail to the CPAN master librarian. (Check |
| 1300 | out http://www.cpan.org/CPAN.html ). |
| 1301 | |
| 1302 | =head1 Help Save the World |
| 1303 | |
| 1304 | You should definitely announce your patch on the perl5-porters list. |
| 1305 | You should also consider announcing your patch on |
| 1306 | comp.lang.perl.announce, though you should make it quite clear that a |
| 1307 | subversion is not a production release, and be prepared to deal with |
| 1308 | people who will not read your disclaimer. |
| 1309 | |
| 1310 | =head1 Todo |
| 1311 | |
| 1312 | Here, in no particular order, are some Configure and build-related |
| 1313 | items that merit consideration. This list isn't exhaustive, it's just |
| 1314 | what I came up with off the top of my head. |
| 1315 | |
| 1316 | =head2 Adding missing library functions to Perl |
| 1317 | |
| 1318 | The perl Configure script automatically determines which headers and |
| 1319 | functions you have available on your system and arranges for them to be |
| 1320 | included in the compilation and linking process. Occasionally, when porting |
| 1321 | perl to an operating system for the first time, you may find that the |
| 1322 | operating system is missing a key function. While perl may still build |
| 1323 | without this function, no perl program will be able to reference the missing |
| 1324 | function. You may be able to write the missing function yourself, or you |
| 1325 | may be able to find the missing function in the distribution files for |
| 1326 | another software package. In this case, you need to instruct the perl |
| 1327 | configure-and-build process to use your function. Perform these steps. |
| 1328 | |
| 1329 | =over 3 |
| 1330 | |
| 1331 | =item * |
| 1332 | |
| 1333 | Code and test the function you wish to add. Test it carefully; you will |
| 1334 | have a much easier time debugging your code independently than when it is a |
| 1335 | part of perl. |
| 1336 | |
| 1337 | =item * |
| 1338 | |
| 1339 | Here is an implementation of the POSIX truncate function for an operating |
| 1340 | system (VOS) that does not supply one, but which does supply the ftruncate() |
| 1341 | function. |
| 1342 | |
| 1343 | /* Beginning of modification history */ |
| 1344 | /* Written 02-01-02 by Nick Ing-Simmons (nick@ing-simmons.net) */ |
| 1345 | /* End of modification history */ |
| 1346 | |
| 1347 | /* VOS doesn't supply a truncate function, so we build one up |
| 1348 | from the available POSIX functions. */ |
| 1349 | |
| 1350 | #include <fcntl.h> |
| 1351 | #include <sys/types.h> |
| 1352 | #include <unistd.h> |
| 1353 | |
| 1354 | int |
| 1355 | truncate(const char *path, off_t len) |
| 1356 | { |
| 1357 | int fd = open(path,O_WRONLY); |
| 1358 | int code = -1; |
| 1359 | if (fd >= 0) { |
| 1360 | code = ftruncate(fd,len); |
| 1361 | close(fd); |
| 1362 | } |
| 1363 | return code; |
| 1364 | } |
| 1365 | |
| 1366 | Place this file into a subdirectory that has the same name as the operating |
| 1367 | system. This file is named perl/vos/vos.c |
| 1368 | |
| 1369 | =item * |
| 1370 | |
| 1371 | If your operating system has a hints file (in perl/hints/XXX.sh for an |
| 1372 | operating system named XXX), then start with it. If your operating system |
| 1373 | has no hints file, then create one. You can use a hints file for a similar |
| 1374 | operating system, if one exists, as a template. |
| 1375 | |
| 1376 | =item * |
| 1377 | |
| 1378 | Add lines like the following to your hints file. The first line |
| 1379 | (d_truncate="define") instructs Configure that the truncate() function |
| 1380 | exists. The second line (archobjs="vos.o") instructs the makefiles that the |
| 1381 | perl executable depends on the existence of a file named "vos.o". (Make |
| 1382 | will automatically look for "vos.c" and compile it with the same options as |
| 1383 | the perl source code). The final line ("test -h...") adds a symbolic link |
| 1384 | to the top-level directory so that make can find vos.c. Of course, you |
| 1385 | should use your own operating system name for the source file of extensions, |
| 1386 | not "vos.c". |
| 1387 | |
| 1388 | # VOS does not have truncate() but we supply one in vos.c |
| 1389 | d_truncate="define" |
| 1390 | archobjs="vos.o" |
| 1391 | |
| 1392 | # Help gmake find vos.c |
| 1393 | test -h vos.c || ln -s vos/vos.c vos.c |
| 1394 | |
| 1395 | The hints file is a series of shell commands that are run in the top-level |
| 1396 | directory (the "perl" directory). Thus, these commands are simply executed |
| 1397 | by Configure at an appropriate place during its execution. |
| 1398 | |
| 1399 | =item * |
| 1400 | |
| 1401 | At this point, you can run the Configure script and rebuild perl. Carefully |
| 1402 | test the newly-built perl to ensure that normal paths, and error paths, |
| 1403 | behave as you expect. |
| 1404 | |
| 1405 | =back |
| 1406 | |
| 1407 | =head2 Good ideas waiting for round tuits |
| 1408 | |
| 1409 | =over 4 |
| 1410 | |
| 1411 | =item Configure -Dsrc=/blah/blah |
| 1412 | |
| 1413 | We should be able to emulate B<configure --srcdir>. Tom Tromey |
| 1414 | tromey@creche.cygnus.com has submitted some patches to |
| 1415 | the dist-users mailing list along these lines. They have been folded |
| 1416 | back into the main distribution, but various parts of the perl |
| 1417 | Configure/build/install process still assume src='.'. |
| 1418 | |
| 1419 | =item Hint file fixes |
| 1420 | |
| 1421 | Various hint files work around Configure problems. We ought to fix |
| 1422 | Configure so that most of them aren't needed. |
| 1423 | |
| 1424 | =item Hint file information |
| 1425 | |
| 1426 | Some of the hint file information (particularly dynamic loading stuff) |
| 1427 | ought to be fed back into the main metaconfig distribution. |
| 1428 | |
| 1429 | =back |
| 1430 | |
| 1431 | =head2 Probably good ideas waiting for round tuits |
| 1432 | |
| 1433 | =over 4 |
| 1434 | |
| 1435 | =item GNU configure --options |
| 1436 | |
| 1437 | I've received sensible suggestions for --exec_prefix and other |
| 1438 | GNU configure --options. It's not always obvious exactly what is |
| 1439 | intended, but this merits investigation. |
| 1440 | |
| 1441 | =item make clean |
| 1442 | |
| 1443 | Currently, B<make clean> isn't all that useful, though |
| 1444 | B<make realclean> and B<make distclean> are. This needs a bit of |
| 1445 | thought and documentation before it gets cleaned up. |
| 1446 | |
| 1447 | =item Try gcc if cc fails |
| 1448 | |
| 1449 | Currently, we just give up. |
| 1450 | |
| 1451 | =item bypassing safe*alloc wrappers |
| 1452 | |
| 1453 | On some systems, it may be safe to call the system malloc directly |
| 1454 | without going through the util.c safe* layers. (Such systems would |
| 1455 | accept free(0), for example.) This might be a time-saver for systems |
| 1456 | that already have a good malloc. (Recent Linux libc's apparently have |
| 1457 | a nice malloc that is well-tuned for the system.) |
| 1458 | |
| 1459 | =back |
| 1460 | |
| 1461 | =head2 Vague possibilities |
| 1462 | |
| 1463 | =over 4 |
| 1464 | |
| 1465 | =item MacPerl |
| 1466 | |
| 1467 | Get some of the Macintosh stuff folded back into the main distribution. |
| 1468 | |
| 1469 | =item gconvert replacement |
| 1470 | |
| 1471 | Maybe include a replacement function that doesn't lose data in rare |
| 1472 | cases of coercion between string and numerical values. |
| 1473 | |
| 1474 | =item Improve makedepend |
| 1475 | |
| 1476 | The current makedepend process is clunky and annoyingly slow, but it |
| 1477 | works for most folks. Alas, it assumes that there is a filename |
| 1478 | $firstmakefile that the B<make> command will try to use before it uses |
| 1479 | F<Makefile>. Such may not be the case for all B<make> commands, |
| 1480 | particularly those on non-Unix systems. |
| 1481 | |
| 1482 | Probably some variant of the BSD F<.depend> file will be useful. |
| 1483 | We ought to check how other packages do this, if they do it at all. |
| 1484 | We could probably pre-generate the dependencies (with the exception of |
| 1485 | malloc.o, which could probably be determined at F<Makefile.SH> |
| 1486 | extraction time. |
| 1487 | |
| 1488 | =item GNU Makefile standard targets |
| 1489 | |
| 1490 | GNU software generally has standardized Makefile targets. Unless we |
| 1491 | have good reason to do otherwise, I see no reason not to support them. |
| 1492 | |
| 1493 | =item File locking |
| 1494 | |
| 1495 | Somehow, straighten out, document, and implement lockf(), flock(), |
| 1496 | and/or fcntl() file locking. It's a mess. See $d_fcntl_can_lock |
| 1497 | in recent config.sh files though. |
| 1498 | |
| 1499 | =back |
| 1500 | |
| 1501 | =head2 Copyright Issues |
| 1502 | |
| 1503 | The following is based on the consensus of a couple of IPR lawyers, |
| 1504 | but it is of course not a legally binding statement, just a common |
| 1505 | sense summary. |
| 1506 | |
| 1507 | =over 4 |
| 1508 | |
| 1509 | =item * |
| 1510 | |
| 1511 | Tacking on copyright statements is unnecessary to begin with because |
| 1512 | of the Berne convention. But assuming you want to go ahead... |
| 1513 | |
| 1514 | =item * |
| 1515 | |
| 1516 | The right form of a copyright statement is |
| 1517 | |
| 1518 | Copyright (C) Year, Year, ... by Someone |
| 1519 | |
| 1520 | The (C) is not required everywhere but it doesn't hurt and in certain |
| 1521 | jurisdictions it is required, so let's leave it in. (Yes, it's true |
| 1522 | that in some jurisdictions the "(C)" is not legally binding, one should |
| 1523 | use the true ringed-C. But we don't have that character available for |
| 1524 | Perl's source code.) |
| 1525 | |
| 1526 | The years must be listed out separately. Year-Year is not correct. |
| 1527 | Only the years when the piece has changed 'significantly' may be added. |
| 1528 | |
| 1529 | =item * |
| 1530 | |
| 1531 | One cannot give away one's copyright trivially. One can give one's |
| 1532 | copyright away by using public domain, but even that requires a little |
| 1533 | bit more than just saying 'this is in public domain'. (What it |
| 1534 | exactly requires depends on your jurisdiction.) But barring public |
| 1535 | domain, one cannot "transfer" one's copyright to another person or |
| 1536 | entity. In the context of software, it means that contributors cannot |
| 1537 | give away their copyright or "transfer" it to the "owner" of the software. |
| 1538 | |
| 1539 | Also remember that in many cases if you are employed by someone, |
| 1540 | your work may be copyrighted to your employer, even when you are |
| 1541 | contributing on your own time (this all depends on too many things |
| 1542 | to list here). But the bottom line is that you definitely can't give |
| 1543 | away a copyright you may not even have. |
| 1544 | |
| 1545 | What is possible, however, is that the software can simply state |
| 1546 | |
| 1547 | Copyright (C) Year, Year, ... by Someone and others |
| 1548 | |
| 1549 | and then list the "others" somewhere in the distribution. |
| 1550 | And this is exactly what Perl does. (The "somewhere" is |
| 1551 | AUTHORS and the Changes* files.) |
| 1552 | |
| 1553 | =item * |
| 1554 | |
| 1555 | Split files, merged files, and generated files are problematic. |
| 1556 | The rule of thumb: in split files, copy the copyright years of |
| 1557 | the original file to all the new files; in merged files make |
| 1558 | an union of the copyright years of all the old files; in generated |
| 1559 | files propagate the copyright years of the generating file(s). |
| 1560 | |
| 1561 | =item * |
| 1562 | |
| 1563 | The files of Perl source code distribution do carry a lot of |
| 1564 | copyrights, by various people. (There are many copyrights embedded in |
| 1565 | perl.c, for example.) The most straightforward thing for pumpkings to |
| 1566 | do is to simply update Larry's copyrights at the beginning of the |
| 1567 | *.[hcy], x2p/*.[hcy], *.pl, and README files, and leave all other |
| 1568 | copyrights alone. Doing more than that requires quite a bit of tracking. |
| 1569 | |
| 1570 | =back |
| 1571 | |
| 1572 | =head1 AUTHORS |
| 1573 | |
| 1574 | Original author: Andy Dougherty doughera@lafayette.edu . |
| 1575 | Additions by Chip Salzenberg chip@perl.com and |
| 1576 | Tim Bunce Tim.Bunce@ig.co.uk . |
| 1577 | |
| 1578 | All opinions expressed herein are those of the authorZ<>(s). |
| 1579 | |
| 1580 | =head1 LAST MODIFIED |
| 1581 | |
| 1582 | $Id: pumpkin.pod,v 1.23 2000/01/13 19:45:13 doughera Released $ |