diff options
| author | Perl 5 Porters <perl5-porters@africa.nicoh.com> | 1997-02-22 04:41:00 +1200 |
|---|---|---|
| committer | Chip Salzenberg <chip@atlantic.net> | 1997-02-22 04:41:00 +1200 |
| commit | aa6893958c2bfb6fa4ab923c8466c188c65748fd (patch) | |
| tree | 012b1f5dd2622b8c322606df0fa2de1a7ec582b1 | |
| parent | d53f8f1cc3de155a009198bbc7c01e2741aa70ac (diff) | |
| download | perl-aa6893958c2bfb6fa4ab923c8466c188c65748fd.tar.gz | |
[inseparable changes from patch from perl5.003_27 to perl5.003_28]
CORE LANGUAGE CHANGES
Subject: Don't let C<sub foo;> undefine &foo
From: Chip Salzenberg <chip@perl.com>
Files: op.c
Subject: Make code, doc agree on $ENV{PATH} and `cmd`
From: Chip Salzenberg <chip@perl.com>
Files: pod/perlsec.pod pp_sys.c
Subject: Optimize keys() and values() in void context
From: Chip Salzenberg <chip@perl.com>
Files: doop.c op.c
CORE PORTABILITY
Subject: VMS patches post _27
Date: Thu, 20 Feb 1997 01:58:46 -0500 (EST)
From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>
Files: MANIFEST dosish.h hv.c lib/ExtUtils/MM_VMS.pm lib/ExtUtils/xsubpp perl.c perlsdio.h pod/perldelta.pod pod/perlvar.pod t/op/closure.t unixish.h vms/Makefile vms/descrip.mms vms/ext/filespec.t vms/genconfig.pl vms/vms.c vms/vmsish.h
private-msgid: <01IFMEMPN1IU0057E2@hmivax.humgen.upenn.edu>
Subject: Re: OS/2 patch for _27
Date: Thu, 20 Feb 1997 19:24:16 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: INSTALL README.os2 lib/Test/Harness.pm os2/Changes os2/OS2/PrfDB/t/os2_prfdb.t os2/os2.c os2/os2ish.h os2/perl2cmd.pl perl.c pod/perldelta.pod t/TEST t/harness t/op/magic.t
Msg-ID: <199702210024.TAA03174@monk.mps.ohio-state.edu>
(applied based on p5p patch as commit 833d3f255ed68b969f062cec63d33f853ed9237c)
DOCUMENTATION
Subject: INSTALL updates since _26
Date: Tue, 18 Feb 1997 16:00:08 -0500 (EST)
From: Andy Dougherty <doughera@fractal.phys.lafayette.edu>
Files: INSTALL
Msg-ID: <Pine.SOL.3.95q.970218155815.2014F-100000@fractal.lafayette.e
(applied based on p5p patch as commit a8247d96fd6167a3b920e63aedee5592cd6e29a7)
Subject: Document "$$0" change
From: Chip Salzenberg <chip@perl.com>
Files: pod/perldelta.pod
Subject: Don't recommend impossible //o for C<$x =~ $y>
From: Chip Salzenberg <chip@perl.com>
Files: pod/perlop.pod
Subject: Correct doc that claimed that <FH> was never false
From: Chip Salzenberg <chip@perl.com>
Files: pod/perldelta.pod pod/perlop.pod
Subject: Document C<$?> vs. $SIG{CHLD}
From: Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de>
Files: pod/perlvar.pod
Subject: Add pumpkin.pod
From: Chip Salzenberg <chip@perl.com>
Files: MANIFEST Porting/pumpkin.pod
Subject: Don't say "associat*ve arr*y"
From: Chip Salzenberg <chip@perl.com>
Files: MANIFEST gv.h hv.c lib/Env.pm lib/overload.pm opcode.pl pod/perl.pod pod/perldelta.pod pod/perldiag.pod pod/perlfunc.pod pod/perlguts.pod pod/perlmod.pod pod/perltie.pod pod/perltoc.pod pod/perltrap.pod x2p/a2p.pod
OTHER CORE CHANGES
Subject: Fix a typo
From: Chip Salzenberg <chip@perl.com>
Files: pp_sys.c
Subject: Fix perl_call_sv(..., G_NOARGS)
From: Chip Salzenberg <chip@perl.com>
Files: perl.c
Subject: Fix SIGSEGV when cloning sub with complex expression
From: Chip Salzenberg <chip@perl.com>
Files: op.c
| -rw-r--r-- | Changes | 179 | ||||
| -rw-r--r-- | INSTALL | 464 | ||||
| -rw-r--r-- | MANIFEST | 6 | ||||
| -rw-r--r-- | Porting/pumpkin.pod | 1122 | ||||
| -rw-r--r-- | README.os2 | 305 | ||||
| -rw-r--r-- | doop.c | 3 | ||||
| -rw-r--r-- | dosish.h | 2 | ||||
| -rw-r--r-- | gv.h | 2 | ||||
| -rw-r--r-- | hints/solaris_2.sh | 1 | ||||
| -rw-r--r-- | hv.c | 20 | ||||
| -rw-r--r-- | lib/Env.pm | 7 | ||||
| -rw-r--r-- | lib/ExtUtils/MM_VMS.pm | 9 | ||||
| -rwxr-xr-x | lib/ExtUtils/xsubpp | 23 | ||||
| -rw-r--r-- | lib/Test/Harness.pm | 36 | ||||
| -rw-r--r-- | lib/overload.pm | 6 | ||||
| -rw-r--r-- | op.c | 31 | ||||
| -rw-r--r-- | opcode.h | 6 | ||||
| -rwxr-xr-x | opcode.pl | 8 | ||||
| -rw-r--r-- | os2/Changes | 10 | ||||
| -rw-r--r-- | os2/OS2/PrfDB/t/os2_prfdb.t | 2 | ||||
| -rw-r--r-- | os2/os2.c | 5 | ||||
| -rw-r--r-- | os2/os2ish.h | 8 | ||||
| -rw-r--r-- | os2/perl2cmd.pl | 2 | ||||
| -rw-r--r-- | patchlevel.h | 2 | ||||
| -rw-r--r-- | perl.c | 48 | ||||
| -rw-r--r-- | perlsdio.h | 6 | ||||
| -rw-r--r-- | pod/perl.pod | 38 | ||||
| -rw-r--r-- | pod/perldelta.pod | 84 | ||||
| -rw-r--r-- | pod/perldiag.pod | 8 | ||||
| -rw-r--r-- | pod/perlfunc.pod | 132 | ||||
| -rw-r--r-- | pod/perlguts.pod | 12 | ||||
| -rw-r--r-- | pod/perlmod.pod | 18 | ||||
| -rw-r--r-- | pod/perlop.pod | 23 | ||||
| -rw-r--r-- | pod/perlsec.pod | 25 | ||||
| -rw-r--r-- | pod/perltie.pod | 25 | ||||
| -rw-r--r-- | pod/perltoc.pod | 62 | ||||
| -rw-r--r-- | pod/perltrap.pod | 5 | ||||
| -rw-r--r-- | pod/perlvar.pod | 5 | ||||
| -rw-r--r-- | pp_sys.c | 10 | ||||
| -rwxr-xr-x | t/TEST | 7 | ||||
| -rwxr-xr-x | t/harness | 7 | ||||
| -rwxr-xr-x | t/op/closure.t | 27 | ||||
| -rwxr-xr-x | t/op/magic.t | 10 | ||||
| -rw-r--r-- | unixish.h | 2 | ||||
| -rw-r--r-- | vms/descrip.mms | 17 | ||||
| -rw-r--r-- | vms/ext/filespec.t | 2 | ||||
| -rw-r--r-- | vms/genconfig.pl | 17 | ||||
| -rw-r--r-- | vms/vms.c | 59 | ||||
| -rw-r--r-- | vms/vmsish.h | 42 | ||||
| -rw-r--r-- | x2p/a2p.pod | 14 |
50 files changed, 2313 insertions, 651 deletions
@@ -9,6 +9,185 @@ releases.) ---------------- +Version 5.003_28 +---------------- + +This release is beta candidate #6. If this isn't good enough to go beta, +I'll eat a floppy disk. (Okay, it's a chocolate floppy, but still....) + + CORE LANGUAGE CHANGES + + Title: "Don't let C<sub foo;> undefine &foo" + From: Chip Salzenberg + Files: op.c + + Title: "Make code, doc agree on $ENV{PATH} and `cmd`" + From: Chip Salzenberg + Files: pod/perlsec.pod pp_sys.c + + Title: "Don't taint $x in C<$x = ($tainted =~ /(\w+)/)>" + From: Chip Salzenberg + Files: pp_ctl.c pp_hot.c + + Title: "Turn off 'expression tainted' flag at end of runops()" + From: Chip Salzenberg + Files: run.c + + Title: "When overloading, don't throw away nomethod's value" + From: Ilya Zakharevich <ilya@math.ohio-state.edu> + Files: gv.c + + Title: "Optimize keys() and values() in void context" + From: Chip Salzenberg + Files: doop.c op.c + + CORE PORTABILITY + + Title: "New hints for Digital UNIX" + From: Jarkko Hietaniemi <jhi@iki.fi> + Files: hints/dec_osf.sh + + Title: "No version of AIX has working setre[ug]id()" + From: neufeld@fast.pvi.org (Keith Neufeld) + Files: hints/aix.sh + + Title: "VMS patches post _27" + From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU> + Msg-ID: <01IFMEMPN1IU0057E2@hmivax.humgen.upenn.edu> + Date: Thu, 20 Feb 1997 01:58:46 -0500 (EST) + Files: MANIFEST dosish.h hv.c lib/ExtUtils/MM_VMS.pm + lib/ExtUtils/xsubpp perl.c perlsdio.h pod/perldelta.pod + pod/perlvar.pod t/op/closure.t unixish.h vms/Makefile + vms/descrip.mms vms/ext/filespec.t vms/genconfig.pl + vms/vms.c vms/vmsish.h + + Title: "Re: OS/2 patch for _27" + From: Ilya Zakharevich <ilya@math.ohio-state.edu> + Msg-ID: <199702210024.TAA03174@monk.mps.ohio-state.edu> + Date: Thu, 20 Feb 1997 19:24:16 -0500 (EST) + Files: INSTALL README.os2 lib/Test/Harness.pm os2/Changes + os2/OS2/PrfDB/t/os2_prfdb.t os2/os2.c os2/os2ish.h + os2/perl2cmd.pl perl.c pod/perldelta.pod t/TEST t/harness + t/op/magic.t + + OTHER CORE CHANGES + + Title: "Fix a typo" + From: Chip Salzenberg + Files: pp_sys.c + + Title: "Undo signal patch -- it broke die() in signal" + From: Chip Salzenberg + Files: mg.c + + Title: "Fix perl_call_sv(..., G_NOARGS)" + From: Chip Salzenberg + Files: perl.c + + Title: "Fix SIGSEGV when cloning sub with complex expression" + From: Chip Salzenberg + Files: op.c + + Title: "Minor update to malloc.c" + From: Ilya Zakharevich <ilya@math.ohio-state.edu> + Msg-ID: <199702210244.VAA03676@monk.mps.ohio-state.edu> + Date: Thu, 20 Feb 1997 21:44:13 -0500 (EST) + Files: malloc.c + + Title: "Fix the Tolkein quote" + From: Chip Salzenberg + Files: perly.y + + BUILD PROCESS + + (no changes) + + LIBRARY AND EXTENSIONS + + Title: "Debugger patch" + From: Ilya Zakharevich <ilya@math.ohio-state.edu> + Msg-ID: <199702210737.CAA03951@monk.mps.ohio-state.edu> + Date: Fri, 21 Feb 1997 02:37:59 -0500 (EST) + Files: lib/perl5db.pl + + Title: "Avoid $` $& $' in libraries" + From: Ilya Zakharevich <ilya@math.ohio-state.edu> + Msg-ID: <199702210207.VAA03560@monk.mps.ohio-state.edu> + Date: Thu, 20 Feb 1997 21:07:30 -0500 (EST) + Files: lib/Getopt/Long.pm lib/Pod/Text.pm lib/diagnostics.pm + os2/OS2/REXX/REXX.pm + + Title: "Remove redundant clearerr() from IO::Seekable" + From: Chip Salzenberg + Files: ext/IO/lib/IO/Handle.pm ext/IO/lib/IO/Seekable.pm + + Title: "prototype error in File::stat" + From: Graham.Barr@tiuk.ti.com + Msg-ID: <199702180748.HAA14151@ultra-boy> + Date: Tue, 18 Feb 1997 07:48:40 GMT + Files: lib/File/stat.pm + + TESTS + + Title: "Include 'study' in regexp.t" + From: Chip Salzenberg + Files: t/op/regexp.t + + Title: "Don't run locale test if -DNO_LOCALE" + From: Chip Salzenberg + Files: t/pragma/locale.t + + Title: "Tweak tests to notice $dont_use_nlink" + From: Chip Salzenberg + Files: t/io/fs.t t/op/stat.t + + Title: "Add test for grep() and wantarray" + From: Hugo van der Sanden <hv@iii.co.uk> + Msg-ID: <199702181105.LAA17895@tyree.iii.co.uk> + Date: Tue, 18 Feb 1997 11:05:59 +0000 + Files: t/op/misc.t + + UTILITIES + + (no changes) + + DOCUMENTATION + + Title: "INSTALL updates since _26" + From: Andy Dougherty <doughera@fractal.phys.lafayette.edu> + Msg-ID: <Pine.SOL.3.95q.970218155815.2014F-100000@fractal.lafayette.e + Date: Tue, 18 Feb 1997 16:00:08 -0500 (EST) + Files: INSTALL + + Title: "Document "$$0" change" + From: Chip Salzenberg + Files: pod/perldelta.pod + + Title: "Don't recommend impossible //o for C<$x =~ $y>" + From: Chip Salzenberg + Files: pod/perlop.pod + + Title: "Correct doc that claimed that <FH> was never false" + From: Chip Salzenberg + Files: pod/perldelta.pod pod/perlop.pod + + Title: "Document C<$?> vs. $SIG{CHLD}" + From: Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de> + Files: pod/perlvar.pod + + Title: "Add pumpkin.pod" + From: Chip Salzenberg + Files: MANIFEST Porting/pumpkin.pod + + Title: "Don't say "associat*ve arr*y"" + From: Chip Salzenberg + Files: MANIFEST gv.h hv.c lib/Env.pm lib/overload.pm opcode.pl + pod/perl.pod pod/perldelta.pod pod/perldiag.pod + pod/perlfunc.pod pod/perlguts.pod pod/perlmod.pod + pod/perltie.pod pod/perltoc.pod pod/perltrap.pod x2p/a2p.pod + + +---------------- Version 5.003_27 ---------------- @@ -4,10 +4,6 @@ Install - Build and Installation guide for perl5. =head1 SYNOPSIS - **************************** - *** NEEDS WORK FOR 5.004 *** - **************************** - The basic steps to build and install perl5 on a Unix system are: rm -f config.sh @@ -15,16 +11,16 @@ The basic steps to build and install perl5 on a Unix system are: make make test make install - # possibly add these: - (cd /usr/include && h2ph *.h sys/*.h) - cd pod; make html && mv *.html <www home dir> && cd .. - cd pod; make tex && <process the latex files> && cd .. + # You may also wish to add these: + (cd /usr/include && h2ph *.h sys/*.h) + (cd pod && make html && mv *.html <www home dir>) + (cd pod && make tex && <process the latex files>) Each of these is explained in further detail below. For information on non-Unix systems, see the section on -L<"Porting Information">, below. +L<"Porting Information"> below. =head1 DESCRIPTION @@ -40,7 +36,7 @@ If you're building Perl on a non-Unix system, you should also read the README file specific to your operating system, since this may provide additional or different instructions for building Perl. -=head1 Space Requirements. +=head1 Space Requirements The complete perl5 source tree takes up about 7 MB of disk space. The complete tree after completing C<make> takes roughly @@ -48,7 +44,7 @@ The complete tree after completing C<make> takes roughly system-dependent. The installation directories need something on the order of 7 MB, though again that value is system-dependent. -=head1 Start with a Fresh Distribution. +=head1 Start with a Fresh Distribution If you have built perl before, you should clean out the build directory with the command @@ -80,7 +76,7 @@ precompiled binary, it might not use the same name. In short, if you wish to use your old config.sh, I recommend running Configure interactively rather than blindly accepting the defaults. -=head1 Run Configure. +=head1 Run Configure Configure will figure out various things about your system. Some things Configure will figure out for itself, other things it will ask @@ -119,7 +115,7 @@ are simplified. For example, if you use prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of /opt/perl/lib/perl5/. -By default, Configure will compile perl to use dynamic loading, if +By default, Configure will compile perl to use dynamic loading if your system supports it. If you want to force perl to be compiled statically, you can either choose this when Configure prompts you or you can use the Configure command line option -Uusedl. @@ -131,37 +127,19 @@ use the supplied B<configure> command, e.g. CC=gcc ./configure -The B<configure> script emulates several of the more common configure +The B<configure> script emulates a few of the more common configure options. Try ./configure --help for a listing. -Cross compiling is currently not supported. +Cross compiling is not supported. For systems that do not distinguish the files "Configure" and "configure", Perl includes a copy of B<configure> named B<configure.gnu>. -=head2 Binary Compatibility With Earlier Versions of Perl 5 - -Starting with Perl 5.003, all functions in the Perl C source code have -been protected by default by the prefix Perl_ (or perl_) so that you -may link with third-party libraries without fear of namespace -collisons. This change broke compatability with version 5.002, so -installing 5.003 or 5.004 over 5.002 or earlier will force you to -re-build and install all of your dynamically loadable extensions. -(The standard extensions supplied with Perl are handled -automatically). You can turn off this namespace protection by adding --DNO_EMBED to your ccflags variable in config.sh. - -Perl 5.003's namespace protection was incomplete, which has been -rectified in Perl 5.004. However, some sites may need to maintain -complete binary compatibility with Perl 5.003. If you are building -Perl for such a site, then when B<Configure> asks if you want binary -compatibility, answer "y". - =head2 Extensions By default, Configure will offer to build every extension which appears @@ -202,7 +180,7 @@ Again, this is taken care of automatically if you don't have the ndbm library. Of course, you may always run Configure interactively and select only -the Extensions you want. +the extensions you want. Finally, if you have dynamic loading (most modern Unix systems do) remember that these extensions do not increase the size of your perl @@ -230,7 +208,7 @@ Configure. See the examples below. =over 4 -=item gdbm in /usr/local. +=item gdbm in /usr/local Suppose you have gdbm and want Configure to find it and build the GDBM_File extension. This examples assumes you have F<gdbm.h> @@ -290,7 +268,7 @@ F</usr/you>, then you have to include both, namely =back -=head2 Installation Directories. +=head2 Installation Directories The installation directories can all be changed by answering the appropriate questions in Configure. For convenience, all the @@ -319,8 +297,8 @@ systems, B<man less> would end up calling up Perl's less.pm module man page, rather than the B<less> program. If you specify a prefix that contains the string "perl", then the -directory structure is simplified. For example, if you Configure -with -Dprefix=/opt/perl, then the defaults are +directory structure is simplified. For example, if you Configure with +-Dprefix=/opt/perl, then the defaults are /opt/perl/lib/archname/5.004 /opt/perl/lib @@ -350,6 +328,99 @@ can be moved to the site_perl and site_perl/archname directories. Again, these are just the defaults, and can be changed as you run Configure. +=head2 Changing the installation directory + +Configure distinguishes between the directory in which perl (and its +associated files) should be installed and the directory in which it +will eventually reside. For most sites, these two are the same; for +sites that use AFS, this distinction is handled automatically. +However, sites that use software such as B<depot> to manage software +packages may also wish to install perl into a different directory and +use that management software to move perl to its final destination. +This section describes how to do this. Someday, Configure may support +an option -Dinstallprefix=/foo to simplify this. + +Suppose you want to install perl under the F</tmp/perl5> directory. +You can edit F<config.sh> and change all the install* variables to +point to F</tmp/perl5> instead of F</usr/local/wherever>. You could +also set them all from the Configure command line. Or, you can +automate this process by placing the following lines in a file +F<config.over> B<before> you run Configure (replace /tmp/perl5 by a +directory of your choice): + + installprefix=/tmp/perl5 + test -d $installprefix || mkdir $installprefix + test -d $installprefix/bin || mkdir $installprefix/bin + installarchlib=`echo $installarchlib | sed "s!$prefix!$installprefix!"` + installbin=`echo $installbin | sed "s!$prefix!$installprefix!"` + installman1dir=`echo $installman1dir | sed "s!$prefix!$installprefix!"` + installman3dir=`echo $installman3dir | sed "s!$prefix!$installprefix!"` + installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"` + installscript=`echo $installscript | sed "s!$prefix!$installprefix!"` + installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"` + installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"` + +Then, you can Configure and install in the usual way: + + sh Configure -des + make + make test + make install + +=head2 Creating an installable tar archive + +If you need to install perl on many identical systems, it is +convenient to compile it once and create an archive that can be +installed on multiple systems. Here's one way to do that: + + # Set up config.over to install perl into a different directory, + # e.g. /tmp/perl5 (see previous part). + sh Configure -des + make + make test + make install + cd /tmp/perl5 + tar cvf ../perl5-archive.tar . + # Then, on each machine where you want to install perl, + cd /usr/local # Or wherever you specified as $prefix + tar xvf perl5-archive.tar + +=head2 Configure-time Options + +There are several different ways to Configure and build perl for your +system. For most users, the defaults are sensible and will work. +Some users, however, may wish to further customize perl. Here are +some of the main things you can change. + +=head2 Binary Compatibility With Earlier Versions of Perl 5 + +If you have dynamically loaded extensions that you built under +perl 5.003 and that you wish to continue to use with perl 5.004, then you +need to ensure that 5.004 remains binary compatible with 5.003. + +Starting with Perl 5.003, all functions in the Perl C source code have +been protected by default by the prefix Perl_ (or perl_) so that you +may link with third-party libraries without fear of namespace +collisions. This change broke compatibility with version 5.002, so +installing 5.003 or 5.004 over 5.002 or earlier will force you to +re-build and install all of your dynamically loadable extensions. +(The standard extensions supplied with Perl are handled +automatically). You can turn off this namespace protection by adding +-DNO_EMBED to your ccflags variable in config.sh. + +Perl 5.003's namespace protection was incomplete, but this has +been fixed in 5.004. However, some sites may need to maintain +complete binary compatibility with Perl 5.003. If you are building +Perl for such a site, then when B<Configure> asks if you want binary +compatibility, answer "y". + +On the other hand, if you are embedding perl into another application +and want the maximum namespace protection, then you probably ought to +answer "n" when B<Configure> asks if you want binary compatibility. + +The default answer of "y" to maintain binary compatibility is probably +appropriate for almost everyone. + =head2 Selecting File IO mechanisms Previous versions of perl used the standard IO mechanisms as defined in @@ -374,7 +445,7 @@ everywhere. =item 1. AT&T's "sfio". This has superior performance to <stdio.h> in many -cases, and is extensible by the use of "disipline" modules. Sfio +cases, and is extensible by the use of "discipline" modules. Sfio currently only builds on a subset of the UNIX platforms perl supports. Because the data structures are completely different from stdio, perl extension modules or external libraries may not work. This @@ -401,7 +472,7 @@ abstraction. This configuration should work on all platforms (but might not). -You select this option via : +You select this option via: sh Configure -Duseperlio -Uusesfio @@ -410,46 +481,7 @@ detect sfio, then this will be the default suggested by Configure. =back -=head2 Changing the installation directory - -Configure distinguishes between the directory in which perl (and its -associated files) should be installed and the directory in which it -will eventually reside. For most sites, these two are the same; for -sites that use AFS, this distinction is handled automatically. -However, sites that use software such as B<depot> to manage software -packages may also wish to install perl into a different directory and -use that management software to move perl to its final destination. -This section describes how to do this. Someday, Configure may support -an option C<-Dinstallprefix=/foo> to simplify this. - -Suppose you want to install perl under the F</tmp/perl5> directory. -You can edit F<config.sh> and change all the install* variables to -point to F</tmp/perl5> instead of F</usr/local/wherever>. You could -also set them all from the Configure command line. Or, you can -automate this process by placing the following lines in a file -F<config.over> B<before> you run Configure (replace /tmp/perl5 by a -directory of your choice): - - installprefix=/tmp/perl5 - test -d $installprefix || mkdir $installprefix - test -d $installprefix/bin || mkdir $installprefix/bin - installarchlib=`echo $installarchlib | sed "s!$prefix!$installprefix!"` - installbin=`echo $installbin | sed "s!$prefix!$installprefix!"` - installman1dir=`echo $installman1dir | sed "s!$prefix!$installprefix!"` - installman3dir=`echo $installman3dir | sed "s!$prefix!$installprefix!"` - installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"` - installscript=`echo $installscript | sed "s!$prefix!$installprefix!"` - installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"` - installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"` - -Then, you can Configure and install in the usual way: - - sh Configure -des - make - make test - make install - -=head2 Building a shared libperl.so Perl library. +=head2 Building a shared libperl.so Perl library Currently, for most systems, the main perl executable is built by linking the "perl library" libperl.a with perlmain.o, your static @@ -465,7 +497,7 @@ can share the same library. The disadvantages are that there may be a significant performance penalty associated with the shared libperl.so, and that the overall -meachanism is still rather fragile with respect to different versions +mechanism is still rather fragile with respect to different versions and upgrades. In terms of performance, on my test system (Solaris 2.5_x86) the perl @@ -488,7 +520,7 @@ You can elect to build a shared libperl by sh Configure -Duseshrplib To actually build perl, you must add the current working directory to your -LD_LIBRARY_PATH environtment variable before running make. You can do +LD_LIBRARY_PATH environment variable before running make. You can do this with LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH @@ -520,23 +552,69 @@ version of perl. You can do this with by changing all the *archlib* variables in config.sh, namely archlib, archlib_exp, and installarchlib, to point to your new architecture-dependent library. -=head2 Creating an installable tar archive +=head2 Malloc Performance Flags -If you need to install perl on many identical systems, it is -convenient to compile it once and create an archive that can be -installed on multiple systems. Here's one way to do that: +If you are using Perl's malloc, you may define one or more of the +following macros to change its behavior in potentially useful ways. - # Set up config.over to install perl into a different directory, - # e.g. /tmp/perl5 (see previous part). - sh Configure -des - make - make test - make install - cd /tmp/perl5 - tar cvf ../perl5-archive.tar . - # Then, on each machine where you want to install perl, - cd /usr/local # Or wherever you specified as $prefix - tar xvf perl5-archive.tar +=over 4 + +=item -DEMERGENCY_SBRK + +If this macro is defined, running out of memory need not be a fatal +error: a memory pool can allocated by assigning to the special +variable C<$^M>. See L<"$^M">. + +=item -DPACK_MALLOC + +Perl memory allocation is by bucket with sizes close to powers of two. +Because of these malloc overhead may be big, especially for data of +size exactly a power of two. If C<PACK_MALLOC> is defined, perl uses +a slightly different algorithm for small allocations (up to 64 bytes +long), which makes it possible to have overhead down to 1 byte for +allocations which are powers of two (and appear quite often). + +Expected memory savings (with 8-byte alignment in C<alignbytes>) is +about 20% for typical Perl usage. Expected slowdown due to additional +malloc overhead is in fractions of a percent (hard to measure, because +of the effect of saved memory on speed). + +=item -DTWO_POT_OPTIMIZE + +Similarly to C<PACK_MALLOC>, this macro improves allocations of data +with size close to a power of two; but this works for big allocations +(starting with 16K by default). Such allocations are typical for big +hashes and special-purpose scripts, especially image processing. + +On recent systems, the fact that perl requires 2M from system for 1M +allocation will not affect speed of execution, since the tail of such +a chunk is not going to be touched (and thus will not require real +memory). However, it may result in a premature out-of-memory error. +So if you will be manipulating very large blocks with sizes close to +powers of two, it would be wise to define this macro. + +Expected saving of memory is 0-100% (100% in applications which +require most memory in such 2**n chunks); expected slowdown is +negligible. + +=back + +=head2 Other Compiler Flags + +For most users, all of the Configure defaults are fine. However, +you can change a number of factors in the way perl is built +by adding appropriate B<-D> directives to your ccflags variable in +config.sh. + +For example, you can replace the rand() and srand() functions in the +perl source by any other random number generator by a trick such as the +following: + + sh Configure -Dccflags='-Drand=random -Dsrand=srandom' + +or by adding C<-Drand=random> and C<-Dsrandom=srandom> to your ccflags +at the appropriate Configure prompt. (You may also have to adjust +Configure's guess for 'randbits' as well.) =head2 What if it doesn't work? @@ -549,15 +627,15 @@ Configure interactively so that you can check (and correct) its guesses. All the installation questions have been moved to the top, so you don't -have to wait for them. Once you've handled them (and your C compiler & -flags) you can type C<&-d> at the next Configure prompt and Configure +have to wait for them. Once you've handled them (and your C compiler and +flags) you can type C<&-d> at the next Configure prompt and Configure will use the defaults from then on. If you find yourself trying obscure command line incantations and config.over tricks, I recommend you run Configure interactively instead. You'll probably save yourself time in the long run. -=item Hint files. +=item Hint files The perl distribution includes a number of system-specific hints files in the hints/ directory. If one of them matches your system, Configure @@ -651,7 +729,7 @@ To change the C flags for all the files, edit F<config.sh> and change either C<$ccflags> or C<$optimize>, and then re-run B<sh Configure -S ; make depend>. -=item No sh. +=item No sh If you don't have sh, you'll have to copy the sample file config_H to config.h and edit the config.h to reflect your system's peculiarities. @@ -660,8 +738,8 @@ mechanism. =item Porting information -Specific information for the OS/2, Plan9, and VMS ports are in the -corresponing subdirectories. Additional information, including +Specific information for the OS/2, Plan9, VMS and Win32 ports are in the +corresponding subdirectories. Additional information, including a glossary of all those config.sh variables, is in the Porting subdirectory. @@ -694,12 +772,7 @@ If none of them help, and careful reading of the error message and the relevant manual pages on your system doesn't help, you can send a message to either the comp.lang.perl.misc newsgroup or to perlbug@perl.com with an accurate description of your problem. -Please include the I<output> of the B<./myconfig> shell script -that comes with the distribution. - -[The B<perlbug> program that comes with the perl distribution is -useful for sending in such reports, but you need to have -perl compiled and installed before you can use it.] +See L<"Reporting Problems"> below. =over 4 @@ -726,7 +799,8 @@ locale. See the discussion under L<make test> below about locales. =item * -If you get duplicates upon linking for malloc et al, say -DHIDEMYMALLOC. +If you get duplicates upon linking for malloc et al, add -DHIDEMYMALLOC +or -DEMBEDMYMALLOC to your ccflags variable in config.sh. =item varargs @@ -770,7 +844,8 @@ L<"Solaris and SunOS dynamic loading">. =item * If you run into dynamic loading problems, check your setting of -the LD_LIBRARY_PATH environment variable. Perl should build +the LD_LIBRARY_PATH environment variable. If you're creating a static +Perl library (libperl.a rather than libperl.so) it should build fine with LD_LIBRARY_PATH unset, though that may depend on details of your local set-up. @@ -780,13 +855,13 @@ The primary cause of the 'dlopen: stub interception failed' message is that the LD_LIBRARY_PATH environment variable includes a directory which is a symlink to /usr/lib (such as /lib). -The reason this causes a problem is quite subtle. The file libdl.so.1.0 +The reason this causes a problem is quite subtle. The file libdl.so.1.0 actually *only* contains functions which generate 'stub interception failed' errors! The runtime linker intercepts links to "/usr/lib/libdl.so.1.0" and links in internal implementation of those functions instead. [Thanks to Tim Bunce for this explanation.] -=item * +=item nm extraction If Configure seems to be having trouble finding library functions, try not using nm extraction. You can do this from the command line @@ -812,10 +887,10 @@ If Configure guessed wrong, it is likely that Configure guessed wrong on a number of other common functions too. You are probably better off re-running Configure without using nm extraction (see previous item). -=item * +=item Optimizer If you can't compile successfully, try turning off your compiler's -optimizier. Edit config.sh and change the line +optimizer. Edit config.sh and change the line optimize='-O' @@ -860,7 +935,7 @@ If you see such a message during the building of an extension, but the extension passes its tests anyway (see L<"make test"> below), then don't worry about the warning message. The extension Makefile.PL goes looking for various libraries needed on various -systems; few systems will need all the possible libries listed. +systems; few systems will need all the possible libraries listed. For example, a system may have -lcposix or -lposix, but it's unlikely to have both, so most users will see warnings for the one they don't have. The message 'will try anyway' is intended to @@ -879,6 +954,20 @@ It is true that, in principle, Configure could have figured all of this out, but Configure and the extension building process are not quite that tightly coordinated. +=item sh: ar: not found + +This is a message from your shell telling you that the command 'ar' +was not found. You need to check your PATH environment variable to +make sure that it includes the directory with the 'ar' command. This +is a common problem on Solaris, where 'ar' is in the F</usr/ccs/bin> +directory. + +=item db-recno failure on tests 51, 53 and 55 + +Old versions of the DB library (including the DB library which comes +with FreeBSD 2.1) had broken handling of recno databases with modified +bval settings. Upgrade your DB library or OS. + =item * Some additional things that have been reported for either perl4 or perl5: @@ -887,49 +976,58 @@ Genix may need to use libc rather than libc_s, or #undef VARARGS. NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR. -UTS may need one or more of B<-DCRIPPLED_CC>, B<-K> or B<-g>, and undef LSTAT. +UTS may need one or more of -DCRIPPLED_CC, B<-K> or B<-g>, and undef LSTAT. If you get syntax errors on '(', try -DCRIPPLED_CC. Machines with half-implemented dbm routines will need to #undef I_ODBM -db-recno failure on tests 51, 53 and 55: Old versions of the DB library -(including the DB library which comes with FreeBSD 2.1) had broken -handling of recno databases with modified bval settings. Upgrade your -DB library or OS. - =back =head1 make test This will run the regression tests on the perl you just made. If it doesn't say "All tests successful" then something went wrong. See the -file F<t/README> in the F<t> subdirectory. Note that you can't run it -in background if this disables opening of /dev/tty. +file F<t/README> in the F<t> subdirectory. Note that you can't run the +tests in background if this disables opening of /dev/tty. If B<make test> bombs out, just B<cd> to the F<t> directory and run -B<TEST> by hand to see if it makes any difference. If individual tests +F<./TEST> by hand to see if it makes any difference. If individual tests bomb, you can run them by hand, e.g., ./perl op/groups.t +Another way to get more detailed information about failed tests and +individual subtests is to B<cd> to the F<t> directory and run + + ./perl harness + +(this assumes that I<most> tests succeed, since F<harness> uses +complicated constructs). + You can also read the individual tests to see if there are any helpful comments that apply to your system. -B<Note>: one possible reason for errors is that some external programs +B<Note>: One possible reason for errors is that some external programs may be broken due to the combination of your environment and the way C<make test> exercises them. For example, this may happen if you have -one or more of these environment variables set: C<LC_ALL LC_CTYPE +one or more of these environment variables set: C<LC_ALL LC_CTYPE LC_COLLATE LANG>. In some versions of UNIX, the non-English locales are known to cause programs to exhibit mysterious errors. If you have any of the above environment variables set, please try -C<setenv LC_ALL C> (for C shell) or <LC_ALL=C;export LC_ALL> (for -Bourne or Korn shell) from the command line and then retry C<make + + setenv LC_ALL C + +(for C shell) or + + LC_ALL=C;export LC_ALL + +for Bourne or Korn shell) from the command line and then retry C<make test>. If the tests then succeed, you may have a broken program that -is confusing the testing. Please run the troublesome test by hand as +is confusing the testing. Please run the troublesome test by hand as shown above and see whether you can locate the program. Look for -things like: C<exec, `backquoted command`, system, open("|...")> or +things like: C<exec, `backquoted command`, system, open("|...")> or C<open("...|")>. All these mean that Perl is trying to run some external program. @@ -938,14 +1036,10 @@ external program. This will put perl into the public directory you specified to B<Configure>; by default this is F</usr/local/bin>. It will also try to put the man pages in a reasonable place. It will not nroff the man -page, however. You may need to be root to run B<make install>. If you +pages, however. You may need to be root to run B<make install>. If you are not root, you must own the directories in question and you should ignore any messages about chown not working. -You may see some harmless error messages and warnings from pod2man. -You may safely ignore them. (Yes, they should be fixed, but they -didn't seem important enough to warrant holding up the entire release.) - If you want to see exactly what will happen without installing anything, you can run @@ -965,12 +1059,16 @@ B<make install> will install the following: c2ph, pstruct Scripts for handling C structures in header files. s2p sed-to-perl translator find2perl find-to-perl translator + h2ph Extract constants and simple macros from C headers h2xs Converts C .h header files to Perl extensions. perlbug Tool to report bugs in Perl. perldoc Tool to read perl's pod documentation. + pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules pod2html, Converters from perl's pod documentation format - pod2latex, and to other useful formats. - pod2man + pod2latex, to other useful formats. + pod2man, and + pod2text + splain Describe Perl warnings and errors library files in $privlib and $archlib specified to Configure, usually under /usr/local/lib/perl5/. @@ -992,34 +1090,7 @@ under $archlib so that any user may later build new extensions, run the optional Perl compiler, or embed the perl interpreter into another program even if the Perl source is no longer available. -Most of the documentation in the pod/ directory is also available -in HTML and LaTeX format. Type - - cd pod; make html; cd .. - -to generate the html versions, and - - cd pod; make tex; cd .. - -to generate the LaTeX versions. - -=head1 cd /usr/include; h2ph *.h sys/*.h - -Some of the perl library files need to be able to obtain information from -the system header files. This command will convert the most commonly used -header files in F</usr/include> into files that can be easily interpreted -by perl. These files will be placed in architectural library directory -you specified to B<Configure>; by default this is -F</usr/local/lib/perl5/ARCH/VERSION>, where B<ARCH> is your architecture -(such as C<sun4-solaris>) and B<VERSION> is the version of perl you are -building (for example, C<5.003>). - -B<NOTE:> Due to differences in the C and perl languages, the conversion of -the header files in not perfect. You may have to hand edit some of the -converted files to get them to parse correctly. For example, it breaks -spectacularly on type casting and certain structures. - -=head1 Coexistence with earlier versions of perl5. +=head1 Coexistence with earlier versions of perl5 You can safely install the current version of perl5 and still run scripts under the old binaries for versions 5.003 and later ONLY. Instead of @@ -1032,7 +1103,7 @@ in incompatible ways. The architecture-dependent files are stored in a version-specific directory (such as F</usr/local/lib/perl5/sun4-sunos/5.004>) so that -they are still accessible. I<Note:> Perl 5.000 and 5.001 did not +they are still accessible. I<Note:> Perl 5.000 and 5.001 did not put their architecture-dependent libraries in a version-specific directory. They are simply in F</usr/local/lib/perl5/$archname>. If you will not be using 5.000 or 5.001, you may safely remove those @@ -1045,8 +1116,8 @@ Most extensions will probably not need to be recompiled to use with a newer version of perl. If you do run into problems, and you want to continue to use the old version of perl along with your extension, simply move those extension files to the appropriate version directory, such as -F</usr/local/lib/perl/archname/5.004>. Then Perl 5.004 will find your -files in the 5.004 directory, and newer versions of perl will find your +F</usr/local/lib/perl/archname/5.003>. Then Perl 5.003 will find your +files in the 5.003 directory, and newer versions of perl will find your newer extension in the site_perl directory. Some users may prefer to keep all versions of perl in completely @@ -1074,6 +1145,55 @@ the C<#!> line at the top of them by C<#!/usr/local/bin/perl4.036> (or whatever the appropriate pathname is). See pod/perltrap.pod for possible problems running perl4 scripts under perl5. +=head1 cd /usr/include; h2ph *.h sys/*.h + +Some perl scripts need to be able to obtain information from +the system header files. This command will convert the most commonly used +header files in F</usr/include> into files that can be easily interpreted +by perl. These files will be placed in the architectural library directory +you specified to B<Configure>; by default this is +F</usr/local/lib/perl5/ARCH/VERSION>, where B<ARCH> is your architecture +(such as C<sun4-solaris>) and B<VERSION> is the version of perl you are +building (for example, C<5.004>). + +B<Note:> Due to differences in the C and perl languages, the +conversion of the header files is not perfect. You will probably have +to hand-edit some of the converted files to get them to parse +correctly. For example, h2ph breaks spectacularly on type casting and +certain structures. + +=head1 cd pod && make html && mv *.html (www home dir) + +Some sites may wish to make the documentation in the pod/ directory +available in HTML format. Type + + cd pod && make html && mv *.html <www home dir> + +where F<www home dir> is wherever your site keeps HTML files. + +=head1 cd pod && make tex && (process the latex files) + +Some sites may also wish to make the documentation in the pod/ directory +available in TeX format. Type + + (cd pod && make tex && <process the latex files>) + +=head1 Reporting Problems + +If you have difficulty building perl, and none of the advice in this +file helps, and careful reading of the error message and the relevant +manual pages on your system doesn't help either, then you should send a +message to either the comp.lang.perl.misc newsgroup or to +perlbug@perl.com with an accurate description of your problem. + +Please include the I<output> of the B<./myconfig> shell script +that comes with the distribution. Alternatively, you can use the +B<perlbug> program that comes with the perl distribution, +but you need to have perl compiled and installed before you can use it. + +You might also find helpful information in the F<Porting> +directory of the perl distribution. + =head1 DOCUMENTATION Read the manual entries before running perl. The main documentation is @@ -1087,9 +1207,11 @@ along with its I<Table of Contents> by going to the pod/ subdirectory and running (either): ./roffitall -groff # If you have GNU groff installed - ./roffitall -psroff # Otherwise + ./roffitall -psroff # If you have psroff This will leave you with two postscript files ready to be printed. +(You may need to fix the roffitall command to use your local troff +set-up.) Note that you must have performed the installation already before running the above, since the script collects the installed files to @@ -1102,4 +1224,4 @@ from the original README by Larry Wall. =head1 LAST MODIFIED -8 February 1997 +18 February 1997 @@ -14,6 +14,7 @@ INTERN.h Included before domestic .h files MANIFEST This list of files Makefile.SH A script that generates Makefile Porting/Glossary Glossary of config.sh variables +Porting/pumpkin.pod Guidelines and hints for Perl maintainers README The Instructions README.amiga Notes about AmigaOS port README.os2 Notes about OS/2 port @@ -646,7 +647,7 @@ t/op/cmp.t See if the various string and numeric compare work t/op/cond.t See if conditional expressions work t/op/delete.t See if delete works t/op/do.t See if subroutines work -t/op/each.t See if associative iterators work +t/op/each.t See if hash iterators work t/op/eval.t See if eval operator works t/op/exec.t See if exec and system work t/op/exp.t See if math functions work @@ -721,7 +722,6 @@ utils/perlbug.PL A simple tool to submit a bug report utils/perldoc.PL A simple tool to find & display perl's documentation utils/pl2pm.PL A pl to pm translator utils/splain.PL Stand-alone version of diagnostics.pm -vms/Makefile VMS port vms/config.vms default config.h for VMS vms/descrip.mms MM[SK] description file for build vms/ext/DCLsym/0README.txt ReadMe file for VMS::DCLsym @@ -813,7 +813,7 @@ x2p/a2p.y A yacc grammer for awk x2p/a2py.c Awk compiler, sort of x2p/cflags.SH A script that emits C compilation flags per file x2p/find2perl.PL A find to perl translator -x2p/hash.c Associative arrays again +x2p/hash.c Hashes again x2p/hash.h Public declarations for the above x2p/proto.h Dummy header x2p/s2p.PL Sed to perl translator diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod new file mode 100644 index 0000000000..3744548fc5 --- /dev/null +++ b/Porting/pumpkin.pod @@ -0,0 +1,1122 @@ +=head1 NAME + +Pumpkin - Notes on handling the Perl Patch Pumpkin + +=head1 SYNOPSIS + +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 is still under construction, and still subject to +significant changes. Still, I hope parts of it will be useful, +so I'm releasing it even though it's not done. + +For the most part, it's a collection of anecdotal information that +already assumes some familiarity with the Perl sources. I really need +an introductory section that describes the organization of the sources +and all the various auxiliary files that are part of the distribution. + +=head1 Where Do I Get Perl Sources and Related Material? + +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, which automatically points you to a +mirror site "close" to you. + +=head2 Perl5-porters mailing list + +The mailing list perl5-porters@perl.org +is the main group working with the development of perl. If you're +interested in all the latest developments, you should definitely +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) + + subscribe perl5-porters + +to perl5-porters-request@perl.org . + +=head1 How are Perl Releases Numbered? + +Perl version numbers are floating point numbers, such as 5.004. The +major version number is 5, the minor version is '0', and '03' is the +patchlevel. The version number is available as the magic variable $], +and can be used in comparisons, e.g. + + print "You've got an old perl\n" if $] < 5.002; + +(Observations about the imprecision of floating point numbers for +representing reality probably have more relevance than you might +imagine :-) + +You can also require particular version (or later) with + + use 5.002; + +=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.004_04 is the 4'th developer version built on top of +5.004. It might include the _01, _02, and _03 changes, but it +also might not. Sub-versions are allowed to be subversive. + +These sub-versions can also be used as floating point numbers, so +you can do things such as + + print "You've got an unstable perl\n" if $] == 5.00403; + +You can also require particular version (or later) with + + use 5.004_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. + +=head2 Why such a complicated scheme? + +Two reasons, really. At least. + +First, we need some way to identify releases that are known to +have new features that need testing and exploration. The +subversion scheme does that nicely while fitting into the +C<use 5.004;> 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. + +=head2 Why is it called the patch pumpkin? + +Chip Salzenberg gets credit for that, with a nod to his cow orker, +David Croy. We had passed around various names (baton, token, hot +potato) but none caught on. Then, Chip asked: + +[begin quote] + + Who has the patch pumpkin? + +To explain: David Croy once told me once that at a previous job, +there was one tape drive and multiple systems that used it for backups. +But instead of some high-tech exclusion software, they used a low-tech +method to prevent multiple simultaneous backups: a stuffed pumpkin. +No one was allowed to make backups unless they had the "backup pumpkin". + +[end quote] + +The name has stuck. + +=head1 Philosophical Issues in Patching 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. +(This section is still under construction.) + +=head2 Solve problems as generally as possible + +(I still have to think of a good example here.) + +=head2 Seek consensus on major changes + +If you are making big changes, don't do it in secret. Discuss the +ideas in advance on perl5-porters. + +=head2 Keep the documentation up-to-date + +If your changes may affect how users use perl, then check to be sure +that the documentation is in sync with your changes. Be sure to +check all the files F<pod/*.pod> and also the F<INSTALL> document. + +Consider writing the appropriate documentation first and then +implementing it to correspond to the documentation. + +=head2 Avoid machine-specific #ifdef's + +To the extent reasonable, try to avoid machine-specific #ifdef's in +the sources. Instead, use feature-specific #ifdef's. The reason is +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 Allow for lots of testing + +We should never release a main version without testing it as a +subversion first. + +=head2 Automate generatation 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 +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, minor changes to +F<Configure> may be made in between major sync-ups with the metaconfig +units, which tends to be complicated operations. + +=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. + +=head2 Announce your intentions + +First, you should volunteer out loud to take the patch pumpkin. It's +generally counter-productive to have multiple people working in secret +on the same thing. + +At the same time, announce what you plan to do with the patch pumpkin, +to allow folks a chance to object or suggest alternatives, or do it for +you. Naturally, the patch pumpkin holder ought to incorporate various +bug fixes and documentation improvements that are posted while he or +she has the pumpkin, but there might also be larger issues at stake. + +One of the precepts of the subversion idea is that we shouldn't give +it to anyone unless we have some idea what you're going to do with +it. + +=head2 refresh pod/perltoc.pod + +Presumably, you have done a full C<make> in your working source +directory. Before you C<make spotless> (if you do), and if you have +changed any documentation in any module or pod file, change to the +F<pod> directory and run C<make toc>. + +=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. + +=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 + +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<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. + +Alternatively, do consider if the F<*ish.h> files might be a better +place for your changes. + +=head2 MANIFEST + +Make sure the MANIFEST is up-to-date. You can use dist's B<manicheck> +program for this. You can also use + + perl -MExtUtils::Manifest -e fullcheck + +to do half the job. This will make sure everything listed in MANIFEST +is included in the distribution. dist's B<manicheck> command 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.) + +If you are using metaconfig to regenerate Configure, then you should note +that metaconfig actually uses MANIFEST.new, so you want to be sure +MANIFEST.new is up-to-date too. I haven't found the MANIFEST/MANIFEST.new +distinction particularly useful, but that's probably because I still haven't +learned how to use the full suite of tools in the dist distribution. + +=head2 Check permissions + +All the tests in the t/ directory ought to be executable. The +main makefile used to do a 'chmod t/*/*.t', but that resulted in +a self-modifying distribution--something some users would strongly +prefer to avoid. Probably, the F<t/TEST> script should check for this +and do the chmod if needed, but it doesn't currently. + +In all, the following files should probably be executable: + + Configure + configpm + configure + embed.pl + installperl + installman + keywords.pl + lib/splain + myconfig + opcode.pl + perly.fixer + t/TEST + t/*/*.t + *.SH + vms/ext/Stdio/test.pl + vms/ext/filespec.t + vms/fndvers.com + 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 + +This will build a config.sh and config.h. You can skip this if you haven't +changed Configure or config_h.SH at all. + +=head2 Update config_H + +The config_H file is provided to help those folks who can't run Configure. +It is important to keep it up-to-date. If you have changed 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 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 +directories. + +=head2 make run_byacc + +If you have byacc-1.8.2 (available from CPAN), and if there have been +changes to F<perly.y>, you can regenerate the F<perly.c> 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<perly.fixer> +script. Depending on the nature of the changes to F<perly.y>, 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<perly.fixer> to detect this, but I never completed the +task. + +Some additional notes from Larry on this: + +Don't forget to regenerate perly.c.diff. + + byacc perly.y + mv y.tab.c perly.c + patch perly.c <perly.c.diff + # manually apply any failed hunks + diff -c2 perly.c.orig 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 + +=head2 make regen_headers + +The F<embed.h>, F<keywords.h>, and F<opcode.h> files are all automatically +generated by perl scripts. Since the user isn't guaranteed to have a +working perl, we can't require the user to generate them. Hence you have +to, if you're making a distribution. + +I used to include rules like the following in the makefile: + + # The following three header files are generated automatically + # The correct versions should be already supplied with the perl kit, + # in case you don't have perl or 'sh' available. + # The - is to ignore error return codes in case you have the source + # installed read-only or you don't have perl yet. + keywords.h: keywords.pl + @echo "Don't worry if this fails." + - perl keywords.pl + + +However, I got lots of mail consisting of people worrying because the +command failed. I eventually decided that I would save myself time +and effort by manually running C<make regen_headers> myself rather +than answering all the questions and complaints about the failing +command. + +=head2 global.sym and interp.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. + +=head2 Binary compatibility + +If you do change F<global.sym> or F<interp.sym>, 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, +extensions built under one version of perl will continue to work with +new versions of perl. + +Of course, some incompatible changes may well be necessary. I'm just +suggesting that we not make any such changes without thinking carefully +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 + +Be sure to update the F<Changes> file. Try to include both an overall +summary as well as detailed descriptions of the changes. Your +audience will include bother 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". + +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 OS/2-specific updates + +In the os2 directory is F<diff.configure>, a set of OS/2-specific +diffs against B<Configure>. If you make changes to Configure, you may +want to consider regenerating this diff file to save trouble for the +OS/2 maintainer. + +=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>. + +The Perl version number appears in several places under F<vms>. +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 + +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 + +=head2 Making a new patch + +I find the F<makepatch> utility quite handy for making patches. +You can obtain it from any CPAN archive under +http://www.perl.com/CPAN/authors/Johan_Vromans/. The only +difference between my version and the standard one is that I have mine +do a + + # Print a reassuring "End of Patch" note so people won't + # wonder if their mailer truncated patches. + print "\n\nEnd of Patch.\n"; + +at the end. That's because I used to get questions from people asking if +their mail was truncated. + +Here's how I generate a new patch. I'll use the hypothetical +5.004_07 to 5.004_08 patch as an example. + + # unpack perl5.004_07/ + gzip -d -c perl5.004_07.tar.gz | tar -xof - + # unpack perl5.004_08/ + gzip -d -c perl5.004_08.tar.gz | tar -xof - + makepatch perl5.004_07 perl5.004_08 > perl5.004_08.pat + +Makepatch will automatically generate appropriate B<rm> commands to remove +deleted files. Unfortunately, it will not correctly set permissions +for newly created files, so you may have to do so manually. For example, +patch 5.003_04 created a new test F<t/op/gv.t> which needs to be executable, +so at the top of the patch, I inserted the following lines: + + # Make a new test + touch t/op/gv.t + chmod +x t/opt/gv.t + +Now, of course, my patch is now wrong because makepatch didn't know I +was going to do that command, and it patched against /dev/null. + +So, what I do is sort out all such shell commands that need to be in the +patch (including possible mv-ing of files, if needed) and put that in the +shell commands at the top of the patch. Next, I delete all the patch parts +of perl5.004_08.pat, leaving just the shell commands. Then, I do the +following: + + cd perl5.003_07 + sh ../perl5.003_08.pat + cd .. + makepatch perl5.003_07 perl5.003_08 >> perl5.003_08.pat + +(Note the append to preserve my shell commands.) +Now, my patch will line up with what the end users are going to do. + +=head2 Testing your patch + +It seems obvious, but be sure to test your patch. That is, verify that +it produces exactly the same thing as your full distribution. + + rm -rf perl5.003_07 + gzip -d -c perl5.003_07.tar.gz | tar -xf - + cd perl5.003_07 + sh ../perl5.003_08.pat + patch -p1 -N < ../perl5.003_08.pat + cd .. + gdiff -r perl5.003_07 perl5.003_08 + +where B<gdiff> is GNU diff. Other diff's may also do recursive checking. + +=head2 More testing + +Again, it's obvious, but you should test your new version as widely as you +can. You can be sure you'll hear about it quickly if your version doesn't +work on both ANSI and pre-ANSI compilers, and on common systems such as +SunOS 4.1.[34], Solaris, and Linux. + +If your changes include conditional code, try to test the different +branches as thoroughly as you can. For example, if your system +supports dynamic loading, you can also test static loading with + + sh Configure -Uusedl + +You can also hand-tweak your config.h to try out different #ifdef +branches. + +=head1 Common Gotcha's + +=over 4 + +=item #elif + +The '#elif' preprocessor directive is not understood on all systems. +Specifically, I know that Pyramids don't understand it. Thus instead of the +simple + + #if defined(I_FOO) + # include <foo.h> + #elif defined(I_BAR) + # include <bar.h> + #else + # include <fubar.h> + #endif + +You have to do the more Byzantine + + #if defined(I_FOO) + # include <foo.h> + #else + # if defined(I_BAR) + # include <bar.h> + # else + # include <fubar.h> + # endif + #endif + +Incidentally, whitespace between the leading '#' and the preprocessor +command is not guaranteed, but is very portable and you may use it freely. +I think it makes things a bit more readable, especially once things get +rather deeply nested. I also think that things should almost never get +too deeply nested, so it ought to be a moot point :-) + +=item Probably Prefer POSIX + +It's often the case that you'll need to choose whether to do +something the BSD-ish way or the POSIX-ish way. It's usually not +a big problem when the two systems use different names for similar +functions, such as memcmp() and bcmp(). The perl.h header file +handles these by appropriate #defines, selecting the POSIX mem*() +functions if available, but falling back on the b*() functions, if +need be. + +More serious is the case where some brilliant person decided to +use the same function name but give it a different meaning or +calling sequence :-). getpgrp() and setpgrp() come to mind. +These are a real problem on systems that aim for conformance to +one standard (e.g. POSIX), but still try to support the other way +of doing things (e.g. BSD). My general advice (still not really +implemented in the source) is to do something like the following. +Suppose there are two alternative versions, fooPOSIX() and +fooBSD(). + + #ifdef HAS_FOOPOSIX + /* use fooPOSIX(); */ + #else + # ifdef HAS_FOOBSD + /* try to emulate fooPOSIX() with fooBSD(); + perhaps with the following: */ + # define fooPOSIX fooBSD + # else + # /* Uh, oh. We have to supply our own. */ + # define fooPOSIX Perl_fooPOSIX + # endif + #endif + +=item Think positively + +If you need to add an #ifdef test, it is usually easier to follow if you +think positively, e.g. + + #ifdef HAS_NEATO_FEATURE + /* use neato feature */ + #else + /* use some fallback mechanism */ + #endif + +rather than the more impenetrable + + #ifndef MISSING_NEATO_FEATURE + /* Not missing it, so we must have it, so use it */ + #else + /* Are missing it, so fall back on something else. */ + #endif + +Of course for this toy example, there's not much difference. But when +the #ifdef's start spanning a couple of screen fulls, and the #else's +are marked something like + + #else /* !MISSING_NEATO_FEATURE */ + +I find it easy to get lost. + +=item Providing Missing Functions -- Problem + +Not all systems have all the neat functions you might want or need, so +you might decide to be helpful and provide an emulation. This is +sound in theory and very kind of you, but please be careful about what +you name the function. Let me use the C<pause()> function as an +illustration. + +Perl5.003 has the following in F<perl.h> + + #ifndef HAS_PAUSE + #define pause() sleep((32767<<16)+32767) + #endif + +Configure sets HAS_PAUSE if the system has the pause() function, so +this #define only kicks in if the pause() function is missing. +Nice idea, right? + +Unfortunately, some systems apparently have a prototype for pause() +in F<unistd.h>, but don't actually have the function in the library. +(Or maybe they do have it in a library we're not using.) + +Thus, the compiler sees something like + + extern int pause(void); + /* . . . */ + #define pause() sleep((32767<<16)+32767) + +and dies with an error message. (Some compilers don't mind this; +others apparently do.) + +To work around this, 5.003_03 and later have the following in perl.h: + + /* Some unistd.h's give a prototype for pause() even though + HAS_PAUSE ends up undefined. This causes the #define + below to be rejected by the compiler. Sigh. + */ + #ifdef HAS_PAUSE + # define Pause pause + #else + # define Pause() sleep((32767<<16)+32767) + #endif + +This works. + +The curious reader may wonder why I didn't do the following in +F<util.c> instead: + + #ifndef HAS_PAUSE + void pause() + { + sleep((32767<<16)+32767); + } + #endif + +That is, since the function is missing, just provide it. +Then things would probably be been alright, it would seem. + +Well, almost. It could be made to work. The problem arises from the +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<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. + +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 +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<embed.h> file. +This file is built from the F<global.sym> and F<interp.sym> files, +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 +line + + #define pause Perl_pause + +and calls to C<pause> in the perl sources would now point to +C<Perl_pause>. Now, when B<ld> is run to build the F<perl> executable, +it will go looking for C<perl_pause>, which probably won't exist in any +of the standard libraries. Thus the build of perl will fail. + +Those systems where C<HAS_PAUSE> is not defined would be ok, however, +since they would get a C<Perl_pause> function in util.c. The rest of +the world would be in trouble. + +And yes, this scenario has happened. On SCO, the function C<chsize> +is available. (I think it's in F<-lx>, the Xenix compatibility +library.) Since the perl4 days (and possibly before), Perl has +included a C<chsize> function that gets called something akin to + + #ifndef HAS_CHSIZE + I32 chsize(fd, length) + /* . . . */ + #endif + +When 5.003 added + + #define chsize Perl_chsize + +to F<embed.h>, the compile started failing on SCO systems. + +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 + # 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 :-). + +Now, we can safely put C<my_chsize> in F<global.sym>, export it, and +hide it with F<embed.h>. + +To be consistent with what I did for C<pause>, I probably should have +called the new function C<Chsize>, rather than C<my_chsize>. +However, the perl sources are quite inconsistent on this (Consider +New, Mymalloc, and Myremalloc, to name just a few.) + +There is a problem with this fix, however, in that C<Perl_chsize> +was available as a F<libperl.a> library function in 5.003, but it +isn't available any more (as of 5.003_07). This means that we've +broken binary compatibility. This is not good. + +=item Providing missing functions -- some ideas + +We currently don't have a standard way of handling such missing +function names. Right now, I'm effectively thinking aloud about a +solution. Some day, I'll try to formally propose a solution. + +Part of the problem is that we want to have some functions listed as +exported but not have their names mangled by embed.h or possibly +conflict with names in standard system headers. We actually already +have such a list at the end of F<perl_exp.SH> (though that list is +out-of-date): + + # extra globals not included above. + cat <<END >> perl.exp + perl_init_ext + perl_init_fold + perl_init_i18nl14n + perl_alloc + perl_construct + perl_destruct + perl_free + perl_parse + perl_run + perl_get_sv + perl_get_av + perl_get_hv + perl_get_cv + perl_call_argv + perl_call_pv + perl_call_method + perl_call_sv + perl_requirepv + safecalloc + safemalloc + saferealloc + safefree + +This still needs much thought, but I'm inclined to think that one +possible solution is to prefix all such functions with C<perl_> in the +source and list them along with the other C<perl_*> functions in +F<perl_exp.SH>. + +Thus, for C<chsize>, we'd do something like the following: + + /* in perl.h */ + #ifdef HAS_CHSIZE + # define perl_chsize chsize + #endif + +then in some file (e.g. F<util.c> or F<doio.c>) do + + #ifndef HAS_CHSIZE + I32 perl_chsize(fd, length) + /* implement the function here . . . */ + #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 +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 +probably a good alternative. (As a counter-example, note how Configure +and perl have to go through hoops to find and use get Malloc_t and +Free_t for C<malloc> and C<free>.) + +At the moment, this latter option is what I tend to prefer. + +=item All the world's a VAX + +Sorry, showing my age:-). Still, all the world is not BSD 4.[34], +SVR4, or POSIX. Be aware that SVR3-derived systems are still quite +common (do you have any idea how many systems run SCO?) If you don't +have a bunch of v7 manuals handy, the metaconfig units (by default +installed in F</usr/local/lib/dist/U>) are a good resource to look at +for portability. + +=back + +=head1 Miscellaneous Topics + +=head2 Autoconf + +Why does perl use a metaconfig-generated Configure script instead of an +autoconf-generated configure script? + +Metaconfig and autoconf are two tools with very similar purposes. +Metaconfig is actually the older of the two, and was originally written +by Larry Wall, while autoconf is probably now used in a wider variety of +packages. The autoconf info file discusses the history of autoconf and +how it came to be. The curious reader is referred there for further +information. + +Overall, both tools are quite good, I think, and the choice of which one +to use could be argued either way. In March, 1994, when I was just +starting to work on Configure support for Perl5, I considered both +autoconf and metaconfig, and eventually decided to use metaconfig for the +following reasons: + +=over 4 + +=item Compatibility with Perl4 + +Perl4 used metaconfig, so many of the #ifdef's were already set up for +metaconfig. Of course metaconfig had evolved some since Perl4's days, +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 +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 +cases.) At the time, I actually fetched a large number of GNU packages +and checked. Not a single one configured and compiled correctly +out-of-the-box with the system's cc compiler. + +=item Configure can be interactive + +With both autoconf and metaconfig, if the script works, everything is +fine. However, one of my main problems with autoconf-generated scripts +was that if it guessed wrong about something, it could be B<very> hard to +go back and fix it. For example, autoconf always insisted on passing the +-Xp flag to cc (to turn on POSIX behavior), even when that wasn't what I +wanted or needed for that package. There was no way short of editing the +configure script to turn this off. You couldn't just edit the resulting +Makefile at the end because the -Xp flag influenced a number of other +configure tests. + +Metaconfig's Configure scripts, on the other hand, can be interactive. +Thus if Configure is guessing things incorrectly, you can go back and fix +them. This isn't as important now as it was when we were actively +developing Configure support for new features such as dynamic loading, +but it's still useful occasionally. + +=item GPL + +At the time, autoconf-generated scripts were covered under the GNU Public +License, and hence weren't suitable for inclusion with Perl, which has a +different licensing policy. (Autoconf's licensing has since changed.) + +=item Modularity + +Metaconfig builds up Configure from a collection of discrete pieces +called "units". You can override the standard behavior by supplying your +own unit. With autoconf, you have to patch the standard files instead. +I find the metaconfig "unit" method easier to work with. Others +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<sh Configure -Dprefix=/opt/perl> 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<INSTALL> 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 +"making one" involves changing perl.c, Configure, config_h.SH (and +associated files, see above), and I<documenting> it all in the +INSTALL file. + +Apparently, most folks who want to override one of the standard library +files simply do it by overwriting the standard library files. + +=head2 APPLLIB + +In the perl.c sources, you'll find an undocumented APPLLIB_EXP +variable, sort of like PRIVLIB_EXP and ARCHLIB_EXP (which are +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. + + 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... :-) + +Given that it's already there, you can use it to override +distribution modules. If you do + + sh Configure -Dccflags='-DAPPLLIB_EXP=/my/override' + +then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB. + +=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 +_PAUSE_, the Perl Author's Upload Server. + +I typically upload both the patch file, e.g. F<perl5.004_08.pat.gz> +and the full tar file, e.g. F<perl5.004_08.tar.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.perl.com/CPAN/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 + +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 + +=over 4 + +=item installprefix + +I think we ought to support + + Configure -Dinstallprefix=/blah/blah + +Currently, we support B<-Dprefix=/blah/blah>, but the changing the install +location has to be handled by something like the F<config.over> trick +described in F<INSTALL>. AFS users also are treated specially. +We should probably duplicate the metaconfig prefix stuff for an +install prefix. + +=item Configure -Dsrcdir=/blah/blah + +We should be able to emulate B<configure --srcdir>. Tom Tromey +tromey@creche.cygnus.com has submitted some patches to +the dist-users mailing list along these lines. Eventually, they ought +to get folded back into the main distribution. + +=item Hint file fixes + +Various hint files work around Configure problems. We ought to fix +Configure so that most of them aren't needed. + +=item Hint file information + +Some of the hint file information (particularly dynamic loading stuff) +ought to be fed back into the main metaconfig distribution. + +=back + +=head2 Probably good ideas waiting for round tuits + +=over 4 + +=item GNU configure --options + +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<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. + +=item bypassing safe*alloc wrappers + +On some systems, it may be safe to call the system malloc directly +without going through the util.c safe* layers. (Such systems would +accept free(0), for example.) This might be a time-saver for systems +that already have a good malloc. (Recent Linux libc's apparently have +a nice malloc that is well-tuned for the system.) + +=back + +=head2 Vague possibilities + +=over 4 + +=item Win95, WinNT, and Win32 support + +We need to get something into the distribution for 32-bit Windows. +I'm tired of all the private e-mail questions I get, and I'm saddened +that so many folks keep trying to reinvent the same wheel. + +=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 +cases of coercion between string and numerical values. + +=item long long + +Can we support C<long long> on systems where C<long long> is larger +than what we've been using for C<IV>? What if you can't C<sprintf> +a C<long long>? + +=item Improve makedepend + +The current makedepend process is clunky and annoyingly slow, but it +works for most folks. Alas, it assumes that there is a filename +$firstmakefile that the B<make> command will try to use before it uses +F<Makefile>. Such may not be the case for all B<make> commands, +particularly those on non-Unix systems. + +Probably some variant of the BSD F<.depend> file will be useful. +We ought to check how other packages do this, if they do it at all. +We could probably pre-generate the dependencies (with the exception of +malloc.o, which could probably be determined at F<Makefile.SH> +extraction time. + +=item GNU Makefile standard targets + +GNU software generally has standardized Makefile targets. Unless we +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. + +=back + +=head1 AUTHOR + +Andy Dougherty <doughera@lafcol.lafayette.edu>. + +Additions by Chip Salzenberg <chip@atlantic.net>. + +All opinions expressed herein are those of the authorZ<>(s). + +=head1 LAST MODIFIED + +$Id: pumpkin.pod,v 1.8 1997/02/18 18:19:20 chip Released $ diff --git a/README.os2 b/README.os2 index e6782e3dc1..c0a19601f3 100644 --- a/README.os2 +++ b/README.os2 @@ -27,9 +27,9 @@ A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip -in F<?:\JUST_ADD\view.exe>. This gives one an access to B<EMX>'s +in F<?:\JUST_ADD\view.exe>. This gives one an access to EMX's F<.INF> docs as well (text form is available in F</emx/doc> in -B<EMX>'s distribution). +EMX's distribution). =cut @@ -43,12 +43,13 @@ Contents - Target - Other OSes - Prerequisites - - Starting Perl programs under OS/2 - - Starting OS/2 programs under Perl + - Starting Perl programs under OS/2 (and DOS and...) + - Starting OS/2 (and DOS) programs under Perl Frequently asked questions - I cannot run external programs - I cannot embed perl into my program, or use perl.dll from my program. - `` and pipe-open do not work under DOS. + - Cannot start find.exe "pattern" file INSTALLATION - Automatic binary installation - Manual binary installation @@ -77,9 +78,10 @@ Contents - Some problem (forget which ;-) - Library ... not found - Segfault in make - Specific (mis)features of OS/2 port + Specific (mis)features of EMX port - setpriority, getpriority - system() + - extproc on the first line - Additional modules: - Prebuilt methods: - Misfeatures @@ -113,7 +115,8 @@ Contents The target is to make OS/2 the best supported platform for using/building/developing Perl and I<Perl applications>, as well as -make Perl the best language to use under OS/2. +make Perl the best language to use under OS/2. The secondary target is +to try to make this work under DOS and Win* as well (but not B<too> hard). The current state is quite close to this target. Known limitations: @@ -131,10 +134,10 @@ to use PM code in your application (like the forthcoming Perl/Tk). =item * -There is no simple way to access B<WPS> objects. The only way I know +There is no simple way to access WPS objects. The only way I know is via C<OS2::REXX> extension (see L<OS2::REXX>), and we do not have access to -convenience methods of B<Object REXX>. (Is it possible at all? I know -of no B<Object-REXX> API.) +convenience methods of Object-REXX. (Is it possible at all? I know +of no Object-REXX API.) =back @@ -142,7 +145,7 @@ Please keep this list up-to-date by informing me about other items. =head2 Other OSes -Since OS/2 port of perl uses a remarkable B<EMX> environment, it can +Since OS/2 port of perl uses a remarkable EMX environment, it can run (and build extensions, and - possibly - be build itself) under any environment which can run EMX. The current list is DOS, DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors, @@ -150,7 +153,7 @@ only one works, see L<"perl_.exe">. Note that not all features of Perl are available under these environments. This depends on the features the I<extender> - most -probably C<RSX> - decided to implement. +probably RSX - decided to implement. Cf. L<Prerequisites>. @@ -158,19 +161,20 @@ Cf. L<Prerequisites>. =over 6 -=item B<EMX> +=item EMX -B<EMX> runtime is required (may be substituted by B<RSX>). Note that +EMX runtime is required (may be substituted by RSX). Note that it is possible to make F<perl_.exe> to run under DOS without any external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind>. Note -that under DOS for best results one should use B<RSX> runtime, which +that under DOS for best results one should use RSX runtime, which has much more functions working (like C<fork>, C<popen> and so on). In -fact B<RSX> is required if there is no C<VCPI> present. Note the -B<RSX> requires C<DPMI>. +fact RSX is required if there is no VCPI present. Note the +RSX requires DPMI. -Only the latest runtime is supported, currently C<0.9c>. +Only the latest runtime is supported, currently C<0.9c>. Perl may run +under earlier versions of EMX, but this is not tested. -One can get different parts of B<EMX> from, say +One can get different parts of EMX from, say ftp://ftp.cdrom.com/pub/os2/emx0.9c/ ftp://hobbes.nmsu.edu/os2/unix/gnu/ @@ -184,19 +188,19 @@ does not need to specify them explicitly (though this will work as well.) -=item B<RSX> +=item RSX -To run Perl on C<DPMI> platforms one needs B<RSX> runtime. This is +To run Perl on DPMI platforms one needs RSX runtime. This is needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see -L<"Other OSes">). B<RSX> would not work with C<VCPI> -only, as B<EMX> would, it requires C<DMPI>. +L<"Other OSes">). RSX would not work with VCPI +only, as EMX would, it requires DMPI. -Having B<RSX> and the latest F<sh.exe> one gets a fully functional +Having RSX and the latest F<sh.exe> one gets a fully functional B<*nix>-ish environment under DOS, say, C<fork>, C<``> and pipe-C<open> work. In fact, MakeMaker works (for static build), so one can have Perl development environment under DOS. -One can get B<RSX> from, say +One can get RSX from, say ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc @@ -207,18 +211,32 @@ The latest F<sh.exe> with DOS hooks is available at ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe -=item B<HPFS> +=item HPFS Perl does not care about file systems, but to install the whole perl library intact one needs a file system which supports long file names. Note that if you do not plan to build the perl itself, it may be -possible to fool B<EMX> to truncate file names. This is not supported, -read B<EMX> docs to see how to do it. +possible to fool EMX to truncate file names. This is not supported, +read EMX docs to see how to do it. + +=item pdksh + +To start external programs with complicated command lines (like with +pipes in between, and/or quoting of arguments), Perl uses an external +shell. With EMX port such shell should be named <sh.exe>, and located +either in the wired-in-during-compile locations (usually F<F:/bin>), +or in configurable location (see L<"PERL_SH_DIR">). + +For best results use EMX pdksh. The soon-to-be-available standard +binary (5.2.12?) runs under DOS (with L<RSX>) as well, meanwhile use +the binary from + + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe =back -=head2 Starting Perl programs under OS/2 +=head2 Starting Perl programs under OS/2 (and DOS and...) Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the same way as on any other platform, by @@ -230,33 +248,28 @@ opposed to to your program), use perl -my_opts foo.pl arg1 arg2 arg3 -Alternately, if you use OS/2-ish shell, like C<CMD> or C<4os2>, put +Alternately, if you use OS/2-ish shell, like CMD or 4os2, put the following at the start of your perl script: - extproc perl -x -S - #!/usr/bin/perl -my_opts + extproc perl -S -my_opts rename your program to F<foo.cmd>, and start it by typing foo arg1 arg2 arg3 -(Note that having *nixish full path to perl F</usr/bin/perl> is not -necessary, F<perl> would be enough, but having full path would make it -easier to use your script under *nix.) - Note that because of stupid OS/2 limitations the full path of the perl script is not available when you use C<extproc>, thus you are forced to use C<-S> perl switch, and your script should be on path. As a plus side, if you know a full path to your script, you may still start it with - perl -x ../../blah/foo.cmd arg1 arg2 arg3 + perl ../../blah/foo.cmd arg1 arg2 arg3 -(note that the argument C<-my_opts> is taken care of by the C<#!> line -in your script). +(note that the argument C<-my_opts> is taken care of by the C<extproc> line +in your script, see L<C<extproc> on the first line>). To understand what the above I<magic> does, read perl docs about C<-S> -and C<-x> switches - see L<perlrun>, and cmdref about C<extproc>: +switch - see L<perlrun>, and cmdref about C<extproc>: view perl perlrun man perlrun @@ -266,11 +279,11 @@ and C<-x> switches - see L<perlrun>, and cmdref about C<extproc>: or whatever method you prefer. There are also endless possibilities to use I<executable extensions> of -B<4OS2>, I<associations> of B<WPS> and so on... However, if you use +4os2, I<associations> of WPS and so on... However, if you use *nixish shell (like F<sh.exe> supplied in the binary distribution), you need to follow the syntax specified in L<perlrun/"Switches">. -=head2 Starting OS/2 programs under Perl +=head2 Starting OS/2 (and DOS) programs under Perl This is what system() (see L<perlfunc/system>), C<``> (see L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>) @@ -278,7 +291,7 @@ are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you do). Note however that to use some of these operators you need to have a -C<sh>-syntax shell installed (see L<"Pdksh">, +sh-syntax shell installed (see L<"Pdksh">, L<"Frequently asked questions">), and perl should be able to find it (see L<"PERL_SH_DIR">). @@ -296,7 +309,7 @@ meta-characters. =item Did you run your programs with C<-w> switch? See -L<Starting OS/2 programs under Perl>. +L<Starting OS/2 (and DOS) programs under Perl>. =item @@ -312,12 +325,12 @@ program. =over 4 -=item Is your program B<EMX>-compiled with C<-Zmt -Zcrtdll>? +=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>? If not, you need to build a stand-alone DLL for perl. Contact me, I did it once. Sockets would not work, as a lot of other stuff. -=item Did you use C<ExtUtils::Embed>? +=item Did you use L<ExtUtils::Embed>? I had reports it does not work. Somebody would need to fix it. @@ -326,12 +339,29 @@ I had reports it does not work. Somebody would need to fix it. =head2 C<``> and pipe-C<open> do not work under DOS. This may a variant of just L<"I cannot run external programs">, or a -deeper problem. Basically: you I<need> B<RSX> (see L<"Prerequisites">) +deeper problem. Basically: you I<need> RSX (see L<"Prerequisites">) for these commands to work, and you may need a port of F<sh.exe> which understands command arguments. One of such ports is listed in -L<"Prerequisites"> under B<RSX>. +L<"Prerequisites"> under RSX. Do not forget to set variable +C<L<"PERL_SH_DIR">> as well. + +DPMI is required for RSX. + +=head2 Cannot start C<find.exe "pattern" file> -C<DPMI> is required for B<RSX>. +Use one of + + system 'cmd', '/c', 'find "pattern" file'; + `cmd /c 'find "pattern" file'` + +This would start F<find.exe> via F<cmd.exe> via C<sh.exe> via +C<perl.exe>, but this is a price to pay if you want to use +non-conforming program. In fact F<find.exe> cannot be started at all +using C library API only. Otherwise the following command-lines were +equivalent: + + find "pattern" file + find pattern file =head1 INSTALLATION @@ -342,9 +372,9 @@ F<install.exe>. Just follow the instructions, and 99% of the installation blues would go away. Note however, that you need to have F<unzip.exe> on your path, and -B<EMX> environment I<running>. The latter means that if you just -installed B<EMX>, and made all the needed changes to F<Config.sys>, -you may need to reboot in between. Check B<EMX> runtime by running +EMX environment I<running>. The latter means that if you just +installed EMX, and made all the needed changes to F<Config.sys>, +you may need to reboot in between. Check EMX runtime by running emxrev @@ -358,7 +388,7 @@ B<Things not taken care of by automatic binary installation:> =item C<PERL_BADLANG> may be needed if you change your codepage I<after> perl installation, -and the new value is not supported by B<EMX>. See L<"PERL_BADLANG">. +and the new value is not supported by EMX. See L<"PERL_BADLANG">. =item C<PERL_BADFREE> @@ -377,19 +407,23 @@ data, please keep me informed if you find one. =back +B<NOTE>. Because of a typo the binary installer of 5.00305 +would install a variable C<PERL_SHPATH> into F<Config.sys>. Please +remove this variable and put C<L<PERL_SH_DIR>> instead. + =head2 Manual binary installation As of version 5.00305, OS/2 perl binary distribution comes split into 11 components. Unfortunately, to enable configurable binary -installation, the file paths in the C<zip> files are not absolute, but +installation, the file paths in the zip files are not absolute, but relative to some directory. Note that the extraction with the stored paths is still necessary -(default with C<unzip>, specify C<-d> to C<pkunzip>). However, you +(default with unzip, specify C<-d> to pkunzip). However, you need to know where to extract the files. You need also to manually change entries in F<Config.sys> to reflect where did you put the files. Note that if you have some primitive unzipper (like -C<pkunzip>), you may get a lot of warnings/errors during +pkunzip), you may get a lot of warnings/errors during unzipping. Upgrade to C<(w)unzip>. Below is the sample of what to do to reproduce the configuration on my @@ -402,20 +436,20 @@ machine: unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin unzip perl_exc.zip *.dll -d f:/emx.add/dll -(have the directories with C<*.exe> on C<PATH>, and C<*.dll> on -C<LIBPATH>); +(have the directories with C<*.exe> on PATH, and C<*.dll> on +LIBPATH); =item Perl_ VIO executable (statically linked) unzip perl_aou.zip -d f:/emx.add/bin -(have the directory on C<PATH>); +(have the directory on PATH); =item Executables for Perl utilities unzip perl_utl.zip -d f:/emx.add/bin -(have the directory on C<PATH>); +(have the directory on PATH); =item Main Perl library @@ -447,25 +481,25 @@ C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">. unzip perl_man.zip -d f:/perllib/man This directory should better be on C<MANPATH>. You need to have a -working C<man> to access these files. +working man to access these files. =item Manpages for Perl modules unzip perl_mam.zip -d f:/perllib/man This directory should better be on C<MANPATH>. You need to have a -working C<man> to access these files. +working man to access these files. =item Source for Perl documentation unzip perl_pod.zip -d f:/perllib/lib This is used by by C<perldoc> program (see L<perldoc>), and may be used to -generate B<HTML> documentation usable by WWW browsers, and +generate HTML documentation usable by WWW browsers, and documentation in zillions of other formats: C<info>, C<LaTeX>, C<Acrobat>, C<FrameMaker> and so on. -=item Perl manual in .INF format +=item Perl manual in F<.INF> format unzip perl_inf.zip -d d:/os2/book @@ -482,7 +516,7 @@ metacharacters>. It is also used instead of explicit F</bin/sh>. Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from the above location. -B<Note.> It may be possible to use some other C<sh>-compatible shell +B<Note.> It may be possible to use some other sh-compatible shell (I<not tested>). =back @@ -511,7 +545,7 @@ identical) Perl documentation in the following formats: =head2 OS/2 F<.INF> file -Most probably the most convenient form. View it as +Most probably the most convenient form. Under OS/2 view it as view perl view perl perlfunc @@ -519,7 +553,7 @@ Most probably the most convenient form. View it as view perl ExtUtils::MakeMaker (currently the last two may hit a wrong location, but this may improve -soon). +soon). Under Win* see L<"SYNOPSIS">. If you want to build the docs yourself, and have I<OS/2 toolkit>, run @@ -535,7 +569,7 @@ BOOKSHELF path. =head2 Plain text If you have perl documentation in the source form, perl utilities -installed, and B<GNU> C<groff> installed, you may use +installed, and GNU groff installed, you may use perldoc perlfunc perldoc less @@ -548,7 +582,7 @@ Alternately, try running pod2text on F<.pod> files. =head2 Manpages -If you have C<man> installed on your system, and you installed perl +If you have man installed on your system, and you installed perl manpages, use something like this: man perlfunc @@ -568,11 +602,11 @@ on our C<MANPATH>, like this set MANPATH=c:/man;f:/perllib/man -=head2 B<HTML> +=head2 HTML If you have some WWW browser available, installed the Perl documentation in the source form, and Perl utilities, you can build -B<HTML> docs. Cd to directory with F<.pod> files, and do like this +HTML docs. Cd to directory with F<.pod> files, and do like this cd f:/perllib/lib/pod pod2html @@ -582,11 +616,11 @@ directory, and go ahead with reading docs, like this: explore file:///f:/perllib/lib/pod/perl.html -Alternatively you may be able to get these docs prebuilt from C<CPAN>. +Alternatively you may be able to get these docs prebuilt from CPAN. -=head2 B<GNU> C<info> files +=head2 GNU C<info> files -Users of C<Emacs> would appreciate it very much, especially with +Users of Emacs would appreciate it very much, especially with C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>, or, alternately, prebuilt info pages. @@ -606,8 +640,8 @@ Here we discuss how to build Perl under OS/2. There is an alternative =head2 Prerequisites -You need to have the latest B<EMX> development environment, the full -B<GNU> tool suite (C<gawk> renamed to C<awk>, and B<GNU> F<find.exe> +You need to have the latest EMX development environment, the full +GNU tool suite (gawk renamed to awk, and GNU F<find.exe> earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to check use @@ -636,17 +670,17 @@ latter condition by if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>. -Make sure your C<gcc> is good for C<-Zomf> linking: run C<omflibs> +Make sure your gcc is good for C<-Zomf> linking: run C<omflibs> script in F</emx/lib> directory. -Check that you have C<link386> installed. It comes standard with OS/2, +Check that you have link386 installed. It comes standard with OS/2, but may be not installed due to customization. If typing link386 shows you do not have it, do I<Selective install>, and choose C<Link object modules> in I<Optional system utilities/More>. If you get into -C<link386>, press C<Ctrl-C>. +link386, press C<Ctrl-C>. =head2 Getting perl source @@ -675,10 +709,6 @@ Extract it like this You may see a message about errors while extracting F<Configure>. This is because there is a conflict with a similarly-named file F<configure>. -Rename F<configure> to F<configure.gnu>. Extract F<Configure> like this - - tar --case-sensitive -vzxf perl5.00409.tar.gz perl5.00409/Configure - Change to the directory of extraction. =head2 Application of the patches @@ -692,10 +722,10 @@ F<./os2/POSIX.mkfifo> like this: You may also need to apply the patches supplied with the binary distribution of perl. -Note also that the F<db.lib> and F<db.a> from the B<EMX> distribution +Note also that the F<db.lib> and F<db.a> from the EMX distribution are not suitable for multi-threaded compile (note that currently perl -is not multithreaded, but is compiled as multithreaded for -compatibility with B<XFree86>-OS/2). Get a corrected one from +is not multithread-safe, but is compiled as multithreaded for +compatibility with XFree86-OS/2). Get a corrected one from ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip @@ -708,12 +738,12 @@ wrong you find there. I do not expect it is needed anywhere. sh Configure -des -D prefix=f:/perllib -Prefix means where to install the resulting perl library. Giving +C<prefix> means: where to install the resulting perl library. Giving correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>, see L<"PERLLIB_PREFIX">. I<Ignore the message about missing C<ln>, and about C<-c> option to -C<tr>>. In fact if you can trace where the latter spurious warning +tr>. In fact if you can trace where the latter spurious warning comes from, please inform me. Now @@ -723,9 +753,11 @@ Now At some moment the built may die, reporting a I<version mismatch> or I<unable to run F<perl>>. This means that most of the build has been finished, and it is the time to move the constructed F<perl.dll> to -some I<absolute> location in C<LIBPATH>. After this done the build -should finish without a lot of fuss. I<One can avoid it if one has the -correct prebuilt version of F<perl.dll> on C<LIBPATH>.> +some I<absolute> location in LIBPATH. After this is done the build +should finish without a lot of fuss. I<One can avoid the interruption +if one has the correct prebuilt version of F<perl.dll> on LIBPATH, but +probably this is not needed anymore, since F<miniperl.exe> is linked +statically now.> Warnings which are safe to ignore: I<mkfifo() redefined> inside F<POSIX.c>. @@ -740,7 +772,7 @@ Some tests (4..6) should fail. Some perl invocations should end in a segfault (system error C<SYS3175>). To get finer error reports, cd t - perl -I ../lib harness + perl harness The report you get may look like @@ -753,11 +785,11 @@ The report you get may look like Failed 4/140 test scripts, 97.14% okay. 27/2937 subtests failed, 99.08% okay. Note that using `make test' target two more tests may fail: C<op/exec:1> -because of (mis)feature of C<pdksh>, and C<lib/posix:15>, which checks +because of (mis)feature of pdksh, and C<lib/posix:15>, which checks that the buffers are not flushed on C<_exit> (this is a bug in the test which assumes that tty output is buffered). -I submitted a patch to B<EMX> which makes it possible to fork() with EMX +I submitted a patch to EMX which makes it possible to fork() with EMX dynamic libraries loaded, which makes F<lib/io*> tests pass. This means that soon the number of failing tests may decrease yet more. @@ -791,12 +823,12 @@ know why this should or should not work. =item F<lib/io_pipe.t> -Checks C<IO::Pipe> module. Some feature of B<EMX> - test fork()s with +Checks C<IO::Pipe> module. Some feature of EMX - test fork()s with dynamic extension loaded - unsupported now. =item F<lib/io_sock.t> -Checks C<IO::Socket> module. Some feature of B<EMX> - test fork()s +Checks C<IO::Socket> module. Some feature of EMX - test fork()s with dynamic extension loaded - unsupported now. =item F<op/stat.t> @@ -869,14 +901,14 @@ Run It would put the generated files into needed locations. Manually put F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your -C<PATH>, F<perl.dll> to a location on your C<LIBPATH>. +PATH, F<perl.dll> to a location on your LIBPATH. Run make cmdscripts INSTALLCMDDIR=d:/ir/on/path to convert perl utilities to F<.cmd> files and put them on -C<PATH>. You need to put F<.EXE>-utilities on path manually. They are +PATH. You need to put F<.EXE>-utilities on path manually. They are installed in C<$prefix/bin>, here C<$prefix> is what you gave to F<Configure>, see L<Making>. @@ -891,7 +923,7 @@ test and install by make aout_test make aout_install -Manually put F<perl_.exe> to a location on your C<PATH>. +Manually put F<perl_.exe> to a location on your PATH. Since C<perl_> has the extensions prebuilt, it does not suffer from the I<dynamic extensions + fork()> syndrome, thus the failing tests @@ -921,13 +953,13 @@ You have a very old pdksh. See L<Prerequisites>. You do not have MT-safe F<db.lib>. See L<Prerequisites>. -=head2 Problems with C<tr> +=head2 Problems with tr -reported with very old version of C<tr>. +reported with very old version of tr. =head2 Some problem (forget which ;-) -You have an older version of F<perl.dll> on your C<LIBPATH>, which +You have an older version of F<perl.dll> on your LIBPATH, which broke the build of extensions. =head2 Library ... not found @@ -936,7 +968,7 @@ You did not run C<omflibs>. See L<Prerequisites>. =head2 Segfault in make -You use an old version of C<GNU> make. See L<Prerequisites>. +You use an old version of GNU make. See L<Prerequisites>. =head1 Specific (mis)features of OS/2 port @@ -952,6 +984,12 @@ Multi-argument form of C<system()> allows an additional numeric argument. The meaning of this argument is described in L<OS2::Process>. +=head2 C<extproc> on the first line + +If the first chars of a script are C<"extproc ">, this line is treated +as C<#!>-line, thus all the switches on this line are processed (twice +if script was started via cmd.exe). + =head2 Additional modules: L<OS2::Process>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. This @@ -999,7 +1037,7 @@ means changes with current dir. =item C<Cwd::sys_cwd(name)> -Interface to cwd from B<EMX>. Used by C<Cwd::cwd>. +Interface to cwd from EMX. Used by C<Cwd::cwd>. =item C<Cwd::sys_abspath(name, dir)> @@ -1031,7 +1069,7 @@ eventually). =item -Since <flock> is present in B<EMX>, but is not functional, the same is +Since <flock> is present in EMX, but is not functional, the same is true for perl. Here is the list of things which may be "broken" on EMX (from EMX docs): @@ -1054,7 +1092,7 @@ Since F<sh.exe> is used for globing (see L<perlfunc/glob>), the bugs of F<sh.exe> plague perl as well. In particular, uppercase letters do not work in C<[...]>-patterns with -the current C<pdksh>. +the current pdksh. =back @@ -1091,7 +1129,7 @@ C<os2_stat> special-cases F</dev/tty> and F</dev/con>. =head1 Perl flavors Because of idiosyncrasies of OS/2 one cannot have all the eggs in the -same basket (though C<EMX> environment tries hard to overcome this +same basket (though EMX environment tries hard to overcome this limitations, so the situation may somehow improve). There are 4 executables for Perl provided by the distribution: @@ -1099,12 +1137,12 @@ executables for Perl provided by the distribution: The main workhorse. This is a chimera executable: it is compiled as an C<a.out>-style executable, but is linked with C<omf>-style dynamic -library F<perl.dll>, and with dynamic B<CRT> DLL. This executable is a -C<VIO> application. +library F<perl.dll>, and with dynamic CRT DLL. This executable is a +VIO application. It can load perl dynamic extensions, and it can fork(). Unfortunately, -with the current version of B<EMX> it cannot fork() with dynamic -extensions loaded (may be fixed by patches to B<EMX>). +with the current version of EMX it cannot fork() with dynamic +extensions loaded (may be fixed by patches to EMX). B<Note.> Keep in mind that fork() is needed to open a pipe to yourself. @@ -1114,12 +1152,12 @@ This is a statically linked C<a.out>-style executable. It can fork(), but cannot load dynamic Perl extensions. The supplied executable has a lot of extensions prebuilt, thus there are situations when it can perform tasks not possible using F<perl.exe>, like fork()ing when -having some standard extension loaded. This executable is a C<VIO> +having some standard extension loaded. This executable is a VIO application. B<Note.> A better behaviour could be obtained from C<perl.exe> if it were statically linked with standard I<Perl extensions>, but -dynamically linked with the I<Perl DLL> and C<CRT> DLL. Then it would +dynamically linked with the I<Perl DLL> and CRT DLL. Then it would be able to fork() with standard extensions, I<and> would be able to dynamically load arbitrary extensions. Some changes to Makefiles and hint files should be necessary to achieve this. @@ -1131,27 +1169,27 @@ appropriate extender. See L<"Other OSes">. =head2 F<perl__.exe> -This is the same executable as <perl___.exe>, but it is a C<PM> +This is the same executable as F<perl___.exe>, but it is a PM application. -B<Note.> Usually C<STDIN>, C<STDERR>, and C<STDOUT> of a C<PM> +B<Note.> Usually STDIN, STDERR, and STDOUT of a PM application are redirected to C<nul>. However, it is possible to see them if you start C<perl__.exe> from a PM program which emulates a -console window, like I<Shell mode> of C<Emacs> or C<EPM>. Thus it I<is +console window, like I<Shell mode> of Emacs or EPM. Thus it I<is possible> to use Perl debugger (see L<perldebug>) to debug your PM application. -This flavor is required if you load extensions which use C<PM>, like +This flavor is required if you load extensions which use PM, like the forthcoming C<Perl/Tk>. =head2 F<perl___.exe> This is an C<omf>-style executable which is dynamically linked to -F<perl.dll> and C<CRT> DLL. I know no advantages of this executable +F<perl.dll> and CRT DLL. I know no advantages of this executable over C<perl.exe>, but it cannot fork() at all. Well, one advantage is that the build process is not so convoluted as with C<perl.exe>. -It is a C<VIO> application. +It is a VIO application. =head2 Why strange names? @@ -1191,16 +1229,16 @@ this DLL into memory and supplies command-arguments. This I<greatly> increases the load time for the application (as well as the number of problems during compilation). Since interpreter is in a DLL, -the C<CRT> is basically forced to reside in a DLL as well (otherwise -extensions would not be able to use C<CRT>). +the CRT is basically forced to reside in a DLL as well (otherwise +extensions would not be able to use CRT). =head2 Why chimera build? -Current C<EMX> environment does not allow DLLs compiled using Unixish +Current EMX environment does not allow DLLs compiled using Unixish C<a.out> format to export symbols for data. This forces C<omf>-style compile of F<perl.dll>. -Current C<EMX> environment does not allow F<.EXE> files compiled in +Current EMX environment does not allow F<.EXE> files compiled in C<omf> format to fork(). fork() is needed for exactly three Perl operations: @@ -1225,12 +1263,12 @@ F<perl.exe>. =head1 ENVIRONMENT -Here we list environment variables with are either OS/2-specific, or -are more important under OS/2 than under other OSes. +Here we list environment variables with are either OS/2- and DOS- and +Win*-specific, or are more important under OS/2 than under other OSes. =head2 C<PERLLIB_PREFIX> -Specific for OS/2. Should have the form +Specific for EMX port. Should have the form path1;path2 @@ -1258,12 +1296,12 @@ memory handling code is buggy. =head2 C<PERL_SH_DIR> -Specific for OS/2. Gives the directory part of the location for +Specific for EMX port. Gives the directory part of the location for F<sh.exe>. =head2 C<TMP> or C<TEMP> -Specific for OS/2. Used as storage place for temporary files, most +Specific for EMX port. Used as storage place for temporary files, most notably C<-e> scripts. =head1 Evolution @@ -1284,12 +1322,12 @@ caching DLLs. =head2 Threading -As of release 5.003_01 perl is linked to multithreaded C<CRT> +As of release 5.003_01 perl is linked to multithreaded CRT DLL. Perl itself is not multithread-safe, as is not perl malloc(). However, extensions may use multiple thread on their own risk. -Needed to compile C<Perl/Tk> for C<XFreeOS/2> out-of-the-box. +Needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box. =head2 Calls to external programs @@ -1307,9 +1345,11 @@ B<Reasons:> a consensus on C<perl5-porters> was that perl should use one non-overridable shell per platform. The obvious choices for OS/2 are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. Thus assures almost -100% compatibility with the scripts coming from *nix. +100% compatibility with the scripts coming from *nix. As an added benefit +this works as well under DOS if you use DOS-enabled port of pdksh +(see L<"Prerequisites">). -B<Disadvantages:> currently F<sh.exe> of C<pdksh> calls external programs +B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs via fork()/exec(), and there is I<no> functioning exec() on OS/2. exec() is emulated by EMX by asyncroneous call while the caller waits for child completion (to pretend that the C<pid> did not change). This @@ -1370,7 +1410,8 @@ there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI files - and maybe some other extensions at the time you read it. Note that OS2 perl defines 2 pseudo-extension functions -OS2::Copy::copy and DynaLoader::mod2fname. +OS2::Copy::copy and DynaLoader::mod2fname (many more now, see +L<Prebuilt methods>). The -R switch of older perl is deprecated. If you need to call a REXX code which needs access to variables, include the call into a REXX compartment @@ -667,6 +667,9 @@ dARGS (void)hv_iterinit(hv); /* always reset iterator regardless */ + if (op->op_private & OPpLEAVE_VOID) + RETURN; + if (GIMME != G_ARRAY) { I32 i; dTARGET; @@ -78,5 +78,3 @@ void Perl_DJGPP_init(); #define Stat(fname,bufptr) stat((fname),(bufptr)) #define Fstat(fd,bufptr) fstat((fd),(bufptr)) #define Fflush(fp) fflush(fp) - -#define my_getenv(var) getenv(var) @@ -13,7 +13,7 @@ struct gp { struct io * gp_io; /* filehandle value */ CV * gp_form; /* format value */ AV * gp_av; /* array value */ - HV * gp_hv; /* associative array value */ + HV * gp_hv; /* hash value */ GV * gp_egv; /* effective gv, if *glob */ CV * gp_cv; /* subroutine value */ U32 gp_cvgen; /* generational validity of cached gv_cv */ diff --git a/hints/solaris_2.sh b/hints/solaris_2.sh index d563e53d7b..255811f2a6 100644 --- a/hints/solaris_2.sh +++ b/hints/solaris_2.sh @@ -142,6 +142,7 @@ case "`${cc:-cc} -v 2>&1`" in NOTE: You are using GNU as(1). GNU as(1) will not build Perl. You must arrange to use /usr/ccs/bin/as, perhaps by setting GCC_EXEC_PREFIX or by including -B/usr/ccs/bin/ in your cc command. +(Note that the trailing "/" is required.) END ;; @@ -135,7 +135,7 @@ I32 lval; if (HvNAME(hv) && strEQ(HvNAME(hv),ENV_HV_NAME)) { char *gotenv; - gotenv = my_getenv(key); + gotenv = ENV_getenv(key); if (gotenv != NULL) { sv = newSVpv(gotenv,strlen(gotenv)); return hv_store(hv,key,klen,sv,hash); @@ -215,7 +215,7 @@ register U32 hash; if (HvNAME(hv) && strEQ(HvNAME(hv),ENV_HV_NAME)) { char *gotenv; - gotenv = my_getenv(key); + gotenv = ENV_getenv(key); if (gotenv != NULL) { sv = newSVpv(gotenv,strlen(gotenv)); return hv_store_ent(hv,keysv,sv,hash); @@ -854,7 +854,7 @@ HV *hv; HvNAME(hv) = 0; } xhv->xhv_array = 0; - xhv->xhv_max = 7; /* it's a normal associative array */ + xhv->xhv_max = 7; /* it's a normal hash */ xhv->xhv_fill = 0; xhv->xhv_keys = 0; @@ -866,10 +866,16 @@ I32 hv_iterinit(hv) HV *hv; { - register XPVHV* xhv = (XPVHV*)SvANY(hv); - HE *entry = xhv->xhv_eiter; + register XPVHV* xhv; + HE *entry; + + if (!hv) + croak("Bad hash"); + xhv = (XPVHV*)SvANY(hv); + entry = xhv->xhv_eiter; #ifdef DYNAMIC_ENV_FETCH /* set up %ENV for iteration */ - if (HvNAME(hv) && strEQ(HvNAME(hv),ENV_HV_NAME)) prime_env_iter(); + if (HvNAME(hv) && strEQ(HvNAME(hv), ENV_HV_NAME)) + prime_env_iter(); #endif if (entry && HvLAZYDEL(hv)) { /* was deleted earlier? */ HvLAZYDEL_off(hv); @@ -890,7 +896,7 @@ HV *hv; MAGIC* mg; if (!hv) - croak("Bad associative array"); + croak("Bad hash"); xhv = (XPVHV*)SvANY(hv); oldentry = entry = xhv->xhv_eiter; diff --git a/lib/Env.pm b/lib/Env.pm index 1f06bebf24..f2fe4af422 100644 --- a/lib/Env.pm +++ b/lib/Env.pm @@ -11,10 +11,9 @@ Env - perl module that imports environment variables =head1 DESCRIPTION -Perl maintains environment variables in a pseudo-associative-array -named %ENV. For when this access method is inconvenient, the Perl -module C<Env> allows environment variables to be treated as simple -variables. +Perl maintains environment variables in a pseudo-hash named %ENV. For +when this access method is inconvenient, the Perl module C<Env> allows +environment variables to be treated as simple variables. The Env::import() function ties environment variables with suitable names to global Perl variables with the same names. By default it diff --git a/lib/ExtUtils/MM_VMS.pm b/lib/ExtUtils/MM_VMS.pm index 12350aaab5..e719946f92 100644 --- a/lib/ExtUtils/MM_VMS.pm +++ b/lib/ExtUtils/MM_VMS.pm @@ -1978,7 +1978,14 @@ $(PERL_ARCHLIB)Config.pm : $(PERL_VMS)config.vms $(PERL_VMS)genconfig.pl $(NOECHO) Write Sys$Error "$(PERL_ARCHLIB)Config.pm may be out of date with config.vms or genconfig.pl" olddef = F$Environment("Default") Set Default $(PERL_SRC) - $(MMS)],$mmsquals,q[ $(MMS$TARGET) + $(MMS)],$mmsquals,); + if ($self->{PERL_ARCHLIB} =~ m|\[-| && $self->{PERL_SRC} =~ m|(\[-+)|) { + my($prefix,$target) = ($1,$self->fixpath('$(PERL_ARCHLIB)Config.pm')); + $target =~ s/\Q$prefix/[/; + push(@m," $target"); + } + else { push(@m,' $(MMS$TARGET)'); } + push(@m,q[ Set Default 'olddef' ]); } diff --git a/lib/ExtUtils/xsubpp b/lib/ExtUtils/xsubpp index 09b8e7dcd3..0cc8d785a7 100755 --- a/lib/ExtUtils/xsubpp +++ b/lib/ExtUtils/xsubpp @@ -79,11 +79,20 @@ require 5.002; use Cwd; use vars '$cplusplus'; +sub Q ; + # Global Constants -$XSUBPP_version = "1.9401"; -$Is_VMS = $^O eq 'VMS'; -sub Q ; +$XSUBPP_version = "1.9402"; + +my ($Is_VMS, $SymSet); +if ($^O eq 'VMS') { + $Is_VMS = 1; + # Establish set of global symbols with max length 28, since xsubpp + # will later add the 'XS_' prefix. + require ExtUtils::XSSymSet; + $SymSet = new ExtUtils::XSSymSet 28; +} $FH = 'File0000' ; @@ -127,13 +136,7 @@ $pwd = cwd(); my(@XSStack) = ({type => 'none'}); # Stack of conditionals and INCLUDEs my($XSS_work_idx, $cpp_next_tmp) = (0, "XSubPPtmpAAAA"); -my($SymSet); -if ($Is_VMS) { - # Establish set of global symbols with max length 28, since xsubpp - # will later add the 'XS_' prefix. - require ExtUtils::XSSymSet; - $SymSet = new ExtUtils::XSSymSet 28; -} + sub TrimWhitespace { diff --git a/lib/Test/Harness.pm b/lib/Test/Harness.pm index ba0683a02e..1bc791be3e 100644 --- a/lib/Test/Harness.pm +++ b/lib/Test/Harness.pm @@ -11,7 +11,7 @@ use vars qw($VERSION $verbose $switches $have_devel_corestack $curtest @ISA @EXPORT @EXPORT_OK); $have_devel_corestack = 0; -$VERSION = "1.15"; +$VERSION = "1.1501"; @ISA=('Exporter'); @EXPORT= qw(&runtests); @@ -60,9 +60,14 @@ sub runtests { chop($te); print "$te" . '.' x (20 - length($te)); my $fh = new FileHandle; - my $cmd = "$^X $switches $test|"; + $fh->open($test) or print "can't open $test. $!\n"; + my $first = <$fh>; + my $s = $switches; + $s .= " -T" if $first =~ /^#!.*\bperl.*-\w*T/; + $fh->close or print "can't close $test. $!\n"; + my $cmd = "$^X $s $test|"; $cmd = "MCR $cmd" if $^O eq 'VMS'; - $fh->open($cmd) or print "can't run. $!\n"; + $fh->open($cmd) or print "can't run $test. $!\n"; $ok = $next = $max = 0; @failed = (); while (<$fh>) { @@ -100,6 +105,7 @@ sub runtests { my $wstatus = $?; my $estatus = $^O eq 'VMS' ? $wstatus : $wstatus >> 8; if ($^O eq 'VMS' ? !($wstatus & 1) : $wstatus) { + my ($failed, $canon, $percent) = ('??', '??'); print "dubious\n\tTest returned status $estatus (wstat $wstatus)\n"; if (corestatus($wstatus)) { # until we have a wait module if ($have_devel_corestack) { @@ -109,9 +115,22 @@ sub runtests { } } $bad++; - $failedtests{$test} = { canon => '??', max => $max || '??', - failed => '??', - name => $test, percent => undef, + if ($max) { + if ($next == $max + 1 and not @failed) { + print "\tafter all the subtests completed successfully\n"; + $percent = 0; + $failed = 0; # But we do not set $canon! + } else { + push @failed, $next..$max; + $failed = @failed; + (my $txt, $canon) = canonfailed($max,@failed); + $percent = 100*(scalar @failed)/$max; + print "DIED. ",$txt; + } + } + $failedtests{$test} = { canon => $canon, max => $max || '??', + failed => $failed, + name => $test, percent => $percent, estat => $estatus, wstat => $wstatus, }; } elsif ($ok == $max && $next == $max+1) { @@ -186,6 +205,7 @@ sub runtests { return ($bad == 0 && $totmax) ; } +my $tried_devel_corestack; sub corestatus { my($st) = @_; my($ret); @@ -199,8 +219,8 @@ sub corestatus { $ret = WCOREDUMP($st); } - eval {require Devel::CoreStack}; - $have_devel_corestack++ unless $@; + eval { require Devel::CoreStack; $have_devel_corestack++ } + unless $tried_devel_corestack++; $ret; } diff --git a/lib/overload.pm b/lib/overload.pm index 0eb9702f82..c9044db0dc 100644 --- a/lib/overload.pm +++ b/lib/overload.pm @@ -588,9 +588,9 @@ function). =head1 BUGS -Because it is used for overloading, the per-package associative array -%OVERLOAD now has a special meaning in Perl. The symbol table is -filled with names looking like line-noise. +Because it is used for overloading, the per-package hash %OVERLOAD now +has a special meaning in Perl. The symbol table is filled with names +looking like line-noise. For the purpose of inheritance every overloaded package behaves as if C<fallback> is present (possibly undefined). This may create @@ -693,8 +693,6 @@ OP *op; case OP_AELEM: case OP_AELEMFAST: case OP_ASLICE: - case OP_VALUES: - case OP_KEYS: case OP_HELEM: case OP_HSLICE: case OP_UNPACK: @@ -817,6 +815,8 @@ OP *op; deprecate("implicit split to @_"); } break; + case OP_KEYS: + case OP_VALUES: case OP_DELETE: op->op_private |= OPpLEAVE_VOID; break; @@ -2949,11 +2949,11 @@ CV* outside; AvFLAGS(av) = AVf_REIFY; for (ix = AvFILL(protopad); ix > 0; ix--) { - SV* sv; - if (pname[ix] != &sv_undef) { - char *name = SvPVX(pname[ix]); /* XXX */ - if (SvFLAGS(pname[ix]) & SVf_FAKE) { /* lexical from outside? */ - I32 off = pad_findlex(name, ix, SvIVX(pname[ix]), + SV* namesv = pname[ix]; + if (namesv && namesv != &sv_undef) { + char *name = SvPVX(namesv); /* XXX */ + if (SvFLAGS(namesv) & SVf_FAKE) { /* lexical from outside? */ + I32 off = pad_findlex(name, ix, SvIVX(namesv), CvOUTSIDE(cv), cxstack_ix); if (!off) curpad[ix] = SvREFCNT_inc(ppad[ix]); @@ -2961,6 +2961,7 @@ CV* outside; croak("panic: cv_clone: %s", name); } else { /* our own lexical */ + SV* sv; if (*name == '&') { /* anon code -- we'll come back for it */ sv = SvREFCNT_inc(ppad[ix]); @@ -2977,7 +2978,7 @@ CV* outside; } } else { - sv = NEWSV(0,0); + SV* sv = NEWSV(0,0); SvPADTMP_on(sv); curpad[ix] = sv; } @@ -2986,9 +2987,11 @@ CV* outside; /* Now that vars are all in place, clone nested closures. */ for (ix = AvFILL(protopad); ix > 0; ix--) { - if (pname[ix] != &sv_undef - && !(SvFLAGS(pname[ix]) & SVf_FAKE) - && *SvPVX(pname[ix]) == '&' + SV* namesv = pname[ix]; + if (namesv + && namesv != &sv_undef + && !(SvFLAGS(namesv) & SVf_FAKE) + && *SvPVX(namesv) == '&' && CvCLONE(ppad[ix])) { CV *kid = cv_clone2((CV*)ppad[ix], cv); @@ -3075,6 +3078,11 @@ OP *block; SvPOK(cv) ? SvPV((SV*)cv,na) : "none", p ? p : "none"); } + if (!block) { + /* just a "sub foo;" when &foo is already defined */ + SAVEFREESV(compcv); + goto done; + } if (const_sv || dowarn) { line_t oldline = curcop->cop_line; curcop->cop_line = copline; @@ -3206,6 +3214,7 @@ OP *block; } } + done: copline = NOLINE; LEAVE_SCOPE(floor); return cv; @@ -838,9 +838,9 @@ EXT char *op_desc[] = { "keys", "delete", "exists operator", - "associative array deref", - "associative array elem", - "associative array slice", + "hash deref", + "hash elem", + "hash slice", "unpack", "pack", "split", @@ -358,16 +358,16 @@ aelemfast known array element ck_null s A S aelem array element ck_null s A S aslice array slice ck_null m A L -# Associative arrays. +# Hashes. each each ck_fun t H values values ck_fun t H keys keys ck_fun t H delete delete ck_delete 0 S exists exists operator ck_exists is S -rv2hv associative array deref ck_rvconst dt -helem associative array elem ck_null s H S -hslice associative array slice ck_null m H L +rv2hv hash deref ck_rvconst dt +helem hash elem ck_null s H S +hslice hash slice ck_null m H L # Explosives and implosives. diff --git a/os2/Changes b/os2/Changes index 4691e5bd35..15fad979f3 100644 --- a/os2/Changes +++ b/os2/Changes @@ -133,3 +133,13 @@ after 5.003_21: 'script.sh'. Form without extension will call shell only if the specified file exists (will not look on path) (to prohibit trying to run shell commands directly). - Needed by magic.t. + +after 5.003_27: + ALTERNATE_SHEBANG="extproc " supported, thus options on this + line are processed (possibly twice). -S is made legal on such + a line. This -S -x is not needed any more. + perl.dll may be used from non-EMX programs (via PERL_SYS_INIT + - the caller should have valid variable "env" with + environment). Known problems: $$ does not work - is 0, waitpid + returns immediately, thus Perl cannot wait for completion of + started programs. diff --git a/os2/OS2/PrfDB/t/os2_prfdb.t b/os2/OS2/PrfDB/t/os2_prfdb.t index a8c9752d36..b9f7d90ae2 100644 --- a/os2/OS2/PrfDB/t/os2_prfdb.t +++ b/os2/OS2/PrfDB/t/os2_prfdb.t @@ -88,6 +88,8 @@ print( OS2::Prf::Set($ini,'bbb', 'xxx','abc') ? "ok 18\n" : print( OS2::Prf::Set($ini,'bbb', 'yyy','456') ? "ok 19\n" : "not ok 19\n# err: `$^E'\n"); +OS2::Prf::Close($ini); + my %hash1; tie %hash1, 'OS2::PrfDB::Sub', $inifile, 'aaa'; @@ -1139,12 +1139,15 @@ Xs_OS2_init() OS2_Perl_data_t OS2_Perl_data; void -Perl_OS2_init() +Perl_OS2_init(char **env) { char *shell; settmppath(); OS2_Perl_data.xs_init = &Xs_OS2_init; + if (environ == NULL) { + environ = env; + } if ( (shell = getenv("PERL_SH_DRIVE")) ) { New(404, sh_path, strlen(SH_PATH) + 1, char); strcpy(sh_path, SH_PATH); diff --git a/os2/os2ish.h b/os2/os2ish.h index 7cf56fe79b..06a92a31fb 100644 --- a/os2/os2ish.h +++ b/os2/os2ish.h @@ -47,7 +47,7 @@ * (IOW, Perl won't hand off to another interpreter via an alternate * shebang sequence that might be legal Perl code.) */ -/* #define ALTERNATE_SHEBANG "#!" / **/ +#define ALTERNATE_SHEBANG "extproc " #ifndef SIGABRT # define SIGABRT SIGILL @@ -64,12 +64,14 @@ # undef I_SYS_UN #endif -void Perl_OS2_init(); +void Perl_OS2_init(char **); + +/* XXX This code hideously puts env inside: */ #define PERL_SYS_INIT(argcp, argvp) STMT_START { \ _response(argcp, argvp); \ _wildcard(argcp, argvp); \ - Perl_OS2_init(); } STMT_END + Perl_OS2_init(env); } STMT_END #define PERL_SYS_TERM() diff --git a/os2/perl2cmd.pl b/os2/perl2cmd.pl index c17ab761aa..e774f773d0 100644 --- a/os2/perl2cmd.pl +++ b/os2/perl2cmd.pl @@ -23,7 +23,7 @@ foreach $file (<$idir/*>) { $base =~ s|.*/||; $file =~ s|/|\\|g ; print "Processing $file => $dir\\$base.cmd\n"; - system 'cmd.exe', '/c', "echo extproc perl -Sx > $dir\\$base.cmd"; + system 'cmd.exe', '/c', "echo extproc perl -S >$dir\\$base.cmd"; system 'cmd.exe', '/c', "type $file >> $dir\\$base.cmd"; } diff --git a/patchlevel.h b/patchlevel.h index 5c392cac4b..0314619d6e 100644 --- a/patchlevel.h +++ b/patchlevel.h @@ -1,5 +1,5 @@ #define PATCHLEVEL 3 -#define SUBVERSION 27 +#define SUBVERSION 28 /* local_patches -- list of locally applied less-than-subversion patches. @@ -948,7 +948,7 @@ I32 flags; /* See G_* flags in cop.h */ { LOGOP myop; /* fake syntax tree node */ SV** sp = stack_sp; - I32 oldmark = TOPMARK; + I32 oldmark; I32 retval; Sigjmp_buf oldtop; I32 oldscope; @@ -959,20 +959,24 @@ I32 flags; /* See G_* flags in cop.h */ SAVETMPS; } + Zero(&myop, 1, LOGOP); + if (flags & G_NOARGS) { + PUSHMARK(sp); + } + else + myop.op_flags |= OPf_STACKED; + myop.op_next = Nullop; + myop.op_flags |= OPf_KNOW; + if (flags & G_ARRAY) + myop.op_flags |= OPf_LIST; SAVESPTR(op); op = (OP*)&myop; - Zero(op, 1, LOGOP); + EXTEND(stack_sp, 1); *++stack_sp = sv; + oldmark = TOPMARK; oldscope = scopestack_ix; - if (!(flags & G_NOARGS)) - myop.op_flags = OPf_STACKED; - myop.op_next = Nullop; - myop.op_flags |= OPf_KNOW; - if (flags & G_ARRAY) - myop.op_flags |= OPf_LIST; - if (perldb && curstash != debstash /* Handle first BEGIN of -d. */ && (DBcv || (DBcv = GvCV(DBsub))) @@ -1435,6 +1439,10 @@ GNU General Public License, which may be found in the Perl 5.0 source kit.\n\n") case '\n': case '\t': break; +#ifdef ALTERNATE_SHEBANG + case 'S': /* OS/2 needs -S on "extproc" line. */ + break; +#endif case 'P': if (preprocess) return s+1; @@ -1467,9 +1475,9 @@ my_unexec() # ifdef VMS # include <lib$routines.h> lib$signal(SS$_DEBUG); /* ssdef.h #included from vmsish.h */ -#else +# else ABORT(); /* for use with undump */ -#endif +# endif #endif } @@ -2332,6 +2340,11 @@ int addsubdirs; + sizeof("//auto")); New(55, archpat_auto, len, char); sprintf(archpat_auto, "/%s/%s/auto", ARCHNAME, patchlevel); +#ifdef VMS + for (len = sizeof(ARCHNAME) + 2; + archpat_auto[len] != '\0' && archpat_auto[len] != '/'; len++) + if (archpat_auto[len] == '.') archpat_auto[len] = '_'; +#endif } } @@ -2363,7 +2376,20 @@ int addsubdirs; */ if (addsubdirs) { struct stat tmpstatbuf; +#ifdef VMS + char *unix; + STRLEN len; + if ((unix = tounixspec_ts(SvPV(libdir,na),Nullch)) != Nullch) { + len = strlen(unix); + while (unix[len-1] == '/') len--; /* Cosmetic */ + sv_usepvn(libdir,unix,len); + } + else + PerlIO_printf(PerlIO_stderr(), + "Failed to unixify @INC element \"%s\"\n", + SvPV(libdir,na)); +#endif /* .../archname/version if -d .../archname/version/auto */ sv_setsv(subdir, libdir); sv_catpv(subdir, archpat_auto); diff --git a/perlsdio.h b/perlsdio.h index c3714410d6..f5c2921f38 100644 --- a/perlsdio.h +++ b/perlsdio.h @@ -32,10 +32,14 @@ ((*(f) && !((*(f))->_flag & _IONBF) && \ ((*(f))->_ptr > (*(f))->_base)) ? \ ((*(f))->_cnt++, *(--(*(f))->_ptr) = (c)) : decc$ungetc(c,f))) + /* Work around bug in DECCRTL/AXP (DECC v5.x) which causes read + * from a pipe after EOF has been returned once to hang. + */ +# define PerlIO_getc(f) (feof(f) ? EOF : getc(f)) #else # define PerlIO_ungetc(f,c) ungetc(c,f) +# define PerlIO_getc(f) getc(f) #endif -#define PerlIO_getc(f) getc(f) #define PerlIO_eof(f) feof(f) #define PerlIO_getname(f,b) fgetname(f,b) #define PerlIO_error(f) ferror(f) diff --git a/pod/perl.pod b/pod/perl.pod index e8522fe89b..302f58b94d 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -90,26 +90,28 @@ system management tasks. The language is intended to be practical (easy to use, efficient, complete) rather than beautiful (tiny, elegant, minimal). -Perl combines (in the author's opinion, anyway) some -of the best features of C, B<sed>, B<awk>, and B<sh>, so people -familiar with those languages should have little difficulty with it. -(Language historians will also note some vestiges of B<csh>, Pascal, -and even BASIC-PLUS.) Expression syntax corresponds quite closely to C +Perl combines (in the author's opinion, anyway) some of the best +features of C, B<sed>, B<awk>, and B<sh>, so people familiar with +those languages should have little difficulty with it. (Language +historians will also note some vestiges of B<csh>, Pascal, and even +BASIC-PLUS.) Expression syntax corresponds quite closely to C expression syntax. Unlike most Unix utilities, Perl does not arbitrarily limit the size of your data--if you've got the memory, -Perl can slurp in your whole file as a single string. Recursion is -of unlimited depth. And the hash tables used by associative arrays -grow as necessary to prevent degraded performance. Perl uses -sophisticated pattern matching techniques to scan large amounts of data -very quickly. Although optimized for scanning text, Perl can also -deal with binary data, and can make dbm files look like associative -arrays. Setuid Perl scripts are safer than -C programs through a dataflow tracing mechanism which prevents many -stupid security holes. If you have a problem that would ordinarily use -B<sed> or B<awk> or B<sh>, but it exceeds their capabilities or must -run a little faster, and you don't want to write the silly thing in C, -then Perl may be for you. There are also translators to turn your -B<sed> and B<awk> scripts into Perl scripts. +Perl can slurp in your whole file as a single string. Recursion is of +unlimited depth. And the tables used by hashes (previously called +"associative arrays") grow as necessary to prevent degraded +performance. Perl uses sophisticated pattern matching techniques to +scan large amounts of data very quickly. Although optimized for +scanning text, Perl can also deal with binary data, and can make dbm +files look like hashes. Setuid Perl scripts are safer than C programs +through a dataflow tracing mechanism which prevents many stupid +security holes. + +If you have a problem that would ordinarily use B<sed> or B<awk> or +B<sh>, but it exceeds their capabilities or must run a little faster, +and you don't want to write the silly thing in C, then Perl may be for +you. There are also translators to turn your B<sed> and B<awk> +scripts into Perl scripts. But wait, there's more... diff --git a/pod/perldelta.pod b/pod/perldelta.pod index ab5cde38ff..628ca22f27 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -34,6 +34,14 @@ application of opcode masks. The revised Safe module has a new API and is implemented using the new Opcode module. Please read the new Opcode and Safe documentation. +=head2 Fixed Parsing of $$<digit>, &$<digit>, etc. + +A bug in previous versions of Perl 5.0 prevented proper parsing of +numeric special variables as symbolic references. That bug has been +fixed. As a result, the string "$$0" is no longer equivalent to +C<$$."0">, but rather to C<${$0}>. To get the old behavior, change +"$$" followed by a digit to "${$}". + =head2 Internal Change: FileHandle Deprecated Filehandles are now stored internally as type IO::Handle. @@ -103,10 +111,9 @@ So "%hi" means "short integer in decimal", and "%ho" means =item keys as an lvalue As an lvalue, C<keys> allows you to increase the number of hash buckets -allocated for the given associative array. This can gain you a measure -of efficiency if you know the hash is going to get big. (This is -similar to pre-extending an array by assigning a larger number to -$#array.) If you say +allocated for the given hash. This can gain you a measure of efficiency if +you know the hash is going to get big. (This is similar to pre-extending +an array by assigning a larger number to $#array.) If you say keys %hash = 200; @@ -122,7 +129,7 @@ as trying has no effect). You can now use my() (with or without the parentheses) in the control expressions of control structures such as: - while (my $line = <>) { + while (defined(my $line = <>)) { $line = lc $line; } continue { print $line; @@ -331,15 +338,72 @@ possibly for cleaning up. =back -=item Efficiency Enhancements +=head2 Malloc Enhancements + +If perl's malloc() is used, you can print memory statistics at runtime +by running Perl thusly: + + env PERL_DEBUG_MSTATS=2 perl your_script_here + +The value of 2 means to print statistics after compilation and on +exit; with a value of 1, the statistics ares printed only on exit. +(If you want the statistics at an arbitrary time, you'll need to +install the optional module Devel::Peek.) + +In addition, three new compilation flags are recognized by malloc.c. +(They have no effect if perl is compiled with system malloc().) + +=over + +=item -DEMERGENCY_SBRK + +If this macro is defined, running out of memory need not be a fatal +error: a memory pool can allocated by assigning to the special +variable C<$^M>. See L<"$^M">. -All hash keys with the same string are only allocated once, so -even if you have 100 copies of the same hash, the immutable keys -never have to be re-allocated. +=item -DPACK_MALLOC + +Perl memory allocation is by bucket with sizes close to powers of two. +Because of these malloc overhead may be big, especially for data of +size exactly a power of two. If C<PACK_MALLOC> is defined, perl uses +a slightly different algorithm for small allocations (up to 64 bytes +long), which makes it possible to have overhead down to 1 byte for +allocations which are powers of two (and appear quite often). + +Expected memory savings (with 8-byte alignment in C<alignbytes>) is +about 20% for typical Perl usage. Expected slowdown due to additional +malloc overhead is in fractions of a percent (hard to measure, because +of the effect of saved memory on speed). + +=item -DTWO_POT_OPTIMIZE + +Similarly to C<PACK_MALLOC>, this macro improves allocations of data +with size close to a power of two; but this works for big allocations +(starting with 16K by default). Such allocations are typical for big +hashes and special-purpose scripts, especially image processing. + +On recent systems, the fact that perl requires 2M from system for 1M +allocation will not affect speed of execution, since the tail of such +a chunk is not going to be touched (and thus will not require real +memory). However, it may result in a premature out-of-memory error. +So if you will be manipulating very large blocks with sizes close to +powers of two, it would be wise to define this macro. + +Expected saving of memory is 0-100% (100% in applications which +require most memory in such 2**n chunks); expected slowdown is +negligible. + +=back + +=head2 Miscellaneous Efficiency Enhancements Functions that have an empty prototype and that do nothing but return a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>). +Each unique hash key is only allocated once, no matter how many hashes +have an entry with that key. So even if you have 100 copies of the +same hash, the hash keys never have to be re-allocated. + =head1 Pragmata Four new pragmatic modules exist: @@ -382,7 +446,7 @@ Disable unsafe opcodes, or any named opcodes, when compiling Perl code. =item use vmsish Enable VMS-specific language features. Currently, there are three -VMS-specific feature available: 'status', which makes C<$?> and +VMS-specific features available: 'status', which makes C<$?> and C<system> return genuine VMS status values instead of emulating POSIX; 'exit', which makes C<exit> take a genuine VMS status value instead of assuming that C<exit 1> is an error; and 'time', which makes all times diff --git a/pod/perldiag.pod b/pod/perldiag.pod index ec300c862b..394ffcbab3 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -267,10 +267,6 @@ shmctl(). In C parlance, the correct sizes are, respectively, S<sizeof(struct msqid_ds *)>, S<sizeof(struct semid_ds *)>, and S<sizeof(struct shmid_ds *)>. -=item Bad associative array - -(P) One of the internal hash routines was passed a null HV pointer. - =item Bad filehandle: %s (F) A symbol was passed to something wanting a filehandle, but the symbol @@ -288,6 +284,10 @@ This message can be quite often seen with DB_File on systems with C<Berkeley DB> which is left unnoticed if C<DB> uses I<forgiving> system malloc(). +=item Bad hash + +(P) One of the internal hash routines was passed a null HV pointer. + =item Bad name after %s:: (F) You started to name a symbol by using a package prefix, and then didn't diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 6825d22e7d..9d21587696 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -622,31 +622,31 @@ their own password: Of course, typing in your own password to whomever asks you for it is unwise. -=item dbmclose ASSOC_ARRAY +=item dbmclose HASH [This function has been superseded by the untie() function.] -Breaks the binding between a DBM file and an associative array. +Breaks the binding between a DBM file and a hash. -=item dbmopen ASSOC,DBNAME,MODE +=item dbmopen HASH,DBNAME,MODE [This function has been superseded by the tie() function.] -This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to an -associative array. ASSOC is the name of the associative array. (Unlike -normal open, the first argument is I<NOT> a filehandle, even though it -looks like one). DBNAME is the name of the database (without the F<.dir> -or F<.pag> extension if any). If the database does not exist, it is -created with protection specified by MODE (as modified by the umask()). -If your system supports only the older DBM functions, you may perform only -one dbmopen() in your program. In older versions of Perl, if your system -had neither DBM nor ndbm, calling dbmopen() produced a fatal error; it now -falls back to sdbm(3). - -If you don't have write access to the DBM file, you can only read -associative array variables, not set them. If you want to test whether -you can write, either use file tests or try setting a dummy array entry -inside an eval(), which will trap the error. +This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to a +hash. HASH is the name of the hash. (Unlike normal open, the first +argument is I<NOT> a filehandle, even though it looks like one). DBNAME +is the name of the database (without the F<.dir> or F<.pag> extension if +any). If the database does not exist, it is created with protection +specified by MODE (as modified by the umask()). If your system supports +only the older DBM functions, you may perform only one dbmopen() in your +program. In older versions of Perl, if your system had neither DBM nor +ndbm, calling dbmopen() produced a fatal error; it now falls back to +sdbm(3). + +If you don't have write access to the DBM file, you can only read hash +variables, not set them. If you want to test whether you can write, +either use file tests or try setting a dummy hash entry inside an eval(), +which will trap the error. Note that functions such as keys() and values() may return huge array values when used on large DBM files. You may prefer to use the each() @@ -677,8 +677,8 @@ a real null string, such as referencing elements of an array. You may also check to see if arrays or subroutines exist. Use of defined on predefined variables is not guaranteed to produce intuitive results. -When used on a hash array element, it tells you whether the value -is defined, not whether the key exists in the hash. Use exists() for that. +When used on a hash array element, it tells you whether the value is +defined, not whether the key exists in the hash. Use exists() for that. Examples: @@ -727,14 +727,14 @@ changed, fixed, or broken in a future release of Perl. =item delete EXPR -Deletes the specified key(s) and their associated values from a hash -array. For each key, returns the deleted value associated with that key, -or the undefined value if there was no such key. Deleting from C<$ENV{}> -modifies the environment. Deleting from an array tied to a DBM file +Deletes the specified key(s) and their associated values from a hash. +For each key, returns the deleted value associated with that key, or +the undefined value if there was no such key. Deleting from C<$ENV{}> +modifies the environment. Deleting from a hash tied to a DBM file deletes the entry from the DBM file. (But deleting from a tie()d hash doesn't necessarily return anything.) -The following deletes all the values of an associative array: +The following deletes all the values of a hash: foreach $key (keys %HASH) { delete $HASH{$key}; @@ -854,22 +854,23 @@ Example: QUICKSTART: Getopt('f'); -=item each ASSOC_ARRAY - -When called in a list context, returns a 2-element array consisting -of the key and value for the next element of an associative array, -so that you can iterate over it. When called in a scalar context, -returns the key for only the next element in the associative array. -Entries are returned in an apparently random order. When the array is -entirely read, a null array is returned in list context (which when -assigned produces a FALSE (0) value), and C<undef> is returned in a -scalar context. The next call to each() after that will start -iterating again. The iterator can be reset only by reading all the -elements from the array. You should not add elements to an array while -you're iterating over it. There is a single iterator for each -associative array, shared by all each(), keys(), and values() function -calls in the program. The following prints out your environment like -the printenv(1) program, only in a different order: +=item each HASH + +When called in a list context, returns a 2-element array consisting of the +key and value for the next element of a hash, so that you can iterate over +it. When called in a scalar context, returns the key for only the next +element in the hash. Entries are returned in an apparently random order. +When the hash is entirely read, a null array is returned in list context +(which when assigned produces a FALSE (0) value), and C<undef> is returned +in a scalar context. The next call to each() after that will start +iterating again. There is a single iterator for each hash, shared by all +each(), keys(), and values() function calls in the program; it can be +reset by reading all the elements from the hash, or by evaluating C<keys +HASH> or C<values HASH> in a scalar context. You should not add elements +to an hash while you're iterating over it. + +The following prints out your environment like the printenv(1) program, +only in a different order: while (($key,$value) = each %ENV) { print "$key=$value\n"; @@ -1573,14 +1574,15 @@ Example: See L<perlfunc/split>. -=item keys ASSOC_ARRAY +=item keys HASH + +Returns a normal array consisting of all the keys of the named hash. (In +a scalar context, returns the number of keys.) The keys are returned in +an apparently random order, but it is the same order as either the +values() or each() function produces (given that the hash has not been +modified). As a side effect, it resets HASH's iterator. -Returns a normal array consisting of all the keys of the named -associative array. (In a scalar context, returns the number of keys.) -The keys are returned in an apparently random order, but it is the same -order as either the values() or each() function produces (given that -the associative array has not been modified). Here is yet another way -to print your environment: +Here is yet another way to print your environment: @keys = keys %ENV; @values = values %ENV; @@ -1594,18 +1596,17 @@ or how about sorted by key: print $key, '=', $ENV{$key}, "\n"; } -To sort an array by value, you'll need to use a C<sort{}> -function. Here's a descending numeric sort of a hash by its values: +To sort an array by value, you'll need to use a C<sort{}> function. +Here's a descending numeric sort of a hash by its values: foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash)) { printf "%4d %s\n", $hash{$key}, $key; } As an lvalue C<keys> allows you to increase the number of hash buckets -allocated for the given associative array. This can gain you a measure -of efficiency if you know the hash is going to get big. (This is -similar to pre-extending an array by assigning a larger number to -$#array.) If you say +allocated for the given hash. This can gain you a measure of efficiency if +you know the hash is going to get big. (This is similar to pre-extending +an array by assigning a larger number to $#array.) If you say keys %hash = 200; @@ -2377,7 +2378,7 @@ If the referenced object has been blessed into a package, then that package name is returned instead. You can think of ref() as a typeof() operator. if (ref($r) eq "HASH") { - print "r is a reference to an associative array.\n"; + print "r is a reference to a hash.\n"; } if (!ref ($r) { print "r is not a reference at all.\n"; @@ -2832,8 +2833,8 @@ Examples: } @sortedclass = sort byage @class; - # this sorts the %age associative arrays by value - # instead of key using an in-line function + # this sorts the %age hash by value instead of key + # using an in-line function @eldest = sort { $age{$b} <=> $age{$a} } keys %age; sub backwards { $b cmp $a; } @@ -3369,8 +3370,7 @@ use the each() function to iterate over such. Example: } untie(%HIST); -A class implementing an associative array should have the following -methods: +A class implementing a hash should have the following methods: TIEHASH classname, LIST DESTROY this @@ -3475,7 +3475,7 @@ subroutine. Examples: undef $foo; undef $bar{'blurfl'}; undef @ary; - undef %assoc; + undef %hash; undef &mysub; return (wantarray ? () : undef) if $they_blew_it; @@ -3629,13 +3629,13 @@ to the current time. Example of a "touch" command: $now = time; utime $now, $now, @ARGV; -=item values ASSOC_ARRAY +=item values HASH -Returns a normal array consisting of all the values of the named -associative array. (In a scalar context, returns the number of -values.) The values are returned in an apparently random order, but it -is the same order as either the keys() or each() function would produce -on the same array. See also keys(), each(), and sort(). +Returns a normal array consisting of all the values of the named hash. +(In a scalar context, returns the number of values.) The values are +returned in an apparently random order, but it is the same order as either +the keys() or each() function would produce on the same hash. As a side +effect, it resets HASH's iterator. See also keys(), each(), and sort(). =item vec EXPR,OFFSET,BITS diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 3d16f94f25..77acc98aae 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -504,12 +504,12 @@ C<sv_2mortal> or C<sv_mortalcopy> routines. =head2 Stashes and Globs -A stash is a hash table (associative array) that contains all of the -different objects that are contained within a package. Each key of the -stash is a symbol name (shared by all the different types of objects -that have the same name), and each value in the hash table is called a -GV (for Glob Value). This GV in turn contains references to the various -objects of that name, including (but not limited to) the following: +A "stash" is a hash that contains all of the different objects that +are contained within a package. Each key of the stash is a symbol +name (shared by all the different types of objects that have the same +name), and each value in the hash table is a GV (Glob Value). This GV +in turn contains references to the various objects of that name, +including (but not limited to) the following: Scalar Value Array Value diff --git a/pod/perlmod.pod b/pod/perlmod.pod index b7383d23d3..9b649d6425 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -67,15 +67,15 @@ or L<perlref> regarding closures. =head2 Symbol Tables -The symbol table for a package happens to be stored in the associative -array of that name appended with two colons. The main symbol table's -name is thus C<%main::>, or C<%::> for short. Likewise symbol table for -the nested package mentioned earlier is named C<%OUTER::INNER::>. - -The value in each entry of the associative array is what you are referring -to when you use the C<*name> typeglob notation. In fact, the following -have the same effect, though the first is more efficient because it does -the symbol table lookups at compile time: +The symbol table for a package happens to be stored in the hash of that +name with two colons appended. The main symbol table's name is thus +C<%main::>, or C<%::> for short. Likewise symbol table for the nested +package mentioned earlier is named C<%OUTER::INNER::>. + +The value in each entry of the hash is what you are referring to when you +use the C<*name> typeglob notation. In fact, the following have the same +effect, though the first is more efficient because it does the symbol +table lookups at compile time: local(*main::foo) = *main::bar; local($main::{'foo'}) = $main::{'bar'}; diff --git a/pod/perlop.pod b/pod/perlop.pod index 55108f0328..88a8af0fd4 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -167,9 +167,8 @@ supposed to be searched, substituted, or translated instead of the default $_. The return value indicates the success of the operation. (If the right argument is an expression rather than a search pattern, substitution, or translation, it is interpreted as a search pattern at run -time. This is less efficient than an explicit search, because the pattern -must be compiled every time the expression is evaluated--unless you've -used C</o>.) +time. This can be is less efficient than an explicit search, because the +pattern must be compiled every time the expression is evaluated. Binary "!~" is just like "=~" except the return value is negated in the logical sense. @@ -1001,15 +1000,15 @@ always undergo shell expansion as well, see L<perlsec> for security concerns.) Evaluating a filehandle in angle brackets yields the next line from -that file (newline included, so it's never false until end of file, at -which time an undefined value is returned). Ordinarily you must assign -that value to a variable, but there is one situation where an automatic -assignment happens. I<If and ONLY if> the input symbol is the only -thing inside the conditional of a C<while> loop, the value is -automatically assigned to the variable C<$_>. The assigned value is -then tested to see if it is defined. (This may seem like an odd thing -to you, but you'll use the construct in almost every Perl script you -write.) Anyway, the following lines are equivalent to each other: +that file (newline, if any, included), or C<undef> at end of file. +Ordinarily you must assign that value to a variable, but there is one +situation where an automatic assignment happens. I<If and ONLY if> the +input symbol is the only thing inside the conditional of a C<while> or +C<for(;;)> loop, the value is automatically assigned to the variable +C<$_>. The assigned value is then tested to see if it is defined. +(This may seem like an odd thing to you, but you'll use the construct +in almost every Perl script you write.) Anyway, the following lines +are equivalent to each other: while (defined($_ = <STDIN>)) { print; } while (<STDIN>) { print; } diff --git a/pod/perlsec.pod b/pod/perlsec.pod index 2324b8a373..5961200f4d 100644 --- a/pod/perlsec.pod +++ b/pod/perlsec.pod @@ -20,11 +20,10 @@ mode explicitly by using the B<-T> command line flag. This flag is I<strongly> suggested for server programs and any program run on behalf of someone else, such as a CGI script. -While in this mode, Perl takes special precautions called I<taint -checks> to prevent both obvious and subtle traps. Some of these checks -are reasonably simple, such as verifying that path directories aren't -writable by others; careful programmers have always used checks like -these. Other checks, however, are best supported by the language itself, +While in this mode, Perl takes special precautions called I<taint checks> to +prevent both obvious and subtle traps. Some of these checks are reasonably +simple, such as not blindly using the PATH inherited from one's parent +process. Other checks, however, are best supported by the language itself, and it is these checks especially that contribute to making a setuid Perl program more secure than the corresponding C program. @@ -145,15 +144,13 @@ block. See L<perllocale/SECURITY> for further discussion and examples. =head2 Cleaning Up Your Path For "Insecure C<$ENV{PATH}>" messages, you need to set C<$ENV{'PATH'}> to a -known value, and each directory in the path must be non-writable by others -than its owner and group. You may be surprised to get this message even -if the pathname to your executable is fully qualified. This is I<not> -generated because you didn't supply a full path to the program; instead, -it's generated because you never set your PATH environment variable, or -you didn't set it to something that was safe. Because Perl can't -guarantee that the executable in question isn't itself going to turn -around and execute some other program that is dependent on your PATH, it -makes sure you set the PATH. +known value. You may be surprised to get this message even if the pathname +to your executable is fully qualified. This is I<not> generated because you +didn't supply a full path to the program; instead, it's generated because +you never set your PATH environment variable. Because Perl can't guarantee +that the executable in question isn't itself going to turn around and +execute some other program that is dependent on your PATH, it makes sure you +set the PATH. It's also possible to get into trouble with other operations that don't care whether they use tainted values. Make judicious use of the file diff --git a/pod/perltie.pod b/pod/perltie.pod index 13135c4ad5..dfc6894172 100644 --- a/pod/perltie.pod +++ b/pod/perltie.pod @@ -293,19 +293,18 @@ the following output demonstrates: =head2 Tying Hashes -As the first Perl data type to be tied (see dbmopen()), associative arrays -have the most complete and useful tie() implementation. A class -implementing a tied associative array should define the following -methods: TIEHASH is the constructor. FETCH and STORE access the key and -value pairs. EXISTS reports whether a key is present in the hash, and -DELETE deletes one. CLEAR empties the hash by deleting all the key and -value pairs. FIRSTKEY and NEXTKEY implement the keys() and each() -functions to iterate over all the keys. And DESTROY is called when the -tied variable is garbage collected. - -If this seems like a lot, then feel free to inherit from -merely the standard Tie::Hash module for most of your methods, redefining only -the interesting ones. See L<Tie::Hash> for details. +As the first Perl data type to be tied (see dbmopen()), hashes have the +most complete and useful tie() implementation. A class implementing a +tied hash should define the following methods: TIEHASH is the constructor. +FETCH and STORE access the key and value pairs. EXISTS reports whether a +key is present in the hash, and DELETE deletes one. CLEAR empties the +hash by deleting all the key and value pairs. FIRSTKEY and NEXTKEY +implement the keys() and each() functions to iterate over all the keys. +And DESTROY is called when the tied variable is garbage collected. + +If this seems like a lot, then feel free to inherit from merely the +standard Tie::Hash module for most of your methods, redefining only the +interesting ones. See L<Tie::Hash> for details. Remember that Perl distinguishes between a key not existing in the hash, and the key existing in the hash but having a corresponding value of diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 224ad5e863..992cd2c3f5 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -54,6 +54,8 @@ HOME, LOGDIR, PATH, PERL5LIB, PERL5DB, PERL_DESTRUCT_LEVEL, PERLLIB =item New Opcode Module and Revised Safe Module +=item Fixed Parsing of $$<digit>, &$<digit>, etc. + =item Internal Change: FileHandle Deprecated =item Internal Change: PerlIO internal IO abstraction interface @@ -76,8 +78,13 @@ isa(CLASS), can(METHOD), VERSION( [NEED] ) =item TIEHANDLE Now Supported -TIEHANDLE classname, LIST, PRINT this, LIST, READLINE this, DESTROY this, -Efficiency Enhancements +TIEHANDLE classname, LIST, PRINT this, LIST, READLINE this, DESTROY this + +=item Malloc Enhancements + +-DEMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE + +=item Miscellaneous Efficiency Enhancements =back @@ -346,11 +353,11 @@ binmode FILEHANDLE, bless REF,CLASSNAME, bless REF, caller EXPR, caller, chdir EXPR, chmod LIST, chomp VARIABLE, chomp LIST, chomp, chop VARIABLE, chop LIST, chop, chown LIST, chr NUMBER, chr, chroot FILENAME, chroot, close FILEHANDLE, closedir DIRHANDLE, connect SOCKET,NAME, continue BLOCK, -cos EXPR, crypt PLAINTEXT,SALT, dbmclose ASSOC_ARRAY, dbmopen -ASSOC,DBNAME,MODE, defined EXPR, defined, delete EXPR, die LIST, do BLOCK, -do SUBROUTINE(LIST), do EXPR, dump LABEL, each ASSOC_ARRAY, eof FILEHANDLE, -eof (), eof, eval EXPR, eval BLOCK, exec LIST, exists EXPR, exit EXPR, exp -EXPR, exp, fcntl FILEHANDLE,FUNCTION,SCALAR, fileno FILEHANDLE, flock +cos EXPR, crypt PLAINTEXT,SALT, dbmclose HASH, dbmopen HASH,DBNAME,MODE, +defined EXPR, defined, delete EXPR, die LIST, do BLOCK, do +SUBROUTINE(LIST), do EXPR, dump LABEL, each HASH, eof FILEHANDLE, eof (), +eof, eval EXPR, eval BLOCK, exec LIST, exists EXPR, exit EXPR, exp EXPR, +exp, fcntl FILEHANDLE,FUNCTION,SCALAR, fileno FILEHANDLE, flock FILEHANDLE,OPERATION, fork, format, formline PICTURE, LIST, getc FILEHANDLE, getc, getlogin, getpeername SOCKET, getpgrp PID, getppid, getpriority WHICH,WHO, getpwnam NAME, getgrnam NAME, gethostbyname NAME, @@ -364,24 +371,24 @@ endprotoent, endservent, getsockname SOCKET, getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob, gmtime EXPR, goto LABEL, goto EXPR, goto &NAME, grep BLOCK LIST, grep EXPR,LIST, hex EXPR, hex, import, index STR,SUBSTR,POSITION, index STR,SUBSTR, int EXPR, int, ioctl -FILEHANDLE,FUNCTION,SCALAR, join EXPR,LIST, keys ASSOC_ARRAY, kill LIST, -last LABEL, last, lc EXPR, lc, lcfirst EXPR, lcfirst, length EXPR, length, -link OLDFILE,NEWFILE, listen SOCKET,QUEUESIZE, local EXPR, localtime EXPR, -log EXPR, log, lstat FILEHANDLE, lstat EXPR, lstat, m//, map BLOCK LIST, -map EXPR,LIST, mkdir FILENAME,MODE, msgctl ID,CMD,ARG, msgget KEY,FLAGS, -msgsnd ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, my EXPR, next LABEL, -next, no Module LIST, oct EXPR, oct, open FILEHANDLE,EXPR, open FILEHANDLE, -opendir DIRHANDLE,EXPR, ord EXPR, ord, pack TEMPLATE,LIST, package -NAMESPACE, pipe READHANDLE,WRITEHANDLE, pop ARRAY, pop, pos SCALAR, pos, -print FILEHANDLE LIST, print LIST, print, printf FILEHANDLE FORMAT, LIST, -printf FORMAT, LIST, prototype FUNCTION, push ARRAY,LIST, q/STRING/, -qq/STRING/, qx/STRING/, qw/STRING/, quotemeta EXPR, quotemeta, rand EXPR, -rand, read FILEHANDLE,SCALAR,LENGTH,OFFSET, read FILEHANDLE,SCALAR,LENGTH, -readdir DIRHANDLE, readlink EXPR, readlink, recv SOCKET,SCALAR,LEN,FLAGS, -redo LABEL, redo, ref EXPR, ref, rename OLDNAME,NEWNAME, require EXPR, -require, reset EXPR, reset, return LIST, reverse LIST, rewinddir DIRHANDLE, -rindex STR,SUBSTR,POSITION, rindex STR,SUBSTR, rmdir FILENAME, rmdir, s///, -scalar EXPR, seek FILEHANDLE,POSITION,WHENCE, seekdir DIRHANDLE,POS, select +FILEHANDLE,FUNCTION,SCALAR, join EXPR,LIST, keys HASH, kill LIST, last +LABEL, last, lc EXPR, lc, lcfirst EXPR, lcfirst, length EXPR, length, link +OLDFILE,NEWFILE, listen SOCKET,QUEUESIZE, local EXPR, localtime EXPR, log +EXPR, log, lstat FILEHANDLE, lstat EXPR, lstat, m//, map BLOCK LIST, map +EXPR,LIST, mkdir FILENAME,MODE, msgctl ID,CMD,ARG, msgget KEY,FLAGS, msgsnd +ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, my EXPR, next LABEL, next, no +Module LIST, oct EXPR, oct, open FILEHANDLE,EXPR, open FILEHANDLE, opendir +DIRHANDLE,EXPR, ord EXPR, ord, pack TEMPLATE,LIST, package NAMESPACE, pipe +READHANDLE,WRITEHANDLE, pop ARRAY, pop, pos SCALAR, pos, print FILEHANDLE +LIST, print LIST, print, printf FILEHANDLE FORMAT, LIST, printf FORMAT, +LIST, prototype FUNCTION, push ARRAY,LIST, q/STRING/, qq/STRING/, +qx/STRING/, qw/STRING/, quotemeta EXPR, quotemeta, rand EXPR, rand, read +FILEHANDLE,SCALAR,LENGTH,OFFSET, read FILEHANDLE,SCALAR,LENGTH, readdir +DIRHANDLE, readlink EXPR, readlink, recv SOCKET,SCALAR,LEN,FLAGS, redo +LABEL, redo, ref EXPR, ref, rename OLDNAME,NEWNAME, require EXPR, require, +reset EXPR, reset, return LIST, reverse LIST, rewinddir DIRHANDLE, rindex +STR,SUBSTR,POSITION, rindex STR,SUBSTR, rmdir FILENAME, rmdir, s///, scalar +EXPR, seek FILEHANDLE,POSITION,WHENCE, seekdir DIRHANDLE,POS, select FILEHANDLE, select, select RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget KEY,NSEMS,FLAGS, semop KEY,OPSTRING, send SOCKET,MSG,FLAGS,TO, send SOCKET,MSG,FLAGS, setpgrp PID,PGRP, setpriority @@ -404,9 +411,8 @@ VARIABLE, time, times, tr///, truncate FILEHANDLE,LENGTH, truncate EXPR,LENGTH, uc EXPR, uc, ucfirst EXPR, ucfirst, umask EXPR, umask, undef EXPR, undef, unlink LIST, unlink, unpack TEMPLATE,EXPR, untie VARIABLE, unshift ARRAY,LIST, use Module LIST, use Module, use Module VERSION LIST, -use VERSION, utime LIST, values ASSOC_ARRAY, vec EXPR,OFFSET,BITS, wait, -waitpid PID,FLAGS, wantarray, warn LIST, write FILEHANDLE, write EXPR, -write, y/// +use VERSION, utime LIST, values HASH, vec EXPR,OFFSET,BITS, wait, waitpid +PID,FLAGS, wantarray, warn LIST, write FILEHANDLE, write EXPR, write, y/// =back diff --git a/pod/perltrap.pod b/pod/perltrap.pod index 4b56dd23d8..05cb02b47b 100644 --- a/pod/perltrap.pod +++ b/pod/perltrap.pod @@ -47,8 +47,7 @@ You have to decide whether your array has numeric or string indices. =item * -Associative array values do not spring into existence upon mere -reference. +Hash values do not spring into existence upon mere reference. =item * @@ -795,7 +794,7 @@ The behavior is slightly different for: =item * (Variable Suicide) Variable suicide behavior is more consistent under Perl 5. -Perl5 exhibits the same behavior for associative arrays and scalars, +Perl5 exhibits the same behavior for hashes and scalars, that perl4 exhibits for only scalars. $aGlobal{ "aKey" } = "global value"; diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 23c110d34e..d072d25df9 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -404,11 +404,14 @@ C<$? & 255> gives which signal, if any, the process died from, and whether there was a core dump. (Mnemonic: similar to B<sh> and B<ksh>.) +Note that if you have installed a signal handler for C<SIGCHLD>, the +value of C<$?> will usually be wrong outside that handler. + Inside an C<END> subroutine C<$?> contains the value that is going to be given to C<exit()>. You can modify C<$?> in an C<END> subroutine to change the exit status of the script. -Under VMS, the pragma C<use vmsish 'status'> make C<$?> reflect the +Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the actual VMS exit status, instead of the default emulation of POSIX status. @@ -154,12 +154,13 @@ PP(pp_backtick) TAINT_PROPER("``"); fp = my_popen(tmps, "r"); if (fp) { - sv_setpv(TARG, ""); /* note that this preserves previous buffer */ if (GIMME == G_SCALAR) { + sv_setpv(TARG, ""); /* note that this preserves previous buffer */ while (sv_gets(TARG, fp, SvCUR(TARG)) != Nullch) /*SUPPRESS 530*/ ; XPUSHs(TARG); + SvTAINTED_on(TARG); } else { SV *sv; @@ -175,9 +176,11 @@ PP(pp_backtick) SvLEN_set(sv, SvCUR(sv)+1); Renew(SvPVX(sv), SvLEN(sv), char); } + SvTAINTED_on(sv); } } STATUS_NATIVE_SET(my_pclose(fp)); + TAINT; /* "I believe that this is not gratuitous!" */ } else { STATUS_NATIVE_SET(-1); @@ -3048,7 +3051,7 @@ PP(pp_getpgrp) #ifdef BSD_GETPGRP value = (I32)BSD_GETPGRP(pid); #else - if (pid != 0 && pid != getpid()) { + if (pid != 0 && pid != getpid()) DIE("POSIX getpgrp can't take an argument"); value = (I32)getpgrp(); #endif @@ -3078,9 +3081,8 @@ PP(pp_setpgrp) #ifdef BSD_SETPGRP SETi( BSD_SETPGRP(pid, pgrp) >= 0 ); #else - if ((pgrp != 0 && pgrp != getpid())) || (pid != 0 && pid != getpid())) { + if ((pgrp != 0 && pgrp != getpid())) || (pid != 0 && pid != getpid())) DIE("POSIX setpgrp can't take an argument"); - } SETi( setpgrp() >= 0 ); #endif /* USE_BSDPGRP */ RETURN; @@ -126,6 +126,13 @@ if ($bad == 0) { ### of them individually and examine any diagnostic messages they ### produce. See the INSTALL document's section on "make test". SHRDLU + warn <<'SHRDLU' if $good / $total > 0.8; + ### + ### Since most tests were successful, you have a good chance to + ### get information with better granularity by running + ### ./perl harness + ### in directory ./t. +SHRDLU } ($user,$sys,$cuser,$csys) = times; print sprintf("u=%g s=%g cu=%g cs=%g scripts=%d tests=%d\n", @@ -3,9 +3,12 @@ # We suppose that perl _mostly_ works at this moment, so may use # sophisticated testing. -# Note that _before install_ you may need to run it with -I ../lib flag - +BEGIN { + chdir 't' if -d 't'; + @INC = '../lib'; +} use lib '../lib'; + use Test::Harness; $Test::Harness::switches = ""; # Too much noise otherwise diff --git a/t/op/closure.t b/t/op/closure.t index 04fb7a303a..7af3abb291 100755 --- a/t/op/closure.t +++ b/t/op/closure.t @@ -408,22 +408,31 @@ END } else { # No fork(). Do it the hard way. my $cmdfile = "tcmd$$"; $cmdfile++ while -e $cmdfile; - my $outfile = "tout$$"; $outfile++ while -e $outfile; my $errfile = "terr$$"; $errfile++ while -e $errfile; + my @tmpfiles = ($cmdfile, $errfile); open CMD, ">$cmdfile"; print CMD $code; close CMD; my $cmd = ($^O eq 'VMS') ? "MCR $^X" : "./perl"; - $cmd .= " -w $cmdfile >$outfile 2>$errfile"; - system $cmd; - $? = 0 if $^O eq 'VMS' and $? & 1; # Keep Unix-minded code below happy + $cmd .= " -w $cmdfile 2>$errfile"; + if ($^O eq 'VMS') { + # Use pipe instead of system so we don't inherit STD* from + # this process, and then foul our pipe back to parent by + # redirecting output in the child. + open PERL,"$cmd |" or die "Can't open pipe: $!\n"; + { local $/; $output = join '', <PERL> } + close PERL; + } else { + my $outfile = "tout$$"; $outfile++ while -e $outfile; + push @tmpfiles, $outfile; + system "$cmd >$outfile"; + { local $/; open IN, $outfile; $output = <IN>; close IN } + } if ($?) { printf "not ok: exited with error code %04X\n", $?; - $debugging or do { 1 while unlink $cmdfile, $outfile, $errfile }; + $debugging or do { 1 while unlink @tmpfiles }; exit; } - { local $/; - open IN, $outfile; $output = <IN>; close IN; - open IN, $errfile; $errors = <IN>; close IN; } - 1 while unlink $cmdfile, $outfile, $errfile; + { local $/; open IN, $errfile; $errors = <IN>; close IN } + 1 while unlink @tmpfiles; } print $output; print STDERR $errors; diff --git a/t/op/magic.t b/t/op/magic.t index bb65ae8b7a..f3e6ba3cc2 100755 --- a/t/op/magic.t +++ b/t/op/magic.t @@ -104,12 +104,10 @@ else { $wd = '.'; } $script = "$wd/show-shebang"; +$s1 = $s2 = "\$^X is $wd/perl, \$0 is $script\n"; if ($^O eq 'os2') { # Started by ksh, which adds suffixes '.exe' and '.' to perl and script - $s = "\$^X is $wd/perl.exe, \$0 is $script.\n"; -} -else { - $s = "\$^X is $wd/perl, \$0 is $script\n"; + $s2 = "\$^X is $wd/perl.exe, \$0 is $script.\n"; } ok 19, open(SCRIPT, ">$script"), $!; ok 20, print(SCRIPT <<EOB . <<'EOF'), $!; @@ -121,9 +119,9 @@ ok 21, close(SCRIPT), $!; ok 22, chmod(0755, $script), $!; $_ = `$script`; s{is perl}{is $wd/perl}; # for systems where $^X is only a basename -ok 23, $_ eq $s, ":$_:!=:$s:"; +ok 23, $_ eq $s2, ":$_:!=:$s2:"; $_ = `$wd/perl $script`; -ok 24, $_ eq $s, ":$_:!=:$s:"; +ok 24, $_ eq $s1, ":$_:!=:$s1: after `$wd/perl $script`"; ok 25, unlink($script), $!; # $], $^O, $^T @@ -105,8 +105,6 @@ #define Fstat(fd,bufptr) fstat((fd),(bufptr)) #define Fflush(fp) fflush(fp) -#define my_getenv(var) getenv(var) - #ifdef PERL_SCO5 # define PERL_SYS_INIT(c,v) fpsetmask(0) #else diff --git a/vms/descrip.mms b/vms/descrip.mms index d3ac365eb2..183c33f2eb 100644 --- a/vms/descrip.mms +++ b/vms/descrip.mms @@ -546,7 +546,7 @@ IO : [.lib]IO.pm [.lib.IO]File.pm [.lib.IO]Handle.pm [.lib.IO]Pipe.pm [.lib.IO]S # Rename catches problem with some DECC versions in which object file is # placed in current default dir, not same one as source file. [.x2p]$(DBG)a2p$(E) : [.x2p]a2p$(O), [.x2p]hash$(O), [.x2p]str$(O), [.x2p]util$(O), [.x2p]walk$(O) - @ If F$Search("a2p$(O)").nes."" Then Rename/NoLog a2p$(O),hash$(O),str$(O),util$(O),walk$(O) [.x2p] + @ If F$Search("hash$(O)").nes."" Then Rename/NoLog hash$(O),str$(O),util$(O),walk$(O) [.x2p] Link $(LINKFLAGS) /Exe=$(MMS$TARGET) $(MMS$SOURCE_LIST) $(CRTLOPTS) # Accomodate buggy cpp in some version of DECC, which chokes on illegal @@ -609,6 +609,10 @@ preplibrary : $(MINIPERL_EXE) $(LIBPREREQ) $(SOCKPM) @ If F$Search("[.lib]pod.dir").eqs."" Then Create/Directory [.lib.pod] @ Copy/Log $(MMS$SOURCE) $(MMS$TARGET) +[.lib.pod]perldelta.pod : [.pod]perldelta.pod + @ If F$Search("[.lib]pod.dir").eqs."" Then Create/Directory [.lib.pod] + @ Copy/Log $(MMS$SOURCE) $(MMS$TARGET) + [.lib.pod]perldiag.pod : [.pod]perldiag.pod @ If F$Search("[.lib]pod.dir").eqs."" Then Create/Directory [.lib.pod] @ Copy/Log $(MMS$SOURCE) $(MMS$TARGET) @@ -697,6 +701,10 @@ preplibrary : $(MINIPERL_EXE) $(LIBPREREQ) $(SOCKPM) @ If F$Search("[.lib]pod.dir").eqs."" Then Create/Directory [.lib.pod] @ Copy/Log $(MMS$SOURCE) $(MMS$TARGET) +[.lib.pod]perltoot.pod : [.pod]perltoot.pod + @ If F$Search("[.lib]pod.dir").eqs."" Then Create/Directory [.lib.pod] + @ Copy/Log $(MMS$SOURCE) $(MMS$TARGET) + [.lib.pod]perltrap.pod : [.pod]perltrap.pod @ If F$Search("[.lib]pod.dir").eqs."" Then Create/Directory [.lib.pod] @ Copy/Log $(MMS$SOURCE) $(MMS$TARGET) @@ -1640,7 +1648,6 @@ tidy : cleanlis - If F$Search("[.Ext.DynaLoader]DL_VMS$(O);-1").nes."" Then Purge/NoConfirm/Log [.Ext.DynaLoader]DL_VMS$(O) - If F$Search("[.Ext.DynaLoader]DL_VMS.C;-1").nes."" Then Purge/NoConfirm/Log [.Ext.DynaLoader]DL_VMS.C - If F$Search("[.Ext.Opcode...];-1").nes."" Then Purge/NoConfirm/Log [.Ext.Opcode] - - If F$Search("[.Ext.FileHandle...];-1").nes."" Then Purge/NoConfirm/Log [.Ext.FileHandle] - If F$Search("[.VMS.Ext...]*.C;-1").nes."" Then Purge/NoConfirm/Log [.VMS.Ext...]*.C - If F$Search("[.VMS.Ext...]*$(O);-1").nes."" Then Purge/NoConfirm/Log [.VMS.Ext...]*$(O) - If F$Search("[.Lib.Auto...]*.al;-1").nes."" Then Purge/NoConfirm/Log [.Lib.Auto...]*.al @@ -1663,9 +1670,6 @@ clean : tidy Set Default [.ext.Fcntl] - $(MMS) clean Set Default [--] - Set Default [.ext.FileHandle] - - $(MMS) clean - Set Default [--] Set Default [.ext.IO] - $(MMS) clean Set Default [--] @@ -1701,9 +1705,6 @@ realclean : clean Set Default [.ext.Fcntl] - $(MMS) realclean Set Default [--] - Set Default [.ext.FileHandle] - - $(MMS) realclean - Set Default [--] Set Default [.ext.IO] - $(MMS) realclean Set Default [--] diff --git a/vms/ext/filespec.t b/vms/ext/filespec.t index a0a274bfee..62b06fe9ed 100644 --- a/vms/ext/filespec.t +++ b/vms/ext/filespec.t @@ -1,5 +1,7 @@ #!./perl +BEGIN { unshift(@INC,'../lib') if -d '../lib'; } + use VMS::Filespec; foreach (<DATA>) { diff --git a/vms/genconfig.pl b/vms/genconfig.pl index 6c3582216d..d2e514b1c9 100644 --- a/vms/genconfig.pl +++ b/vms/genconfig.pl @@ -78,10 +78,6 @@ ar='' eunicefix=':' hint='none' hintfile='' -intsize='4' -longsize='4' -shortsize='2' -alignbytes='8' shrplib='define' usemymalloc='n' usevfork='true' @@ -256,13 +252,15 @@ while (<IN>) { $val =~ s!\s*/\*.*!!; # strip off trailing comment my($had_val); # Maybe a macro with args that we just #undefd or commented if (!length($val) and $val_vars{$token} and ($un || $blocked)) { - print OUT "$val_vars{$token}=''\n"; + print OUT "$val_vars{$token}=''\n" unless exists $done{$val_vars{$token}}; + $done{$val_vars{$token}}++; delete $val_vars{$token}; $had_val = 1; } $state = ($blocked || $un) ? 'undef' : 'define'; if ($pp_vars{$token}) { - print OUT "$pp_vars{$token}='$state'\n"; + print OUT "$pp_vars{$token}='$state'\n" unless exists $done{$pp_vars{$token}}; + $done{$pp_vars{$token}}++; delete $pp_vars{$token}; } elsif (not length $val and not $had_val) { @@ -278,8 +276,11 @@ while (<IN>) { # Library directory; convert to VMS syntax $val = VMS::Filespec::vmspath($val) if ($token =~ /EXP$/); if ($val_vars{$token}) { - print OUT "$val_vars{$token}='$val'\n"; - if ($val_vars{$token} =~ s/exp$//) {print OUT "$val_vars{$token}='$val'\n";} + print OUT "$val_vars{$token}='$val'\n" unless exists $done{$val_vars{$token}}; + if ($val_vars{$token} =~ s/exp$//) { + print OUT "$val_vars{$token}='$val'\n" unless exists $done{$val_vars{$token}};; + } + $done{$val_vars{$token}}++; delete $val_vars{$token}; } elsif (!$pp_vars{$token}) { # Haven't seen it previously, either @@ -42,9 +42,9 @@ # define SS$_NOSUCHOBJECT 2696 #endif -/* Don't intercept calls to vfork, since my_vfork below needs to - * get to the underlying CRTL routine. */ -#define __DONT_MASK_VFORK +/* Don't replace system definitions of vfork, getenv, and stat, + * code below needs to get to the underlying CRTL routines. */ +#define DONT_MASK_RTL_CALLS #include "EXTERN.h" #include "perl.h" #include "XSUB.h" @@ -333,7 +333,7 @@ do_rmdir(char *name) { char dirfile[NAM$C_MAXRSS+1]; int retval; - struct stat st; + struct mystat st; if (do_fileify_dirspec(name,dirfile,0) == NULL) return -1; if (flex_stat(dirfile,&st) || !S_ISDIR(st.st_mode)) retval = -1; @@ -2965,7 +2965,7 @@ struct passwd *my_getpwnam(char *name) { struct dsc$descriptor_s name_desc; union uicdef uic; - unsigned long int status, stat; + unsigned long int status, sts; __pwdcache = __passwd_empty; if (!fillpasswd(name, &__pwdcache)) { @@ -2974,17 +2974,17 @@ struct passwd *my_getpwnam(char *name) name_desc.dsc$b_dtype= DSC$K_DTYPE_T; name_desc.dsc$b_class= DSC$K_CLASS_S; name_desc.dsc$a_pointer= (char *) name; - if ((stat = sys$asctoid(&name_desc, &uic, 0)) == SS$_NORMAL) { + if ((sts = sys$asctoid(&name_desc, &uic, 0)) == SS$_NORMAL) { __pwdcache.pw_uid= uic.uic$l_uic; __pwdcache.pw_gid= uic.uic$v_group; } else { - if (stat == SS$_NOSUCHID || stat == SS$_IVIDENT || stat == RMS$_PRV) { - set_vaxc_errno(stat); - set_errno(stat == RMS$_PRV ? EACCES : EINVAL); + if (sts == SS$_NOSUCHID || sts == SS$_IVIDENT || sts == RMS$_PRV) { + set_vaxc_errno(sts); + set_errno(sts == RMS$_PRV ? EACCES : EINVAL); return NULL; } - else { _ckvmssts(stat); } + else { _ckvmssts(sts); } } } strncpy(__pw_namecache, name, sizeof(__pw_namecache)); @@ -3388,11 +3388,11 @@ int my_utime(char *file, struct utimbuf *utimes) * on the first call. */ #define LOCKID_MASK 0x80000000 /* Use 0 to force device name use only */ -static dev_t encode_dev (const char *dev) +static mydev_t encode_dev (const char *dev) { int i; unsigned long int f; - dev_t enc; + mydev_t enc; char c; const char *q; @@ -3456,14 +3456,15 @@ is_null_device(name) /* Do the permissions allow some operation? Assumes statcache already set. */ /* Do this via $Check_Access on VMS, since the CRTL stat() returns only a - * subset of the applicable information. + * subset of the applicable information. (We have to stick with struct + * stat instead of struct mystat in the prototype since we have to match + * the one in proto.h.) */ /*{{{I32 cando(I32 bit, I32 effective, struct stat *statbufp)*/ I32 cando(I32 bit, I32 effective, struct stat *statbufp) { - if (statbufp == &statcache) - return cando_by_name(bit,effective,namecache); + if (statbufp == &statcache) return cando_by_name(bit,effective,namecache); else { char fname[NAM$C_MAXRSS+1]; unsigned long int retsts; @@ -3472,13 +3473,13 @@ cando(I32 bit, I32 effective, struct stat *statbufp) /* If the struct mystat is stale, we're OOL; stat() overwrites the device name on successive calls */ - devdsc.dsc$a_pointer = statbufp->st_devnam; - devdsc.dsc$w_length = strlen(statbufp->st_devnam); + devdsc.dsc$a_pointer = ((struct mystat *)statbufp)->st_devnam; + devdsc.dsc$w_length = strlen(((struct mystat *)statbufp)->st_devnam); namdsc.dsc$a_pointer = fname; namdsc.dsc$w_length = sizeof fname - 1; - retsts = lib$fid_to_name(&devdsc,&(statbufp->st_ino),&namdsc, - &namdsc.dsc$w_length,0,0); + retsts = lib$fid_to_name(&devdsc,&(((struct mystat *)statbufp)->st_ino), + &namdsc,&namdsc.dsc$w_length,0,0); if (retsts & 1) { fname[namdsc.dsc$w_length] = '\0'; return cando_by_name(bit,effective,fname); @@ -3589,13 +3590,12 @@ cando_by_name(I32 bit, I32 effective, char *fname) /*}}}*/ -/*{{{ int flex_fstat(int fd, struct stat *statbuf)*/ -#undef stat +/*{{{ int flex_fstat(int fd, struct mystat *statbuf)*/ int flex_fstat(int fd, struct mystat *statbufp) { if (!fstat(fd,(stat_t *) statbufp)) { - if (statbufp == &statcache) *namecache == '\0'; + if (statbufp == (struct mystat *) &statcache) *namecache == '\0'; statbufp->st_dev = encode_dev(statbufp->st_devnam); # ifdef VMSISH_TIME if (!VMSISH_TIME) { /* Return UTC instead of local time */ @@ -3614,19 +3614,15 @@ flex_fstat(int fd, struct mystat *statbufp) } /* end of flex_fstat() */ /*}}}*/ -/*{{{ int flex_stat(char *fspec, struct stat *statbufp)*/ -/* We defined 'stat' as 'mystat' in vmsish.h so that declarations of - * 'struct stat' elsewhere in Perl would use our struct. We go back - * to the system version here, since we're actually calling their - * stat(). - */ +/*{{{ int flex_stat(char *fspec, struct mystat *statbufp)*/ int flex_stat(char *fspec, struct mystat *statbufp) { char fileified[NAM$C_MAXRSS+1]; int retval = -1; - if (statbufp == &statcache) do_tovmsspec(fspec,namecache,0); + if (statbufp == (struct mystat *) &statcache) + do_tovmsspec(fspec,namecache,0); if (is_null_device(fspec)) { /* Fake a stat() for the null device */ memset(statbufp,0,sizeof *statbufp); statbufp->st_dev = encode_dev("_NLA0:"); @@ -3648,7 +3644,8 @@ flex_stat(char *fspec, struct mystat *statbufp) */ if (do_fileify_dirspec(fspec,fileified,0) != NULL) { retval = stat(fileified,(stat_t *) statbufp); - if (!retval && statbufp == &statcache) strcpy(namecache,fileified); + if (!retval && statbufp == (struct mystat *) &statcache) + strcpy(namecache,fileified); } if (retval) retval = stat(fspec,(stat_t *) statbufp); if (!retval) { @@ -3667,8 +3664,6 @@ flex_stat(char *fspec, struct mystat *statbufp) return retval; } /* end of flex_stat() */ -/* Reset definition for later calls */ -#define stat mystat /*}}}*/ /* Insures that no carriage-control translation will be done on a file. */ diff --git a/vms/vmsish.h b/vms/vmsish.h index cab319dc04..61543415e2 100644 --- a/vms/vmsish.h +++ b/vms/vmsish.h @@ -2,8 +2,8 @@ * * VMS-specific C header file for perl5. * - * Last revised: 01-Oct-1995 by Charles Bailey bailey@genetics.upenn.edu - * Version: 5.1.6 + * Last revised: 18-Feb-1997 by Charles Bailey bailey@genetics.upenn.edu + * Version: 5.3.28 */ #ifndef __vmsish_h_included @@ -56,6 +56,18 @@ # include <unistd.h> /* DECC has this; VAXC and gcc don't */ #endif +#ifdef NO_PERL_TYPEDEFS /* a2p; we don't want Perl's special routines */ +# define DONT_MASK_RTL_CALLS +#endif + + /* defined for vms.c so we can see CRTL | defined for a2p */ +#ifndef DONT_MASK_RTL_CALLS +# ifdef getenv +# undef getenv +# endif +# define getenv(v) my_getenv(v) /* getenv used for regular logical names */ +#endif + /* DECC introduces this routine in the RTL as of VMS 7.0; for now, * we'll use ours, since it gives us the full VMS exit status. */ #ifdef __PID_T @@ -130,7 +142,7 @@ * exec should be handled in VMSish or Unixish style. */ #define fork my_vfork -#ifndef __DONT_MASK_VFORK /* #defined in vms.c so we see real vfork */ +#ifndef DONT_MASK_RTL_CALLS /* #defined in vms.c so we see real vfork */ # ifdef vfork # undef vfork # endif @@ -181,13 +193,13 @@ #define COMPLEX_STATUS 1 /* We track both "POSIX" and VMS values */ -#define HINT_S_VMSISH 24 +#define HINT_V_VMSISH 24 #define HINT_M_VMSISH_STATUS 0x01000000 /* system, $? return VMS status */ #define HINT_M_VMSISH_EXIT 0x02000000 /* exit(1) ==> SS$_NORMAL */ #define HINT_M_VMSISH_TIME 0x04000000 /* times are local, not UTC */ -#define NATIVE_HINTS (hints >> HINT_S_VMSISH) /* used in op.c */ +#define NATIVE_HINTS (hints >> HINT_V_VMSISH) /* used in op.c */ -#define TEST_VMSISH(h) (curcop->op_private & ((h) >> HINT_S_VMSISH)) +#define TEST_VMSISH(h) (curcop->op_private & ((h) >> HINT_V_VMSISH)) #define VMSISH_STATUS TEST_VMSISH(HINT_M_VMSISH_STATUS) #define VMSISH_EXIT TEST_VMSISH(HINT_M_VMSISH_EXIT) #define VMSISH_TIME TEST_VMSISH(HINT_M_VMSISH_TIME) @@ -327,6 +339,9 @@ struct utimbuf { /* Look up new %ENV values on the fly */ #define DYNAMIC_ENV_FETCH 1 #define ENV_HV_NAME "%EnV%VmS%" + /* Special getenv function for retrieving %ENV elements. */ +#define ENV_getenv(v) my_getenv(v) + /* Thin jacket around cuserid() tomatch Unix' calling sequence */ #define getlogin my_getlogin @@ -430,11 +445,16 @@ struct mystat char st_fab_fsz; /* fixed header size */ unsigned st_dev; /* encoded device name */ }; -#define stat mystat typedef unsigned mydev_t; -#define dev_t mydev_t typedef unsigned myino_t; -#define ino_t myino_t +#ifndef DONT_MASK_RTL_CALLS /* defined for vms.c so we can see RTL calls */ +# ifdef stat +# undef stat +# endif +# define stat mystat +# define dev_t mydev_t +# define ino_t myino_t +#endif #if defined(__DECC) || defined(__DECCXX) # pragma __member_alignment __restore #endif @@ -513,8 +533,8 @@ struct tm * my_gmtime _((const time_t *)); struct tm * my_localtime _((const time_t *)); time_t my_time _((time_t *)); I32 cando_by_name _((I32, I32, char *)); -int flex_fstat _((int, struct stat *)); -int flex_stat _((char *, struct stat *)); +int flex_fstat _((int, struct mystat *)); +int flex_stat _((char *, struct mystat *)); int trim_unixpath _((char *, char*, int)); int my_vfork _(()); bool vms_do_aexec _((SV *, SV **, SV **)); diff --git a/x2p/a2p.pod b/x2p/a2p.pod index 4e61fd6ab9..06c5ac7322 100644 --- a/x2p/a2p.pod +++ b/x2p/a2p.pod @@ -82,13 +82,13 @@ block to bypass the block under such circumstances can be simplified by removing the conditional in the END block and just exiting directly from the perl script. -Perl has two kinds of array, numerically-indexed and associative. Awk -arrays are usually translated to associative arrays, but if you happen -to know that the index is always going to be numeric you could change -the {...} to [...]. Iteration over an associative array is done using -the keys() function, but iteration over a numeric array is NOT. You -might need to modify any loop that is iterating over the array in -question. +Perl has two kinds of array, numerically-indexed and associative. +Perl associative arrays are called "hashes". Awk arrays are usually +translated to hashes, but if you happen to know that the index is +always going to be numeric you could change the {...} to [...]. +Iteration over a hash is done using the keys() function, but iteration +over an array is NOT. You might need to modify any loop that iterates +over such an array. Awk starts by assuming OFMT has the value %.6g. Perl starts by assuming its equivalent, $#, to have the value %.20g. You'll want to |