diff options
| -rw-r--r-- | Porting/pumpkin.pod | 67 |
1 files changed, 59 insertions, 8 deletions
diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index db29b754fb..e3e8b7cb27 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<MANIFEST>. +Remember to update C<MANIFEST> when you add files. -=head2 Machine-specific hints +If your system support dynamic loading but none of the existing +methods at F<ext/DynaLoader/dl_*.xs> 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<hints> 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<Makefile.SH> and F<installperl>. +Tread very carefully, even more than usual. Contain your changes +with utmost care. -Some of the tests in C<t> subdirectory assume machine-specific things +=item test suite + +Many of the tests in C<t> 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<Config> module (which contains the results of the Configure run, in effect the C<config.sh> 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<pod/perlport.pod>. If your operating system is +the first B<not> to have a system call also update the list of +"portability-bewares" at the beginning of F<pod/perlfunc.pod>. + +A file called F<README.youros> 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 +F<perl>I<youros>.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<embed.h>, F<keywords.h>, F<opcode.h>, and F<perltoc.pod> 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<Makefile> is automatically produced from F<Makefile.SH>. +In general, look out for all F<*.SH> files. + Finally, the sample files in the F<Porting/> subdirectory are generated automatically by the script F<U/mksample> included with the metaconfig units. See L<"run metaconfig"> below for |