=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,
=head2 Subversions
-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.)
+In addition, there usually are sub-versions available. 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.)
These sub-versions can also be used as floating point numbers, so
you can do things such as
use 5.003_03; # the "_" is optional
Sub-versions produced by the members of perl5-porters are usually
-available on CPAN in the F<src/5.0/unsupported> directory.
+available on CPAN in the F<src/5.0/maint> and F<src/5.0/devel>
+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.
+Starting with version 5.004, subversions _01 through _49 is reserved
+for bug-fix maintenance releases, and subversions _50 through _99 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.
+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.
+patch' entry in patchlevel.h. The distribution file contains the
+string C<MAINT_TRIAL> to make clear that the file is not meant for
+public consumption.
+
+In general, the names of official distribution files for the public
+always match the regular expression
+
+ ^perl5\.\d{3}(_[0-4]\d)?\.tar\.gz$
+
+Developer releases always match
+
+ ^perl5\.\d{3}(_[5-9]\d)?\.tar\.gz$
-Watch for announcements of maintenance subversions in
-comp.lang.perl.announce.
+And the trial versions for a new maintainance release match
+
+ ^perl5\.\d{3}(_[0-4]\d)-MAINT_TRIAL_\d+\.tar\.gz$
+
+In the past it has been observed that pumkings 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<in advance> what you decide.
=head2 Why such a complicated scheme?
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.
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.
+
=head2 Seek consensus on major changes
If you are making big changes, don't do it in secret. Discuss the
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" (os2ish.h, vmsish.h, and so on) and including
+that in perl.h. 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<MANIFEST> when you add files.
+
+If your system support dynamic loading but none of the existing
+methods at F<ext/DynaLoader/dl_*.xs> 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<hints> subdirectory, the latter
+in C<ext/*/hints> 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 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<Makefile.SH> and F<installperl>.
+Tread very carefully, even more than usual. Contain your changes
+with utmost care.
+
+=item test suite
+
+Many of the tests in C<t> 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<Config> module (which contains the results of the
+Configure run, in effect the C<config.sh> 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.
+
+=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<pod/perlport.pod>. If your operating system is
+the first B<not> to have a system call also update the list of
+"portability-bewares" at the beginning of F<pod/perlfunc.pod>.
+
+A file called F<README.youros> 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.
+
+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
+F<perl>I<youros>.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
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<embed.h>, F<keywords.h>, F<opcode.h>, and F<perltoc.pod> files
are all automatically generated by perl scripts. In general, don't
F<Configure> and F<config_h.SH> are also automatically generated by
B<metaconfig>. In general, you should patch the metaconfig units
-instead of patching these files directly. However, very minor changes to
-F<Configure> 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<Configure> 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<Makefile> is automatically produced from F<Makefile.SH>.
+In general, look out for all F<*.SH> files.
+
+Finally, the sample files in the F<Porting/> subdirectory are
+generated automatically by the script F<U/mksample> included
+with the metaconfig units. See L<"run metaconfig"> below for
+information on obtaining the metaconfig units.
=head1 How to Make a Distribution
metaconfig -m
-will regenerate Configure and config_h.SH. More information on
-obtaining and running metaconfig is in the F<U/README> file that comes
-with Perl's metaconfig units. Perl's metaconfig units should be
-available the same place you found this file. On CPAN, look under my
-directory F<authors/id/ANDYD/> for a file such as F<5.003_07-02.U.tar.gz>.
-That file should be unpacked in your main perl source directory. It
-contains the files needed to run B<metaconfig> to reproduce Perl's
-Configure script. (Those units are for 5.003_07. There have been
-changes since then; please contact me if you want more recent
-versions, and I will try to point you in the right direction.)
+will regenerate Configure and config_h.SH. Much more information
+on obtaining and running metaconfig is in the F<U/README> 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<mc_units-5.005_00-01.tar.gz> 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.
Both commands will also list extra files in the directory that are not
listed in MANIFEST.
-The MANIFEST is normally sorted, with one exception. Perl includes
-both a F<Configure> script and a F<configure> script. The
-F<configure> script is a front-end to the main F<Configure>, but
-is there to aid folks who use autoconf-generated F<configure> files
-for other software. The problem is that F<Configure> and F<configure>
-are the same on case-insensitive file systems, so I deliberately put
-F<configure> first in the MANIFEST so that the extraction of
-F<Configure> will overwrite F<configure> and leave you with the
-correct script. (The F<configure> script must also have write
-permission for this to work, so it's the only file in the distribution
-I normally have with write permission.)
+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
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. Probably, the F<t/TEST> script should check for this
-and do the chmod if needed, but it doesn't currently.
+prefer to avoid. The F<t/TEST> 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
+ configure.gnu
embed.pl
installperl
installman
*.SH
vms/ext/Stdio/test.pl
vms/ext/filespec.t
- vms/fndvers.com
x2p/*.SH
Other things ought to be readable, at least :-).
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 vms/config.vms and
+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
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
started to fix F<perly.fixer> to detect this, but I never completed the
task.
+If C<perly.c> changes, make sure you run C<perl vms/vms_yfix.pl> to
+update the corresponding VMS files. See L<VMS-specific updates>.
+
Some additional notes from Larry on this:
-Don't forget to regenerate perly.c.diff.
+Don't forget to regenerate perly_c.diff.
byacc -d perly.y
mv y.tab.c perly.c
- patch perly.c <perly.c.diff
+ patch perly.c <perly_c.diff
# manually apply any failed hunks
- diff -c2 perly.c.orig perly.c >perly.c.diff
+ diff -c2 perly.c.orig perly.c >perly_c.diff
One chunk of lines that often fails begins with
=head2 VMS-specific updates
-If you have changed F<perly.y>, then you may want to update
-F<vms/perly_{h,c}.vms> by running C<perl vms/vms_yfix.pl>.
+If you have changed F<perly.y> or F<perly.c>, then you most probably want
+to update F<vms/perly_{h,c}.vms> by running C<perl vms/vms_yfix.pl>.
The Perl version number appears in several places under F<vms>.
It is courteous to update these versions. For example, if you are
back into the main distribution, but various parts of the perl
Configure/build/install process still assume src='.'.
+=item Directory for vendor-supplied modules?
+
+If a vendor supplies perl, but wants to leave $siteperl and $sitearch
+for the local user to use, where should the vendor put vendor-supplied
+modules (such as Tk.so)? If the vendor puts them in the default $archlib,
+then they need to be updated each time the perl version is updated.
+Perhaps we need a set of libries $vendorlib and $vendorarch that
+track $apiversion (like the $sitexxx directories do) rather than just
+$version (like the main perl directory).
+
+An alternative (and perhaps even better) plan might be for the vendor
+to select non-default $privlib and $archlib directories, perhaps using
+$apiversion instead of $version (or even just /usr/lib/perl5 with no
+version stuff at all), and put modules into those directories (with perl
+Makefile.PL INSTALLDIRS=perl). This would be fine unless the vendor
+wanted to support different versions of perl installed at the same time.
+(How many vendors *really* want to do that?)
+
+=item Separate directories for Perl-supplied and add-on man pages
+
+Man pages supplied with the perl distribution proper ought to go in
+an appropriate man directory. Perhaps man pages supplied with add-on
+modules ought to (at least optionally) go into a $siteman[1-9] directory.
+For example, suppose that $privlib is /usr/lib/perl5 and $man1dir
+is /usr/man/man1. Also, suppose $sitelib is /usr/local/lib/perl5.
+In this situation, it might make sense for man pages to go into
+/usr/local/lib/man/man1.
+
=item Hint file fixes
Various hint files work around Configure problems. We ought to fix
=head1 LAST MODIFIED
-$Id: pumpkin.pod,v 1.15 1998/04/23 17:03:48 doughera Released $
+$Id: pumpkin.pod,v 1.22 1998/07/22 16:33:55 doughera Released $