X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=Porting%2Fpumpkin.pod;h=42f44286730bb6664c608a6e442a77ec3effe61e;hb=0fa156b9cc6e57c94350bf8b3486af3d1c7dd41d;hp=d7610595f04d5508fd6aa544e459d9e4be590d7c;hpb=d2560b705d852dbc96fd94b95faaa076758b7a8c;p=p5sagit%2Fp5-mst-13.2.git diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index d761059..42f4428 100644 --- a/Porting/pumpkin.pod +++ b/Porting/pumpkin.pod @@ -24,7 +24,7 @@ and all the various auxiliary files that are part of the distribution. The Comprehensive Perl Archive Network (or CPAN) is the place to go. There are many mirrors, but the easiest thing to use is probably -http://www.perl.com/CPAN/README.html , which automatically points you to a +http://www.cpan.org/README.html , which automatically points you to a mirror site "close" to you. =head2 Perl5-porters mailing list @@ -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. @@ -240,6 +241,9 @@ 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. +Remember to have a $VERSION in the modules. You can use the +Porting/checkVERSION.pl script for checking this. + =item documentation If your operating system comes from outside UNIX you almost certainly @@ -252,7 +256,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, @@ -357,7 +362,7 @@ on obtaining and running metaconfig is in the F file that comes with Perl's metaconfig units. Perl's metaconfig units should be available on CPAN. A set of units that will work with perl5.005 is in the file F under -http://www.perl.com/CPAN/authors/id/ANDYD/ . The mc_units tar file +http://www.cpan.org/authors/id/ANDYD/ . The mc_units tar file should be unpacked in your main perl source directory. Note: those units were for use with 5.005. There may have been changes since then. Check for later versions or contact perl5-porters@perl.org to obtain a @@ -449,7 +454,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 +467,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 +488,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 +516,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 +546,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 +559,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 +612,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 @@ -618,7 +636,7 @@ script. I find the F utility quite handy for making patches. You can obtain it from any CPAN archive under -http://www.perl.com/CPAN/authors/Johan_Vromans/ . There are a couple +http://www.cpan.org/authors/Johan_Vromans/ . There are a couple of differences between my version and the standard one. I have mine do a @@ -715,15 +733,33 @@ produced by this process. A more accurate approach is the following commands: - sh Configure -des -Dccflags=-Wformat ... - make miniperl # without -DCHECK_FORMAT - perl -i.orig -pwe 's/-Wformat/-DCHECK_FORMAT $&/' config.sh - sh Configure -S - make >& make.log # build from correct miniperl +=over 4 + +=item * + +build miniperl with -DCHECK_FORMAT + make clean - make miniperl >& mini.log # build miniperl with -DCHECK_FORMAT - perl -nwe 'print if /^\S+:/ and not /^make\b/' mini.log make.log + 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.) @@ -743,7 +779,7 @@ Use the following commands to test perl with Purify: make all pureperl cd t ln -s ../pureperl perl - setenv PERL_DESTRUCT_LEVEL 5 + setenv PERL_DESTRUCT_LEVEL 2 ./perl TEST Disabling Perl's malloc allows Purify to monitor allocations and leaks @@ -1103,7 +1139,7 @@ but not so much that it posed any serious problems. =item Metaconfig worked for me -My system at the time was Interactive 2.2, a SVR3.2/386 derivative that +My system at the time was Interactive 2.2, an SVR3.2/386 derivative that also had some POSIX support. Metaconfig-generated Configure scripts worked fine for me on that system. On the other hand, autoconf-generated scripts usually didn't. (They did come quite close, though, in some @@ -1240,7 +1276,7 @@ reflection, I'd say leave libperl.so in $archlib. =head1 Upload Your Work to CPAN You can upload your work to CPAN if you have a CPAN id. Check out -http://www.perl.com/CPAN/modules/04pause.html for information on +http://www.cpan.org/modules/04pause.html for information on _PAUSE_, the Perl Author's Upload Server. I typically upload both the patch file, e.g. F @@ -1248,7 +1284,7 @@ and the full tar file, e.g. F. If you want your patch to appear in the F directory on CPAN, send e-mail to the CPAN master librarian. (Check -out http://www.perl.com/CPAN/CPAN.html ). +out http://www.cpan.org/CPAN.html ). =head1 Help Save the World @@ -1353,7 +1389,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