X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/449b893f0f01dace40f6b620372b0098345284a8..c157f5d2977bb9a463059e5684f4630a38194592:/Porting/pumpkin.pod diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index 3e13cdd..1f289f7 100644 --- a/Porting/pumpkin.pod +++ b/Porting/pumpkin.pod @@ -91,7 +91,7 @@ The first rule of maintenance work is "First, do no harm." Trial releases of bug-fix maintenance releases are announced on perl5-porters. Trial releases use the new subversion number (to avoid testers installing it over the previous release) and include a 'local -patch' entry in patchlevel.h. The distribution file contains the +patch' entry in F. The distribution file contains the string C to make clear that the file is not meant for public consumption. @@ -158,7 +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. +There's a script, F, for keeping your nose 8.3-clean. In a similar vein, do not create files or directories which differ only in case (upper versus lower). @@ -191,8 +191,8 @@ may help out folks on another platform who have the same problem. =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 +creating an "osish.h" (F, F, and so on) and including +that in F. 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 when you add files. @@ -244,7 +244,7 @@ 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. +F script for checking this. =item documentation @@ -287,7 +287,8 @@ things. =head2 Automated generation of derivative files -The F, F, F, and F files +The F, F, F, F, +F, and F files are all automatically generated by perl scripts. In general, don't patch these directly; patch the data files instead. @@ -309,51 +310,12 @@ information on obtaining the metaconfig units. =head1 How to Make a Distribution -There really ought to be a 'make dist' target, but there isn't. -The 'dist' suite of tools also contains a number of tools that I haven't -learned how to use yet. Some of them may make this all a bit easier. +This section has now been expanded and moved into its own file, +F. -Here are the steps I go through to prepare a patch & distribution. - -Lots of it could doubtless be automated but isn't. The Porting/makerel -(make release) perl script does now help automate some parts of it. - -=head2 Announce your intentions - -First, you should volunteer out loud to take the patch pumpkin. It's -generally counter-productive to have multiple people working in secret -on the same thing. - -At the same time, announce what you plan to do with the patch pumpkin, -to allow folks a chance to object or suggest alternatives, or do it for -you. Naturally, the patch pumpkin holder ought to incorporate various -bug fixes and documentation improvements that are posted while he or -she has the pumpkin, but there might also be larger issues at stake. - -One of the precepts of the subversion idea is that we shouldn't give -the patch pumpkin to anyone unless we have some idea what he or she -is going to do with it. - -=head2 refresh pod/perltoc.pod - -Presumably, you have done a full C in your working source -directory. Before you C (if you do), and if you have -changed any documentation in any module or pod file, change to the -F directory and run C. - -=head2 run installhtml to check the validity of the pod files - -=head2 update patchlevel.h - -Don't be shy about using the subversion number, even for a relatively -modest patch. We've never even come close to using all 99 subversions, -and it's better to have a distinctive number for your patch. If you -need feedback on your patch, go ahead and issue it and promise to -incorporate that feedback quickly (e.g. within 1 week) and send out a -second patch. - -If you update the subversion number, you may need to change the version -number near the top of the F file. +I've kept some of the subsections here for now, as they don't directly +relate to building a release any more, but still contain what might be +useful information - DAPM 7/2009. =head2 run metaconfig @@ -362,7 +324,7 @@ change the appropriate metaconfig units instead, and regenerate Configure. metaconfig -m -will regenerate Configure and config_h.SH. Much more information +will regenerate F and F. Much more information on obtaining and running metaconfig is in the F file that comes with Perl's metaconfig units. @@ -375,7 +337,7 @@ files that come with the metaunits. Perl's metaconfig units should be available on CPAN. A set of units that will work with perl5.9.x is in a file with a name similar to -F under http://www.cpan.org/authors/id/H/HM/HMBRAND/ . +F under L. The mc_units tar file should be unpacked in your main perl source directory. Note: those units were for use with 5.9.x. There may have been changes since then. Check for later versions or contact perl5-porters@perl.org to obtain a @@ -386,57 +348,12 @@ a better place for your changes. =head2 MANIFEST -Make sure the MANIFEST is up-to-date. You can use dist's B -program for this. You can also use - - perl -w -MExtUtils::Manifest=fullcheck -e fullcheck - -Both commands will also list extra files in the directory that are not -listed in MANIFEST. - -The MANIFEST is normally sorted. - If you are using metaconfig to regenerate Configure, then you should note that metaconfig actually uses MANIFEST.new, so you want to be sure MANIFEST.new is up-to-date too. I haven't found the MANIFEST/MANIFEST.new distinction particularly useful, but that's probably because I still haven't learned how to use the full suite of tools in the dist distribution. -=head2 Check permissions - -All the tests in the t/ directory ought to be executable. The -main makefile used to do a 'chmod t/*/*.t', but that resulted in -a self-modifying distribution--something some users would strongly -prefer to avoid. The F script will check for this -and do the chmod if needed, but the tests still ought to be -executable. - -In all, the following files should probably be executable: - - Configure - configpm - configure.gnu - embed.pl - installperl - installman - keywords.pl - myconfig - opcode.pl - t/TEST - t/*/*.t - *.SH - vms/ext/Stdio/test.pl - vms/ext/filespec.t - x2p/*.SH - -Other things ought to be readable, at least :-). - -Probably, the permissions for the files could be encoded in MANIFEST -somehow, but I'm reluctant to change MANIFEST itself because that -could break old scripts that use MANIFEST. - -I seem to recall that some SVR3 systems kept some sort of file that listed -permissions for system files; something like that might be appropriate. =head2 Run Configure @@ -465,47 +382,48 @@ sometimes be very hard to follow. config.sh, on the other hand, can safely be sorted, so it's easy to track (typically very small) changes to config.sh and then propagate 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.) 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 +F and F to a Unix system and running sh +config_h.SH.) Vms uses F to generate its own F +and F. If you want to add a new variable to F 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 +The F and F files are provided to help those folks who can't run Configure. It is important to keep -them up-to-date. If you have changed config_h.SH, those changes must +them up-to-date. If you have changed F, those changes must be reflected in config_H as well. (The name config_H was chosen to 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, and -plan9/config.plan9, though you should be quite careful in doing so if +F, 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 directories. =head2 make regen_perly -If perly.y has been edited, it is necessary to run this target to rebuild -perly.h, perly.act and perly.tab. In fact this target just runs the Perl -script regen_perly.pl. Note that perly.c is I rebuilt; this is just a +If F has been edited, it is necessary to run this target to rebuild +F, F and F. In fact this target just runs the Perl +script F. Note that F is I rebuilt; this is just a plain static file now. This target relies on you having Bison installed on your system. Running the target will tell you if you haven't got the right version, and if so, where to get the right one. Or if you prefer, you could hack -regen_perly.pl to work with your version of Bison. The important things +F to work with your version of Bison. The important things are that the regexes can still extract out the right chunks of the Bison -output into perly.act and perly.tab, and that the contents of those two -files, plus perly.h, are functionally equivalent to those produced by the +output into F and F, and that the contents of those two +files, plus F, are functionally equivalent to those produced by the supported version of Bison. Note that in the old days, you had to do C instead. =head2 make regen_all -This target takes care of the regen_headers, and regen_pods targets. +This target takes care of the regen_headers target. +(It used to also call the regen_pods target, but that has been eliminated.) =head2 make regen_headers @@ -532,18 +450,14 @@ 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 +=head2 globvar.sym, and perlio.sym Make sure these files are up-to-date. Read the comments in these -files and in perl_exp.SH to see what to do. +files and in F to see what to do. =head2 Binary compatibility -If you do change F or F, think carefully about +If you do change F think carefully about what you are doing. To the extent reasonable, we'd like to maintain source and binary compatibility with older releases of perl. That way, extensions built under one version of perl will continue to work with @@ -557,8 +471,8 @@ Let's not force people to keep changing it. =head2 PPPort -F needs to be synchronized to include all -new macros added to .h files (normally perl.h and XSUB.h, but others +F needs to be synchronized to include all +new macros added to .h files (normally F and F, but others as well). Since chances are that when a new macro is added the committer will forget to update F, it's the best to diff for changes in .h files when making a new release and making sure that @@ -568,25 +482,10 @@ The pumpking can delegate the synchronization responsibility to anybody else, but the release process is the only place where we can make sure that no new macros fell through the cracks. -=head2 Changes - -Be sure to update the F file. Try to include both an overall -summary as well as detailed descriptions of the changes. Your -audience will include other developers and users, so describe -user-visible changes (if any) in terms they will understand, not in -code like "initialize foo variable in bar function". - -There are differing opinions on whether the detailed descriptions -ought to go in the Changes file or whether they ought to be available -separately in the patch file (or both). There is no disagreement that -detailed descriptions ought to be easily available somewhere. - -If you update the subversion number in F, you may need -to change the version number near the top of the F file. =head2 Todo -The F file contains a roughly-categorized unordered +The F file contains a roughly-categorized unordered list of aspects of Perl that could use enhancement, features that could be added, areas that could be cleaned up, and so on. During your term as pumpkin-holder, you will probably address some of these issues, and @@ -613,28 +512,15 @@ things that need to be fixed in Configure. =head2 VMS-specific updates -The Perl revision number appears as "perl5" in configure.com. +The Perl revision number appears as "perl5" in F. It is courteous to update that if necessary. -=head2 Making the new distribution - -Suppose, for example, that you want to make version 5.004_08. Then you can -do something like the following - - mkdir ../perl5.004_08 - awk '{print $1}' MANIFEST | cpio -pdm ../perl5.004_08 - cd ../ - tar cf perl5.004_08.tar perl5.004_08 - gzip --best perl5.004_08.tar - -These steps, with extra checks, are automated by the Porting/makerel -script. =head2 Making a new patch I find the F utility quite handy for making patches. You can obtain it from any CPAN archive under -http://www.cpan.org/authors/Johan_Vromans/ . There are a couple +L. There are a couple of differences between my version and the standard one. I have mine do a @@ -928,8 +814,8 @@ conflicting needs of dynamic loading and namespace protection. For dynamic loading to work on AIX (and VMS) we need to provide a list of symbols to be exported. This is done by the script F, -which reads F and F. Thus, the C -symbol would have to be added to F So far, so good. +which reads F. Thus, the C +symbol would have to be added to F So far, so good. On the other hand, one of the goals of Perl5 is to make it easy to either extend or embed perl and link it with other libraries. This @@ -937,9 +823,9 @@ means we have to be careful to keep the visible namespace "clean". That is, we don't want perl's global variables to conflict with those in the other application library. Although this work is still in progress, the way it is currently done is via the F file. -This file is built from the F and F files, +This file is built from the F file, since those files already list the globally visible symbols. If we -had added C to global.sym, then F would contain the +had added C to F, then F would contain the line #define pause Perl_pause @@ -986,7 +872,7 @@ My explanatory comment in patch 5.003_05 said: applies to SCO. This shows the perils of having internal functions with the same name as external library functions :-). -Now, we can safely put C in F, export it, and +Now, we can safely put C in C, export it, and hide it with F. To be consistent with what I did for C, I probably should have @@ -1056,7 +942,7 @@ then in some file (e.g. F or F) do #endif Alternatively, we could just always use C everywhere and move -C from F to the end of F. That would +C from F to the end of F. That would probably be fine as long as our C function agreed with all the C function prototypes in the various systems we'll be using. As long as the prototypes in actual use don't vary that much, this is @@ -1182,7 +1068,7 @@ Given that it's already there, you can use it to override distribution modules. One way to do that is to add ccflags="$ccflags -DAPPLLIB_EXP=\"/my/override\"" - + to your config.over file. (You have to be particularly careful to get the double quotes in. APPLLIB_EXP must be a valid C string. It might actually be easier to just #define it yourself in perl.c.) @@ -1238,7 +1124,7 @@ were to install /usr/lib/libperl.so.4.5. Now, when you try to run perl5.004_04, ld.so might try to load libperl.so.4.5, since it has the right "major version" number. If this works at all, it almost certainly defeats the reason for keeping perl5.004_04 around. Worse, -with development subversions, you certaily can't guarantee that +with development subversions, you certainly can't guarantee that libperl.so.4.4 and libperl.so.4.55 will be compatible. Anyway, all this leads to quite obscure failures that are sure to drive @@ -1265,7 +1151,7 @@ Similarly nicely aligned &&s, ||s and ==s would not be respected. =head1 Upload Your Work to CPAN You can upload your work to CPAN if you have a CPAN id. Check out -http://www.cpan.org/modules/04pause.html for information on +L for information on _PAUSE_, the Perl Author's Upload Server. I typically upload both the patch file, e.g. F @@ -1438,10 +1324,6 @@ a nice malloc that is well-tuned for the system.) =over 4 -=item MacPerl - -Get some of the Macintosh stuff folded back into the main distribution. - =item gconvert replacement Maybe include a replacement function that doesn't lose data in rare @@ -1555,5 +1437,4 @@ All opinions expressed herein are those of the authorZ<>(s). =head1 LAST MODIFIED -27-04-2007 H.Merijn Brand -$Id: pumpkin.pod,v 1.23 2000/01/13 19:45:13 doughera Released $ +2009-07-08-01 Jesse Vincent