From: Jarkko Hietaniemi Date: Thu, 17 Dec 1998 12:17:19 +0000 (+0000) Subject: More porting notes. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=98dddfbde85ba9abd899e710b443f45cc7cf07e0;p=p5sagit%2Fp5-mst-13.2.git More porting notes. p4raw-id: //depot/cfgperl@2485 --- diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index db29b75..e3e8b7c 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, @@ -208,14 +208,23 @@ 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. +Remember to update C when you add files. -=head2 Machine-specific hints +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 @@ -231,14 +240,53 @@ miniperl has been built) and control the building of their respective extensions. They can be used to for example manipulate compilation and linking flags. -=head2 Machine-specific tests +=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. -Some of the tests in C subdirectory assume machine-specific things +=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 or customize the tests for your platform. +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 @@ -255,7 +303,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 @@ -269,6 +317,9 @@ 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 with the metaconfig units. See L<"run metaconfig"> below for