X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=Porting%2Fpumpkin.pod;h=9dc3ed1b1d23e8d9e38377387b5dfe05918db586;hb=a725df954c99dfa9de8864cdcc07f04fd5445563;hp=1749b22e4b2913467dd9bd180c17f12187a4545d;hpb=05ff1fbb4c37d896ff839b1d2d6c6650cdafae98;p=p5sagit%2Fp5-mst-13.2.git diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index 1749b22..9dc3ed1 100644 --- a/Porting/pumpkin.pod +++ b/Porting/pumpkin.pod @@ -1,6 +1,6 @@ =head1 NAME -Pumpkin - Notes on handling the Perl Patch Pumpkin +Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl =head1 SYNOPSIS @@ -43,7 +43,7 @@ to perl5-porters-request@perl.org . Archives of the list are held at: - http://www.rosat.mpe-garching.mpg.de/mailing-lists/perl-porters/ + http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ =head1 How are Perl Releases Numbered? @@ -103,7 +103,7 @@ always match the regular expression: C<$1> in the pattern is always an even number for maintenance versions, and odd for developer releases. -In the past it has been observed that pumkings tend to invent new +In the past it has been observed that pumpkings tend to invent new naming conventions on the fly. If you are a pumpking, before you invent a new name for any of the three types of perl distributions, please inform the guys from the CPAN who are doing indexing and @@ -159,6 +159,8 @@ 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. +In a similar vein, do not create files or directories which differ only +in case (upper versus lower). =head2 Seek consensus on major changes @@ -307,51 +309,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 direclty +eleate to building a release any more, but still contain what might be +useful information - DAPM 7/2009. =head2 run metaconfig @@ -362,72 +325,34 @@ change the appropriate metaconfig units instead, and regenerate Configure. will regenerate Configure and config_h.SH. Much more information 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.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 +that comes with Perl's metaconfig units. + +Since metaconfig is hard to change, running correction scripts after +this generation is sometimes needed. Configure gained complexity over +time, and the order in which config_h.SH is generated can cause havoc +when compiling perl. Therefor, you need to run Porting/config_h.pl +after that generation. All that and more is described in the README +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/ . +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 pointer to the current version. -Alternatively, do consider if the F<*ish.h> files might be a better -place for your changes. +Alternatively, do consider if the F<*ish.h> files or the hint files might be +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 - perly.fixer - 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 @@ -454,7 +379,7 @@ This is to ease maintenance. When Configure gets updated, the parts sometimes get scrambled around, and the changes in config_H can 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 propoagate them to a canned 'config.h' by any +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 @@ -476,53 +401,28 @@ 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 run_byacc - -If you have byacc-1.8.2 (available from CPAN), and if there have been -changes to F, you can regenerate the F file. The -run_byacc makefile target does this by running byacc and then applying -some patches so that byacc dynamically allocates space, rather than -having fixed limits. This patch is handled by the F -script. Depending on the nature of the changes to F, you may -or may not have to hand-edit the patch to apply correctly. If you do, -you should include the edited patch in the new distribution. If you -have byacc-1.9, the patch won't apply cleanly. Changes to the printf -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 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: - -Don't forget to regenerate perly_c.diff. +=head2 make regen_perly - byacc -d perly.y - mv y.tab.c perly.c - patch perly.c perly_c.diff +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 +plain static file now. -One chunk of lines that often fails begins with +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 +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 +supported version of Bison. - #line 29 "perly.y" - -and ends one line before - - #define YYERRCODE 256 - -This only happens when you add or remove a token type. I suppose this -could be automated, but it doesn't happen very often nowadays. - -Larry +Note that in the old days, you had to do C instead. =head2 make regen_all -This target takes care of the PERLYVMS, 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 @@ -549,10 +449,6 @@ 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 @@ -572,37 +468,35 @@ about them first. If possible, we should provide backwards-compatibility stubs. There's a lot of XS code out there. Let's not force people to keep changing it. -=head2 Changes +=head2 PPPort -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". +F needs to be synchronized to include all +new macros added to .h files (normally perl.h and XSUB.h, 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 +F contains them all. -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. +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. -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-catgorized 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 -perhaps identify others which, while you decide not to address them -this time around, may be tackled in the future. Update the file -reflect the situation as it stands when you hand over the pumpkin. +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 +perhaps identify others which, while you decide not to address them this +time around, may be tackled in the future. Update the file to reflect +the situation as it stands when you hand over the pumpkin. You might like, early in your pumpkin-holding career, to see if you -can find champions for partiticular issues on the to-do list: an issue +can find champions for particular issues on the to-do list: an issue owned is an issue more likely to be resolved. -There are also some more porting-specific L items later in this +There are also some more porting-specific L items later in this file. =head2 OS/2-specific updates @@ -617,26 +511,9 @@ 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, or -by running `make regen_all` which will run that script for you. - The Perl revision number appears as "perl5" in configure.com. 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 @@ -729,45 +606,47 @@ branches. =over 4 -=item CHECK_FORMAT +=item gcc -ansi -pedantic + +Configure -Dgccansipedantic [ -Dcc=gcc ] will enable (via the cflags script, +not $Config{ccflags}) the gcc strict ANSI C flags -ansi and -pedantic for +the compilation of the core files on platforms where it knows it can +do so (like Linux, see cflags.SH for the full list), and on some +platforms only one (Solaris can do only -pedantic, not -ansi). +The flag -DPERL_GCC_PEDANTIC also gets added, since gcc does not add +any internal cpp flag to signify that -pedantic is being used, as it +does for -ansi (__STRICT_ANSI__). -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. +Note that the -ansi and -pedantic are enabled only for version 3 (and +later) of gcc, since even gcc version 2.95.4 finds lots of seemingly +false "value computed not used" errors from Perl. -A more accurate approach is the following commands: +The -ansi and -pedantic are useful in catching at least the following +nonportable practices: =over 4 =item * -build miniperl with -DCHECK_FORMAT - - make clean - make miniperl OPTIMIZE=-DCHECK_FORMAT >& mini.log +gcc-specific extensions =item * -build a clean miniperl, -and build everything else from that with -DCHECK_FORMAT +lvalue casts - make clean - make miniperl - make all OPTIMIZE=-DCHECK_FORMAT >& make.log - =item * -clean up, and print warnings from the log files +// C++ comments - make clean - perl -nwe 'print if /^\S+:/ and not /^make\b/' \ - mini.log make.log +=item * + +enum trailing commas =back -(-Wformat support by Robin Barker.) +The -Dgccansipedantic should be used only when cleaning up the code, +not for production builds, since otherwise gcc cannot inline certain +things. =back @@ -807,42 +686,10 @@ The only currently known leaks happen when there are compile-time errors within eval or require. (Fixing these is non-trivial, unfortunately, but they must be fixed eventually.) -=head1 Common Gotcha's +=head1 Common Gotchas =over 4 -=item #elif - -The '#elif' preprocessor directive is not understood on all systems. -Specifically, I know that Pyramids don't understand it. Thus instead of the -simple - - #if defined(I_FOO) - # include - #elif defined(I_BAR) - # include - #else - # include - #endif - -You have to do the more Byzantine - - #if defined(I_FOO) - # include - #else - # if defined(I_BAR) - # include - # else - # include - # endif - #endif - -Incidentally, whitespace between the leading '#' and the preprocessor -command is not guaranteed, but is very portable and you may use it freely. -I think it makes things a bit more readable, especially once things get -rather deeply nested. I also think that things should almost never get -too deeply nested, so it ought to be a moot point :-) - =item Probably Prefer POSIX It's often the case that you'll need to choose whether to do @@ -1216,12 +1063,18 @@ a mail message from Larry: probably have been named something to do with overriding though. Since it's undocumented we could still change it... :-) -Given that it's already there, you can use it to override -distribution modules. If you do +Given that it's already there, you can use it to override distribution modules. +One way to do that is to add - sh Configure -Dccflags='-DAPPLLIB_EXP=/my/override' + 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.) -then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB. +Then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB. Perl will +also search architecture-specific and version-specific subdirectories of +APPLLIB_EXP. =head2 Shared libperl.so location @@ -1279,6 +1132,21 @@ reflection, I'd say leave libperl.so in $archlib. =back +=head2 Indentation style + +Over the years Perl has become a mishmash of +various indentation styles, but the original "Larry style" can +probably be restored with (GNU) indent somewhat like this: + + indent -kr -nce -psl -sc + +A more ambitious solution would also specify a list of Perl specific +types with -TSV -TAV -THV .. -TMAGIC -TPerlIO ... but that list would +be quite ungainly. Also note that GNU indent also doesn't do aligning +of consecutive assignments, which would truly wreck the layout in +places like sv.c:Perl_sv_upgrade() or sv.c:Perl_clone_using(). +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 @@ -1306,6 +1174,97 @@ Here, in no particular order, are some Configure and build-related items that merit consideration. This list isn't exhaustive, it's just what I came up with off the top of my head. +=head2 Adding missing library functions to Perl + +The perl Configure script automatically determines which headers and +functions you have available on your system and arranges for them to be +included in the compilation and linking process. Occasionally, when porting +perl to an operating system for the first time, you may find that the +operating system is missing a key function. While perl may still build +without this function, no perl program will be able to reference the missing +function. You may be able to write the missing function yourself, or you +may be able to find the missing function in the distribution files for +another software package. In this case, you need to instruct the perl +configure-and-build process to use your function. Perform these steps. + +=over 3 + +=item * + +Code and test the function you wish to add. Test it carefully; you will +have a much easier time debugging your code independently than when it is a +part of perl. + +=item * + +Here is an implementation of the POSIX truncate function for an operating +system (VOS) that does not supply one, but which does supply the ftruncate() +function. + + /* Beginning of modification history */ + /* Written 02-01-02 by Nick Ing-Simmons (nick@ing-simmons.net) */ + /* End of modification history */ + + /* VOS doesn't supply a truncate function, so we build one up + from the available POSIX functions. */ + + #include + #include + #include + + int + truncate(const char *path, off_t len) + { + int fd = open(path,O_WRONLY); + int code = -1; + if (fd >= 0) { + code = ftruncate(fd,len); + close(fd); + } + return code; + } + +Place this file into a subdirectory that has the same name as the operating +system. This file is named perl/vos/vos.c + +=item * + +If your operating system has a hints file (in perl/hints/XXX.sh for an +operating system named XXX), then start with it. If your operating system +has no hints file, then create one. You can use a hints file for a similar +operating system, if one exists, as a template. + +=item * + +Add lines like the following to your hints file. The first line +(d_truncate="define") instructs Configure that the truncate() function +exists. The second line (archobjs="vos.o") instructs the makefiles that the +perl executable depends on the existence of a file named "vos.o". (Make +will automatically look for "vos.c" and compile it with the same options as +the perl source code). The final line ("test -h...") adds a symbolic link +to the top-level directory so that make can find vos.c. Of course, you +should use your own operating system name for the source file of extensions, +not "vos.c". + + # VOS does not have truncate() but we supply one in vos.c + d_truncate="define" + archobjs="vos.o" + + # Help gmake find vos.c + test -h vos.c || ln -s vos/vos.c vos.c + +The hints file is a series of shell commands that are run in the top-level +directory (the "perl" directory). Thus, these commands are simply executed +by Configure at an appropriate place during its execution. + +=item * + +At this point, you can run the Configure script and rebuild perl. Carefully +test the newly-built perl to ensure that normal paths, and error paths, +behave as you expect. + +=back + =head2 Good ideas waiting for round tuits =over 4 @@ -1364,10 +1323,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 @@ -1400,9 +1355,80 @@ in recent config.sh files though. =back +=head2 Copyright Issues + +The following is based on the consensus of a couple of IPR lawyers, +but it is of course not a legally binding statement, just a common +sense summary. + +=over 4 + +=item * + +Tacking on copyright statements is unnecessary to begin with because +of the Berne convention. But assuming you want to go ahead... + +=item * + +The right form of a copyright statement is + + Copyright (C) Year, Year, ... by Someone + +The (C) is not required everywhere but it doesn't hurt and in certain +jurisdictions it is required, so let's leave it in. (Yes, it's true +that in some jurisdictions the "(C)" is not legally binding, one should +use the true ringed-C. But we don't have that character available for +Perl's source code.) + +The years must be listed out separately. Year-Year is not correct. +Only the years when the piece has changed 'significantly' may be added. + +=item * + +One cannot give away one's copyright trivially. One can give one's +copyright away by using public domain, but even that requires a little +bit more than just saying 'this is in public domain'. (What it +exactly requires depends on your jurisdiction.) But barring public +domain, one cannot "transfer" one's copyright to another person or +entity. In the context of software, it means that contributors cannot +give away their copyright or "transfer" it to the "owner" of the software. + +Also remember that in many cases if you are employed by someone, +your work may be copyrighted to your employer, even when you are +contributing on your own time (this all depends on too many things +to list here). But the bottom line is that you definitely can't give +away a copyright you may not even have. + +What is possible, however, is that the software can simply state + + Copyright (C) Year, Year, ... by Someone and others + +and then list the "others" somewhere in the distribution. +And this is exactly what Perl does. (The "somewhere" is +AUTHORS and the Changes* files.) + +=item * + +Split files, merged files, and generated files are problematic. +The rule of thumb: in split files, copy the copyright years of +the original file to all the new files; in merged files make +an union of the copyright years of all the old files; in generated +files propagate the copyright years of the generating file(s). + +=item * + +The files of Perl source code distribution do carry a lot of +copyrights, by various people. (There are many copyrights embedded in +perl.c, for example.) The most straightforward thing for pumpkings to +do is to simply update Larry's copyrights at the beginning of the +*.[hcy], x2p/*.[hcy], *.pl, and README files, and leave all other +copyrights alone. Doing more than that requires quite a bit of tracking. + +=back + =head1 AUTHORS -Original author: Andy Dougherty doughera@lafcol.lafayette.edu . +Original author: Andy Dougherty doughera@lafayette.edu . Additions by Chip Salzenberg chip@perl.com and Tim Bunce Tim.Bunce@ig.co.uk . @@ -1410,4 +1436,4 @@ All opinions expressed herein are those of the authorZ<>(s). =head1 LAST MODIFIED -$Id: pumpkin.pod,v 1.23 2000/01/13 19:45:13 doughera Released $ +2009-07-08-01 Jesse Vincent