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.cpan.org/README.html , which automatically points you to a
+L<http://www.cpan.org/README.html> , which automatically points you to a
mirror site "close" to you.
=head2 Perl5-porters mailing list
subscribe. The list is high volume, but generally has a
fairly low noise level.
-Subscribe by sending the message (in the body of your letter)
+To subscribe to perl5-porters, send an email to
- subscribe perl5-porters
-
-to perl5-porters-request@perl.org .
+ perl5-porters-subscribe@perl.org
Archives of the list are held at:
- http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/
+ https://lists.perl.org/list/perl5-porters.html
=head1 How are Perl Releases Numbered?
Trial releases of bug-fix maintenance releases are announced on
perl5-porters. Trial releases use the new subversion number (to avoid
testers installing it over the previous release) and include a 'local
-patch' entry in patchlevel.h. The distribution file contains the
+patch' entry in F<patchlevel.h>. The distribution file contains the
string C<MAINT_TRIAL> to make clear that the file is not meant for
public consumption.
If feasible, try to keep filenames 8.3-compliant to humor those poor
souls that get joy from running Perl under such dire limitations.
-There's a script, check83.pl, for keeping your nose 8.3-clean.
+There's a script, F<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).
=item source code
If you have many machine-specific #defines or #includes, consider
-creating an "osish.h" (os2ish.h, vmsish.h, and so on) and including
-that in perl.h. If you have several machine-specific files (function
+creating an "osish.h" (F<os2ish.h>, F<vmsish.h>, and so on) and including
+that in F<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.
peculiarities.
Remember to have a $VERSION in the modules. You can use the
-Porting/checkVERSION.pl script for checking this.
+F<Porting/checkVERSION.pl> script for checking this.
=item documentation
=head2 Automated generation of derivative files
-The F<embed.h>, F<keywords.h>, F<opcode.h>, and F<perltoc.pod> files
+The F<embed.h>, F<keywords.h>, F<opcode.h>, F<regcharclass.h>,
+F<l1_char_class_tab.h>, and F<perltoc.pod> files
are all automatically generated by perl scripts. In general, don't
patch these directly; patch the data files instead.
-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.
-
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.
+Finally, the sample files F<config.sh> and F<config_H> in the
+F<Porting/> subdirectory are generated by the script F<Porting/mksample>.
-=head1 How to Make a Distribution
+=head3 Files generated by metaconfig
-This section has now been expanded and moved into its own file,
-F<Porting/release_managers_guide.pod>.
+F<Configure>, F<config_h.SH> and F<Porting/Glossary> are generated by
+B<metaconfig> (see below for more information on how to use this system)
+and direct changes to these files should in general not be pushed to blead.
-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.
+The exceptions are:
-=head2 run metaconfig
+=over 4
-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.
+=item *
- metaconfig -m
+security fixes
+
+=item *
-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.
+changes pre-approved by the metaconfig maintainers
+
+=back
+
+Such changes should also be notified to the metaconfig maintainers by
+creating an issue at <https://github.com/Perl/metaconfig/issues>.
+
+Alternatively, do consider if the F<*ish.h> files or the hint files might
+be a better place for your changes.
+
+=head1 Working with metaconfig
+
+Information about how to use metaconfig can be found in the F<README>
+and F<README_U> files in the metaconfig repository containing Perl's
+metaconfig units:
+
+ # anonymous clone
+ git clone https://github.com/Perl/metaconfig.git
+ # or using a registered github.com identity with ssh
+ git clone github.com:Perl/metaconfig.git
Since metaconfig is hard to change, running correction scripts after
this generation is sometimes needed. Configure gained complexity over
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<mc_units-20070423.tgz> 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.
+=head1 How to Make a Distribution
-Alternatively, do consider if the F<*ish.h> files or the hint files might be
-a better place for your changes.
+This section has now been expanded and moved into its own file,
+F<Porting/release_managers_guide.pod>.
+
+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 MANIFEST
safely be sorted, so it's easy to track (typically very small) changes
to config.sh and then propagate them to a canned 'config.h' by any
number of means, including a perl script in win32/ or carrying
-config.sh and config_h.SH to a Unix system and running sh
-config_h.SH.) Vms uses configure.com to generate its own config.sh
-and config.h. If you want to add a new variable to config.sh check
+F<config.sh> and F<config_h.SH> to a Unix system and running sh
+config_h.SH.) Vms uses F<configure.com> to generate its own F<config.sh>
+and F<config.h>. If you want to add a new variable to F<config.sh> 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<Porting/config.sh> and F<Porting/config_H> 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<config_h.SH>, those changes must
be reflected in config_H as well. (The name config_H was chosen to
distinguish the file from config.h even on case-insensitive file systems.)
Simply edit the existing config_H file; keep the first few explanatory
lines and then copy your new config.h below.
It may also be necessary to update win32/config.?c, and
-plan9/config.plan9, though you should be quite careful in doing so if
+F<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
directories.
=head2 make regen_perly
-If perly.y has been edited, it is necessary to run this target to rebuild
-perly.h, perly.act and perly.tab. In fact this target just runs the Perl
-script regen_perly.pl. Note that perly.c is I<not> rebuilt; this is just a
+If F<perly.y> has been edited, it is necessary to run this target to rebuild
+F<perly.h>, F<perly.act> and F<perly.tab>. In fact this target just runs the Perl
+script F<regen_perly.pl>. Note that F<perly.c> is I<not> rebuilt; this is just a
plain static file now.
This target relies on you having Bison installed on your system. Running
the target will tell you if you haven't got the right version, and if so,
where to get the right one. Or if you prefer, you could hack
-regen_perly.pl to work with your version of Bison. The important things
+F<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
+output into F<perly.act> and F<perly.tab>, and that the contents of those two
+files, plus F<perly.h>, are functionally equivalent to those produced by the
supported version of Bison.
Note that in the old days, you had to do C<make run_byacc> instead.
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<perl_exp.SH> to see what to do.
=head2 Binary compatibility
-If you do change F<global.sym> or F<interp.sym>, think carefully about
+If you do change F<embed.fnc> think carefully about
what you are doing. To the extent reasonable, we'd like to maintain
source and binary compatibility with older releases of perl. That way,
extensions built under one version of perl will continue to work with
=head2 PPPort
-F<ext/Devel-PPPort/PPPort.pm> needs to be synchronized to include all
-new macros added to .h files (normally perl.h and XSUB.h, but others
+F<dist/Devel-PPPort/PPPort.pm> needs to be synchronized to include all
+new macros added to .h files (normally F<perl.h> and F<XSUB.h>, but others
as well). Since chances are that when a new macro is added the
committer will forget to update F<PPPort.pm>, it's the best to diff for
changes in .h files when making a new release and making sure that
=head2 Todo
-The F<pod/perltodo.pod> file contains a roughly-categorized unordered
+The F<Porting/todo.pod> 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
=head2 VMS-specific updates
-The Perl revision number appears as "perl5" in configure.com.
+The Perl revision number appears as "perl5" in F<configure.com>.
It is courteous to update that if necessary.
I find the F<makepatch> utility quite handy for making patches.
You can obtain it from any CPAN archive under
-http://www.cpan.org/authors/Johan_Vromans/ . There are a couple
+L<https://www.cpan.org/authors/id/J/JV/JV/>. There are a couple
of differences between my version and the standard one. I have mine do
a
=back
-=head1 Running Purify
-
-Purify is a commercial tool that is helpful in identifying memory
-overruns, wild pointers, memory leaks and other such badness. Perl
-must be compiled in a specific way for optimal testing with Purify.
-
-Use the following commands to test perl with Purify:
-
- sh Configure -des -Doptimize=-g -Uusemymalloc -Dusemultiplicity \
- -Accflags=-DPURIFY
- setenv PURIFYOPTIONS "-chain-length=25"
- make all pureperl
- cd t
- ln -s ../pureperl perl
- setenv PERL_DESTRUCT_LEVEL 2
- ./perl TEST
-
-Disabling Perl's malloc allows Purify to monitor allocations and leaks
-more closely; using Perl's malloc will make Purify report most leaks
-in the "potential" leaks category. Enabling the multiplicity option
-allows perl to clean up thoroughly when the interpreter shuts down, which
-reduces the number of bogus leak reports from Purify. The -DPURIFY
-enables any Purify-specific debugging code in the sources.
-
-Purify outputs messages in "Viewer" windows by default. If you don't have
-a windowing environment or if you simply want the Purify output to
-unobtrusively go to a log file instead of to the interactive window,
-use the following options instead:
-
- setenv PURIFYOPTIONS "-chain-length=25 -windows=no -log-file=perl.log \
- -append-logfile=yes"
-
-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 Gotchas
=over 4
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<perl_exp.SH>,
-which reads F<
global.sym> and F<interp.sym>. Thus, the C<pause>
-symbol would have to be added to F<global.sym> So far, so good.
+which reads F<
embed.fnc>. Thus, the C<pause>
+symbol would have to be added to F<embed.fnc> 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
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<embed.h> file.
-This file is built from the F<global.sym> and F<interp.sym> files,
+This file is built from the F<embed.fnc> file,
since those files already list the globally visible symbols. If we
-had added C<pause> to global.sym, then F<embed.h> would contain the
+had added C<pause> to F<embed.fnc>, then F<embed.h> would contain the
line
#define pause Perl_pause
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<my_chsize> in F<global.sym>, export it, and
+Now, we can safely put C<my_chsize> in C<embed.fnc>, export it, and
hide it with F<embed.h>.
To be consistent with what I did for C<pause>, I probably should have
#endif
Alternatively, we could just always use C<chsize> everywhere and move
-C<chsize> from F<
global.sym> to the end of F<perl_exp.SH>. That would
+C<chsize> from F<
embed.fnc> to the end of F<perl_exp.SH>. That would
probably be fine as long as our C<chsize> function agreed with all the
C<chsize> 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
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.
One way to do that is to add
ccflags="$ccflags -DAPPLLIB_EXP=\"/my/override\""
-
+
to your config.over file. (You have to be particularly careful to get the
double quotes in. APPLLIB_EXP must be a valid C string. It might
actually be easier to just #define it yourself in perl.c.)
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
=head1 Upload Your Work to CPAN
You can upload your work to CPAN if you have a CPAN id. Check out
-http://www.cpan.org/modules/04pause.html for information on
+L<http://www.cpan.org/modules/04pause.html> for information on
_PAUSE_, the Perl Author's Upload Server.
I typically upload both the patch file, e.g. F<perl5.004_08.pat.gz>
If you want your patch to appear in the F<src/5.0/unsupported>
directory on CPAN, send e-mail to the CPAN master librarian. (Check
-out http://www.cpan.org/CPAN.html ).
+out L<http://www.cpan.org/CPAN.html> ).
=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
/* 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 <fcntl.h>
#include <sys/types.h>
#include <unistd.h>
-
+
int
truncate(const char *path, off_t len)
{
# 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
GNU configure --options. It's not always obvious exactly what is
intended, but this merits investigation.
-=item make clean
-
-Currently, B<make clean> isn't all that useful, though
-B<make realclean> and B<make distclean> 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.
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
+*.[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@lafayette.edu .
-Additions by Chip Salzenberg chip@perl.com and
-Tim Bunce Tim.Bunce@ig.co.uk .
+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
-2009-07-08-01 Jesse Vincent
+2017-10-13 Dominic Hargreaves
https://perl5.git.perl.org / perl5.git / blobdiff