=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.
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:
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
=head1 LAST MODIFIED
-$Id: pumpkin.pod,v 1.17 1998/06/30 17:00:06 doughera Released $
+$Id: pumpkin.pod,v 1.22 1998/07/22 16:33:55 doughera Released $