From: Jarkko Hietaniemi Date: Sun, 13 Dec 1998 12:32:42 +0000 (+0000) Subject: Some notes about porting issues. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=a6968aa6b3935adbe27690e3c0b55deffa52e62d;p=p5sagit%2Fp5-mst-13.2.git Some notes about porting issues. p4raw-id: //depot/cfgperl@2474 --- diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index f62f753..db29b75 100644 --- a/Porting/pumpkin.pod +++ b/Porting/pumpkin.pod @@ -155,7 +155,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 +174,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 +206,40 @@ 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 + +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. + +=head2 Machine-specific 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. + +=head2 Machine-specific tests + +Some 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. + =head2 Allow for lots of testing We should never release a main version without testing it as a @@ -219,11 +263,11 @@ 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. Finally, the sample files in the F subdirectory are generated automatically by the script F included