X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=Porting%2Fpumpkin.pod;h=1f53c2679406e6d75770c5603c9c99de85de7d44;hb=472a4973258a334c0ca9dab6c0aa2926a6dc3433;hp=f62f753056c3e1359eef18d3d161c7c0780e3e91;hpb=ebb9925428467601f365b797b9f30a0507ef87e1;p=p5sagit%2Fp5-mst-13.2.git diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index f62f753..1f53c26 100644 --- a/Porting/pumpkin.pod +++ b/Porting/pumpkin.pod @@ -8,8 +8,8 @@ There is no simple synopsis, yet. =head1 DESCRIPTION -This document attempts to begin to describe some of the -considerations involved in patching and maintaining perl. +This document attempts to begin to describe some of the considerations +involved in patching, porting, and maintaining perl. This document is still under construction, and still subject to significant changes. Still, I hope parts of it will be useful, @@ -73,14 +73,12 @@ Let's worry about that problem when we get there. =head2 Subversions -In addition, there may be "developer" sub-versions available. These -are not official releases. They may contain unstable experimental -features, and are subject to rapid change. Such developer -sub-versions are numbered with sub-version numbers. For example, -version 5.003_04 is the 4'th developer version built on top of -5.003. It might include the _01, _02, and _03 changes, but it -also might not. Sub-versions are allowed to be subversive. (But see -the next section for recent changes.) +In addition, there usually are sub-versions available. Sub-versions +are numbered with sub-version numbers. For example, version 5.003_04 +is the 4'th developer version built on top of 5.003. It might include +the _01, _02, and _03 changes, but it also might not. Sub-versions are +allowed to be subversive. (But see the next section for recent +changes.) These sub-versions can also be used as floating point numbers, so you can do things such as @@ -92,28 +90,47 @@ You can also require particular version (or later) with use 5.003_03; # the "_" is optional Sub-versions produced by the members of perl5-porters are usually -available on CPAN in the F directory. +available on CPAN in the F and F +directories. =head2 Maintenance and Development Subversions -As an experiment, starting with version 5.004, subversions _01 through -_49 will be reserved for bug-fix maintenance releases, and subversions -_50 through _99 will be available for unstable development versions. +Starting with version 5.004, subversions _01 through _49 is reserved +for bug-fix maintenance releases, and subversions _50 through _99 for +unstable development versions. The separate bug-fix track is being established to allow us an easy way to distribute important bug fixes without waiting for the developers to untangle all the other problems in the current -developer's release. +developer's release. The first rule of maintenance work is "First, do +no harm." Trial releases of bug-fix maintenance releases are announced on perl5-porters. Trial releases use the new subversion number (to avoid testers installing it over the previous release) and include a 'local -patch' entry in patchlevel.h. +patch' entry in patchlevel.h. The distribution file contains the +string C to make clear that the file is not meant for +public consumption. + +In general, the names of official distribution files for the public +always match the regular expression + + ^perl5\.\d{3}(_[0-4]\d)?\.tar\.gz$ + +Developer releases always match -Watch for announcements of maintenance subversions in -comp.lang.perl.announce. + ^perl5\.\d{3}(_[5-9]\d)?\.tar\.gz$ -The first rule of maintenance work is "First, do no harm." +And the trial versions for a new maintainance release match + + ^perl5\.\d{3}(_[0-4]\d)-MAINT_TRIAL_\d+\.tar\.gz$ + +In the past it has been observed that pumkings tend to invent new +naming conventions on the fly. If you are a pumpking, before you +invent a new name for any of the three types of perl distributions, +please inform the guys from the CPAN who are doing indexing and +provide the trees of symlinks and the like. They will have to know +I what you decide. =head2 Why such a complicated scheme? @@ -155,7 +172,7 @@ No one was allowed to make backups unless they had the "backup pumpkin". The name has stuck. -=head1 Philosophical Issues in Patching Perl +=head1 Philosophical Issues in Patching and Porting Perl There are no absolute rules, but there are some general guidelines I have tried to follow as I apply patches to the perl sources. @@ -174,6 +191,16 @@ generalized the process of building libperl so that NeXT and SVR4 users could still get their work done, but others could build a shared libperl if they wanted to as well. +Contain your changes carefully. Assume nothing about other operating +systems, not even closely related ones. Your changes must not affect +other platforms. + +Spy shamelessly on how similar patching or porting issues have been +settled elsewhere. + +If feasible, try to keep filenames 8.3-compliant to humor those poor +souls that get joy from running Perl under such dire limitations. + =head2 Seek consensus on major changes If you are making big changes, don't do it in secret. Discuss the @@ -196,6 +223,88 @@ that the machine-specific #ifdef's may not be valid across major releases of the operating system. Further, the feature-specific tests may help out folks on another platform who have the same problem. +=head2 Machine-specific files + +=over 4 + +=item source code + +If you have many machine-specific #defines or #includes, consider +creating an "osish.h" (os2ish.h, vmsish.h, and so on) and including +that in perl.h. If you have several machine-specific files (function +emulations, function stubs, build utility wrappers) you may create a +separate subdirectory (djgpp, win32) and put the files in there. +Remember to update C when you add files. + +If your system support dynamic loading but none of the existing +methods at F work for you, you must write +a new one. Study the existing ones to see what kind of interface +you must supply. + +=item build hints + +There are two kinds of hints: hints for building Perl and hints for +extensions. The former live in the C subdirectory, the latter +in C subdirectories. + +The top level hints are Bourne-shell scripts that set, modify and +unset appropriate Configure variables, based on the Configure command +line options and possibly existing config.sh and Policy.sh files from +previous Configure runs. + +The extension hints are written Perl (by the time they are used +miniperl has been built) and control the building of their respective +extensions. They can be used to for example manipulate compilation +and linking flags. + +=item build and installation Makefiles, scripts, and so forth + +Sometimes you will also need to tweak the Perl build and installation +procedure itself, like for example F and F. +Tread very carefully, even more than usual. Contain your changes +with utmost care. + +=item test suite + +Many of the tests in C subdirectory assume machine-specific things +like existence of certain functions, something about filesystem +semantics, certain external utilities and their error messages. Use +the C<$^O> and the C module (which contains the results of the +Configure run, in effect the C converted to Perl) to either +skip (preferably not) or customize (preferable) the tests for your +platform. + +=item modules + +Certain standard modules may need updating if your operating system +sports for example a native filesystem naming. You may want to update +some or all of the modules File::Basename, File::Spec, File::Path, and +File::Copy to become aware of your native filesystem syntax and +peculiarities. + +=item documentation + +If your operating system comes from outside UNIX you almost certainly +will have differences in the available operating system functionality +(missing system calls, different semantics, whatever). Please +document these at F. If your operating system is +the first B to have a system call also update the list of +"portability-bewares" at the beginning of F. + +A file called F at the top level that explains things +like how to install perl at this platform, where to get any possibly +required additional software, and for example what test suite errors +to expect, is nice too. + +You may also want to write a separate F<.pod> file for your operating +system to tell about existing mailing lists, os-specific modules, +documentation, whatever. Please name these along the lines of +FI.pod. [unfinished: where to put this file (the pod/ +subdirectory, of course: but more importantly, which/what index files +should be updated?)] + +=back + =head2 Allow for lots of testing We should never release a main version without testing it as a @@ -211,7 +320,7 @@ that some of those things will be just plain broken and need to be fixed, but, in general, we ought to try to avoid breaking widely-installed things. -=head2 Automate generation of derivative files +=head2 Automated generation of derivative files The F, F, F, and F files are all automatically generated by perl scripts. In general, don't @@ -219,11 +328,14 @@ patch these directly; patch the data files instead. F and F are also automatically generated by B. In general, you should patch the metaconfig units -instead of patching these files directly. However, very minor changes to -F may be made in between major sync-ups with the metaconfig -units, which tends to be complicated operations. But be careful, this -can quickly spiral out of control. Running metaconfig is not really -hard. +instead of patching these files directly. However, very minor changes +to F may be made in between major sync-ups with the +metaconfig units, which tends to be complicated operations. But be +careful, this can quickly spiral out of control. Running metaconfig +is not really hard. + +Also F is automatically produced from F. +In general, look out for all F<*.SH> files. Finally, the sample files in the F subdirectory are generated automatically by the script F included