X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=Porting%2Fpumpkin.pod;h=44fde71970cce638dd5b883b08504170c4a5df61;hb=4f17444bfdadccc916ed92105c913310503bea91;hp=55c1eb84b4e9f685bdb37c8055ff6f47b2fe017a;hpb=f5a32c7f87cd929827e4ff3bd7c4afabda8d29d9;p=p5sagit%2Fp5-mst-13.2.git diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index 55c1eb8..44fde71 100644 --- a/Porting/pumpkin.pod +++ b/Porting/pumpkin.pod @@ -58,7 +58,7 @@ and 1 is the subversion. For compatibility with the older numbering scheme the composite floating point version number continues to be available as the magic variable $], -and amounts to C<$revision + $version/1000 + $subversion/1000000>. This +and amounts to C<$revision + $version/1000 + $subversion/100000>. This can still be used in comparisons. print "You've got an old perl\n" if $] < 5.005_03; @@ -158,6 +158,7 @@ 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. +There's a script, check83.pl, for keeping your nose 8.3-clean. =head2 Seek consensus on major changes @@ -210,7 +211,7 @@ 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 +The extension hints are written in 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. @@ -252,7 +253,8 @@ the first B to have a system call also update the list of 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. +to expect, is nice too. Such files are in the process of being written +in pod format and will eventually be renamed F. You may also want to write a separate F<.pod> file for your operating system to tell about existing mailing lists, os-specific modules, @@ -449,7 +451,9 @@ safely be sorted, so it's easy to track (typically very small) changes to config.sh and then propoagate them to a canned 'config.h' by any number of means, including a perl script in win32/ or carrying config.sh and config_h.SH to a Unix system and running sh -config_h.SH.) +config_h.SH.) Vms uses configure.com to generate its own config.sh +and config.h. If you want to add a new variable to config.sh check +with vms folk how to add it to configure.com too. XXX] The Porting/config.sh and Porting/config_H files are provided to @@ -460,7 +464,7 @@ distinguish the file from config.h even on case-insensitive file systems.) Simply edit the existing config_H file; keep the first few explanatory lines and then copy your new config.h below. -It may also be necessary to update win32/config.?c, vms/config.vms and +It may also be necessary to update win32/config.?c, and plan9/config.plan9, though you should be quite careful in doing so if you are not familiar with those systems. You might want to issue your patch with a promise to quickly issue a follow-up that handles those @@ -481,8 +485,10 @@ output statements mean the patch won't apply cleanly. Long ago I started to fix F to detect this, but I never completed the task. -If C changes, make sure you run C to -update the corresponding VMS files. See L. +If C or C changes, make sure you run C +to update the corresponding VMS files. This could be taken care of by +the regen_all target in the Unix Makefile. See also +L. Some additional notes from Larry on this: @@ -507,6 +513,11 @@ could be automated, but it doesn't happen very often nowadays. Larry +=head2 make regen_all + +This target takes care of the PERLYVMS, regen_headers, and regen_pods +targets. + =head2 make regen_headers The F, F, and F files are all automatically @@ -532,6 +543,10 @@ and effort by manually running C myself rather than answering all the questions and complaints about the failing command. +=head2 make regen_pods + +Will run `make regen_pods` in the pod directory for indexing. + =head2 global.sym, interp.sym and perlio.sym Make sure these files are up-to-date. Read the comments in these @@ -541,7 +556,7 @@ files and in perl_exp.SH to see what to do. If you do change F or F, think carefully about what you are doing. To the extent reasonable, we'd like to maintain -souce and binary compatibility with older releases of perl. That way, +source and binary compatibility with older releases of perl. That way, extensions built under one version of perl will continue to work with new versions of perl. @@ -594,11 +609,11 @@ things that need to be fixed in Configure. =head2 VMS-specific updates If you have changed F or F, then you most probably want -to update F by running C. +to update F by running C, or +by running `make regen_all` which will run that script for you. -The Perl version number appears in several places under F. -It is courteous to update these versions. For example, if you are -making 5.004_42, replace "5.00441" with "5.00442". +The Perl revision number appears as "perl5" in configure.com. +It is courteous to update that if necessary. =head2 Making the new distribution @@ -701,7 +716,53 @@ supports dynamic loading, you can also test static loading with You can also hand-tweak your config.h to try out different #ifdef branches. -=head1 Purify runs +=head2 Other tests + +=over 4 + +=item CHECK_FORMAT + +To test the correct use of printf-style arguments, C with +S<-Dccflags='-DCHECK_FORMAT -Wformat'> and run C. The compiler +will produce warning of incorrect use of format arguments. CHECK_FORMAT +changes perl-defined formats to common formats, so DO NOT USE the executable +produced by this process. + +A more accurate approach is the following commands: + +=over 4 + +=item * + +build miniperl with -DCHECK_FORMAT + + make clean + make miniperl OPTIMIZE=-DCHECK_FORMAT >& mini.log + +=item * + +build a clean miniperl, +and build everything else from that with -DCHECK_FORMAT + + make clean + make miniperl + make all OPTIMIZE=-DCHECK_FORMAT >& make.log + +=item * + +clean up, and print warnings from the log files + + make clean + perl -nwe 'print if /^\S+:/ and not /^make\b/' \ + mini.log make.log + +=back + +(-Wformat support by Robin Barker.) + +=back + +=head1 Running Purify Purify is a commercial tool that is helpful in identifying memory overruns, wild pointers, memory leaks and other such badness. Perl @@ -715,6 +776,7 @@ Use the following commands to test perl with Purify: make all pureperl cd t ln -s ../pureperl perl + setenv PERL_DESTRUCT_LEVEL 2 ./perl TEST Disabling Perl's malloc allows Purify to monitor allocations and leaks @@ -1324,7 +1386,8 @@ have good reason to do otherwise, I see no reason not to support them. =item File locking Somehow, straighten out, document, and implement lockf(), flock(), -and/or fcntl() file locking. It's a mess. +and/or fcntl() file locking. It's a mess. See $d_fcntl_can_lock +in recent config.sh files though. =back