X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/ebb9925428467601f365b797b9f30a0507ef87e1..1e436e33038f3b8b5c79a2e5c8edab3894665709:/Porting/pumpkin.pod diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index f62f753..7253fe7 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 @@ -8,8 +8,8 @@ There is no simple synopsis, yet. =head1 DESCRIPTION -This document attempts to begin to describe some of the -considerations involved in patching and maintaining perl. +This document attempts to begin to describe some of the considerations +involved in patching, porting, and maintaining perl. This document is still under construction, and still subject to significant changes. Still, I hope parts of it will be useful, @@ -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 +L , which automatically points you to a mirror site "close" to you. =head2 Perl5-porters mailing list @@ -43,97 +43,72 @@ 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? -Perl version numbers are floating point numbers, such as 5.004. -(Observations about the imprecision of floating point numbers for -representing reality probably have more relevance than you might -imagine :-) The major version number is 5 and the '004' is the -patchlevel. (Questions such as whether or not '004' is really a minor -version number can safely be ignored.:) +Beginning with v5.6.0, even versions will stand for maintenance releases +and odd versions for development releases, i.e., v5.6.x for maintenance +releases, and v5.7.x for development releases. Before v5.6.0, subversions +_01 through _49 were reserved for bug-fix maintenance releases, and +subversions _50 through _99 for unstable development versions. -The version number is available as the magic variable $], -and can be used in comparisons, e.g. +For example, in v5.6.1, the revision number is 5, the version is 6, +and 1 is the subversion. - print "You've got an old perl\n" if $] < 5.002; +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/100000>. This +can still be used in comparisons. -You can also require particular version (or later) with + print "You've got an old perl\n" if $] < 5.005_03; - use 5.002; +In addition, the version is also available as a string in $^V. -At some point in the future, we may need to decide what to call the -next big revision. In the .package file used by metaconfig to -generate Configure, there are two variables that might be relevant: -$baserev=5.0 and $package=perl5. At various times, I have suggested -we might change them to $baserev=5.1 and $package=perl5.1 if want -to signify a fairly major update. Or, we might want to jump to perl6. -Let's worry about that problem when we get there. + print "You've got a new perl\n" if $^V and $^V ge v5.6.0; -=head2 Subversions +You can also require particular version (or later) with: -In addition, there may be "developer" sub-versions available. These -are not official releases. They may contain unstable experimental -features, and are subject to rapid change. Such developer -sub-versions are numbered with sub-version numbers. For example, -version 5.003_04 is the 4'th developer version built on top of -5.003. It might include the _01, _02, and _03 changes, but it -also might not. Sub-versions are allowed to be subversive. (But see -the next section for recent changes.) + use 5.006; -These sub-versions can also be used as floating point numbers, so -you can do things such as +or using the new syntax available only from v5.6 onward: - print "You've got an unstable perl\n" if $] == 5.00303; + use v5.6.0; -You can also require particular version (or later) with - - use 5.003_03; # the "_" is optional +At some point in the future, we may need to decide what to call the +next big revision. In the .package file used by metaconfig to +generate Configure, there are two variables that might be relevant: +$baserev=5 and $package=perl5. -Sub-versions produced by the members of perl5-porters are usually -available on CPAN in the F directory. +Perl releases produced by the members of perl5-porters are usually +available on CPAN in the F and F +directories. =head2 Maintenance and Development Subversions -As an experiment, starting with version 5.004, subversions _01 through -_49 will be reserved for bug-fix maintenance releases, and subversions -_50 through _99 will be available for unstable development versions. - -The separate bug-fix track is being established to allow us an easy -way to distribute important bug fixes without waiting for the -developers to untangle all the other problems in the current -developer's release. +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. - -Watch for announcements of maintenance subversions in -comp.lang.perl.announce. +patch' entry in F. The distribution file contains the +string C to make clear that the file is not meant for +public consumption. -The first rule of maintenance work is "First, do no harm." +In general, the names of official distribution files for the public +always match the regular expression: -=head2 Why such a complicated scheme? + ^perl\d+\.(\d+)\.\d+(-MAINT_TRIAL_\d+)\.tar\.gz$ -Two reasons, really. At least. +C<$1> in the pattern is always an even number for maintenance +versions, and odd for developer releases. -First, we need some way to identify and release collections of patches -that are known to have new features that need testing and exploration. The -subversion scheme does that nicely while fitting into the -C mold. - -Second, since most of the folks who help maintain perl do so on a -free-time voluntary basis, perl development does not proceed at a -precise pace, though it always seems to be moving ahead quickly. -We needed some way to pass around the "patch pumpkin" to allow -different people chances to work on different aspects of the -distribution without getting in each other's way. It wouldn't be -constructive to have multiple people working on incompatible -implementations of the same idea. Instead what was needed was -some kind of "baton" or "token" to pass around so everyone knew -whose turn was next. +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 +provide the trees of symlinks and the like. They will have to know +I what you decide. =head2 Why is it called the patch pumpkin? @@ -155,7 +130,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 +149,19 @@ 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. +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). + =head2 Seek consensus on major changes If you are making big changes, don't do it in secret. Discuss the @@ -196,6 +184,92 @@ 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 + +=over 4 + +=item source code + +If you have many machine-specific #defines or #includes, consider +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. + +If your system supports dynamic loading but none of the existing +methods at F work for you, you must write +a new one. Study the existing ones to see what kind of interface +you must supply. + +=item build 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 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. + +=item build and installation Makefiles, scripts, and so forth + +Sometimes you will also need to tweak the Perl build and installation +procedure itself, like for example F and F. +Tread very carefully, even more than usual. Contain your changes +with utmost care. + +=item test suite + +Many 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 (preferably not) or customize (preferable) the tests for your +platform. + +=item modules + +Certain standard modules may need updating if your operating system +sports for example a native filesystem naming. You may want to update +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 +F script for checking this. + +=item documentation + +If your operating system comes from outside UNIX you almost certainly +will have differences in the available operating system functionality +(missing system calls, different semantics, whatever). Please +document these at F. If your operating system is +the first B to have a system call also update the list of +"portability-bewares" at the beginning of F. + +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. 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, +documentation, whatever. Please name these along the lines of +FI.pod. [unfinished: where to put this file (the pod/ +subdirectory, of course: but more importantly, which/what index files +should be updated?)] + +=back + =head2 Allow for lots of testing We should never release a main version without testing it as a @@ -211,19 +285,23 @@ that some of those things will be just plain broken and need to be fixed, but, in general, we ought to try to avoid breaking widely-installed things. -=head2 Automate generation of derivative files +=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. 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. + +Also F is automatically produced from F. +In general, look out for all F<*.SH> files. Finally, the sample files in the F subdirectory are generated automatically by the script F included @@ -232,81 +310,39 @@ 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. - -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. +This section has now been expanded and moved into its own file, +F. -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. +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 If you need to make changes to Configure or config_h.SH, it may be best to change the appropriate metaconfig units instead, and regenerate Configure. - metaconfig -m + mconfig -m -O -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. 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 -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 -pointer to the current version. - -Alternatively, do consider if the F<*ish.h> files might be a better -place for your changes. - -=head2 MANIFEST +that comes with Perl's metaconfig units. See the head of Configure for the +recent information on how to obtain the units and the tools. The base boils +down to -Make sure the MANIFEST is up-to-date. You can use dist's B -program for this. You can also use +` git clone github.com:perl5-metaconfig/metaconfig metaconfig - perl -w -MExtUtils::Manifest=fullcheck -e fullcheck +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. -Both commands will also list extra files in the directory that are not -listed in MANIFEST. +Alternatively, do consider if the F<*ish.h> files or the hint files might +be a better place for your changes. -The MANIFEST is normally sorted. +=head2 MANIFEST If you are using metaconfig to regenerate Configure, then you should note that metaconfig actually uses MANIFEST.new, so you want to be sure @@ -314,42 +350,6 @@ 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 @@ -376,66 +376,50 @@ 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.) +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, vms/config.vms and -plan9/config.plan9, though you should be quite careful in doing so if +It may also be necessary to update win32/config.?c, and +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 run_byacc +=head2 make regen_perly -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 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. -If C changes, make sure you run C to -update the corresponding VMS files. See L. +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 +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 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. -Some additional notes from Larry on this: +Note that in the old days, you had to do C instead. -Don't forget to regenerate perly_c.diff. +=head2 make regen_all - byacc -d perly.y - mv y.tab.c perly.c - patch perly.c perly_c.diff - -One chunk of lines that often fails begins with - - #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 +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 @@ -462,16 +446,16 @@ and effort by manually running C myself rather than answering all the questions and complaints about the failing command. -=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 -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. @@ -481,34 +465,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 + +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 +F contains them all. -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". +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. -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. =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 @@ -523,32 +508,15 @@ 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. - -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". - -=head2 Making the new distribution +The Perl revision number appears as "perl5" in F. +It is courteous to update that if necessary. -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.perl.com/CPAN/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 @@ -631,41 +599,57 @@ 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 Common Gotcha's +=head2 Other tests =over 4 -=item #elif +=item gcc -ansi -pedantic -The '#elif' preprocessor directive is not understood on all systems. -Specifically, I know that Pyramids don't understand it. Thus instead of the -simple +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__). - #if defined(I_FOO) - # include - #elif defined(I_BAR) - # include - #else - # include - #endif +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. -You have to do the more Byzantine +The -ansi and -pedantic are useful in catching at least the following +nonportable practices: - #if defined(I_FOO) - # include - #else - # if defined(I_BAR) - # include - # else - # include - # endif - #endif +=over 4 + +=item * + +gcc-specific extensions -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 * + +lvalue casts + +=item * + +// C++ comments + +=item * + +enum trailing commas + +=back + +The -Dgccansipedantic should be used only when cleaning up the code, +not for production builds, since otherwise gcc cannot inline certain +things. + +=back + +=head1 Common Gotchas + +=over 4 =item Probably Prefer POSIX @@ -790,8 +774,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 @@ -799,9 +783,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 @@ -835,20 +819,20 @@ The "fix" is to give the function a different name. The one implemented in 5.003_05 isn't optimal, but here's what was done: #ifdef HAS_CHSIZE - # ifdef my_chsize /* Probably #defined to Perl_my_chsize in embed.h */ - # undef my_chsize + # ifdef my_chsize /* Probably #defined to Perl_my_chsize */ + # undef my_chsize /* in embed.h */ # endif # define my_chsize chsize #endif My explanatory comment in patch 5.003_05 said: - Undef and then re-define my_chsize from Perl_my_chsize to - just plain chsize if this system HAS_CHSIZE. This probably only - applies to SCO. This shows the perils of having internal - functions with the same name as external library functions :-). + Undef and then re-define my_chsize from Perl_my_chsize to + just plain chsize if this system HAS_CHSIZE. This probably only + 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 @@ -918,7 +902,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 @@ -969,7 +953,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 @@ -1011,33 +995,6 @@ may find metaconfig's units clumsy to work with. =back -=head2 @INC search order - -By default, the list of perl library directories in @INC is the -following: - - $archlib - $privlib - $sitearch - $sitelib - -Specifically, on my Solaris/x86 system, I run -B and I have the following -directories: - - /opt/perl/lib/i86pc-solaris/5.00307 - /opt/perl/lib - /opt/perl/lib/site_perl/i86pc-solaris - /opt/perl/lib/site_perl - -That is, perl's directories come first, followed by the site-specific -directories. - -The site libraries come second to support the usage of extensions -across perl versions. Read the relevant section in F for -more information. If we ever make $sitearch version-specific, this -topic could be revisited. - =head2 Why isn't there a directory to override Perl's library? Mainly because no one's gotten around to making one. Note that @@ -1056,23 +1013,30 @@ documented in config_h.SH). Here's what APPLLIB_EXP is for, from a mail message from Larry: The main intent of APPLLIB_EXP is for folks who want to send out a - version of Perl embedded in their product. They would set the symbol - to be the name of the library containing the files needed to run or to - support their particular application. This works at the "override" - level to make sure they get their own versions of any library code that - they absolutely must have configuration control over. + version of Perl embedded in their product. They would set the + symbol to be the name of the library containing the files needed + to run or to support their particular application. This works at + the "override" level to make sure they get their own versions of + any library code that they absolutely must have configuration + control over. As such, I don't see any conflict with a sysadmin using it for a - override-ish sort of thing, when installing a generic Perl. It should - probably have been named something to do with overriding though. Since - it's undocumented we could still change it... :-) + override-ish sort of thing, when installing a generic Perl. It + should 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\"" -then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB. +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. Perl will +also search architecture-specific and version-specific subdirectories of +APPLLIB_EXP. =head2 Shared libperl.so location @@ -1121,7 +1085,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 @@ -1130,10 +1094,25 @@ 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 -http://www.perl.com/CPAN/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 @@ -1141,15 +1120,11 @@ 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 L ). =head1 Help Save the World You should definitely announce your patch on the perl5-porters list. -You should also consider announcing your patch on -comp.lang.perl.announce, though you should make it quite clear that a -subversion is not a production release, and be prepared to deal with -people who will not read your disclaimer. =head1 Todo @@ -1157,21 +1132,100 @@ 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 Good ideas waiting for round tuits +=head2 Adding missing library functions to Perl -=over 4 +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 */ -=item installprefix + /* VOS doesn't supply a truncate function, so we build one up + from the available POSIX functions. */ -I think we ought to support + #include + #include + #include - Configure -Dinstallprefix=/blah/blah + 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; + } -Currently, we support B<-Dprefix=/blah/blah>, but the changing the install -location has to be handled by something like the F trick -described in F. AFS users also are treated specially. -We should probably duplicate the metaconfig prefix stuff for an -install prefix. +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 =item Configure -Dsrc=/blah/blah @@ -1191,47 +1245,6 @@ Configure so that most of them aren't needed. Some of the hint file information (particularly dynamic loading stuff) ought to be fed back into the main metaconfig distribution. -=item Catch GNU Libc "Stub" functions - -Some functions (such as lchown()) are present in libc, but are -unimplmented. That is, they always fail and set errno=ENOSYS. - -Thomas Bushnell provided the following sample code and the explanation -that follows: - - /* System header to define __stub macros and hopefully few prototypes, - which can conflict with char FOO(); below. */ - #include - /* Override any gcc2 internal prototype to avoid an error. */ - /* We use char because int might match the return type of a gcc2 - builtin and then its argument prototype would still apply. */ - char FOO(); - - int main() { - - /* The GNU C library defines this for functions which it implements - to always fail with ENOSYS. Some functions are actually named - something starting with __ and the normal name is an alias. */ - #if defined (__stub_FOO) || defined (__stub___FOO) - choke me - #else - FOO(); - #endif - - ; return 0; } - -The choice of is essentially arbitrary. The GNU libc -macros are found in . You can include that file instead -of (which itself includes ) if you test for -its existence first. is assumed to exist on every system, -which is why it's used here. Any GNU libc header file will include -the stubs macros. If either __stub_NAME or __stub___NAME is defined, -then the function doesn't actually exist. Tests using work -on every system around. - -The declaration of FOO is there to override builtin prototypes for -ANSI C functions. - =back =head2 Probably good ideas waiting for round tuits @@ -1244,12 +1257,6 @@ I've received sensible suggestions for --exec_prefix and other GNU configure --options. It's not always obvious exactly what is intended, but this merits investigation. -=item make clean - -Currently, B isn't all that useful, though -B and B are. This needs a bit of -thought and documentation before it gets cleaned up. - =item Try gcc if cc fails Currently, we just give up. @@ -1268,10 +1275,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 @@ -1299,18 +1302,90 @@ 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 + +=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], *.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 . -Additions by Chip Salzenberg chip@perl.com and -Tim Bunce Tim.Bunce@ig.co.uk . +Original author: Andy Dougherty doughera@lafayette.edu . +Additions by Chip Salzenberg chip@perl.com, Tim Bunce and the perl5 +development team. All opinions expressed herein are those of the authorZ<>(s). =head1 LAST MODIFIED -$Id: pumpkin.pod,v 1.22 1998/07/22 16:33:55 doughera Released $ +2017-10-13 H.Merijn Brand