perl 5.000perl-5.000

[editor's note: this commit combines approximate 4 months of furious
releases of Andy Dougherty and Larry Wall - see pod/perlhist.pod for
details.  Andy notes that;
 
Alas neither my "Irwin AccuTrack" nor my DC 600A quarter-inch cartridge 
backup tapes from that era seem to be readable anymore.  I guess 13 years 
exceeds the shelf life for that backup technology :-(.
]

1 files changed, 232 insertions, 0 deletions

diff --git a/README.vms b/README.vms
new file mode 100644
index 0000000000..dbf6251311
--- /dev/null
+++ b/README.vms
@@ -0,0 +1,232 @@
+Last revised: 09-Oct-1994 by Charles Bailey  bailey@genetics.upenn.edu
+
+The VMS port of perl5 is still under development.  At this time, the perl
+binaries built under VMS handle internal operations properly, for the most
+part, as well as most of the system calls which have close equivalents under
+VMS. There are still some incompatibilities in process handling (e.g the
+fork/exec model for creating subprocesses doesn't do what you might expect
+under Unix), and there remain some file handling differences from Unix.  There
+is a VMS implementation of the DynaLoader, but it hasn't been tested much, so
+it may still have some bugs in it.  Over the longer term, we'll try to get many
+of the useful VMS system services integrated as well, depending on time and
+people available.  Of course, if you'd like to add something yourself, or join
+the porting team, we'd love to have you!
+
+The current sources and build procedures have been tested on a VAX using VAXC
+and on an AXP using DECC.  IF you run into problems with other compilers,
+please let us know.
+
+
+* Other software required
+
+At the moment, in addition to basic VMS, you'll need two things:
+   - a C compiler: VAXC, DECC, or gcc for the VAX; DECC for the AXP
+   - a make tool: DEC's MMS or the free analog MMK (available from ftp.spc.edu)
+     or a standard make utility (e.g. GNU make, also available from
+     ftp.spc.edu).
+In addition, you may include socket support if you have a IP stack running
+on your system.  See the topic "Socket support" for more information.
+
+* Socket support
+
+Perl5 includes a number of IP socket routines among its builtin functions,
+which are available if you choose to compile perl with socket support.  Since
+IP networking is an optional addition to VMS, there are several different IP
+stacks available, it's difficult to automate the process of building perl5 with
+socket support in a way which will work on all systems.  
+
+By default, perl5 is built without IP socket support.  If you define the macro
+SOCKET when invoking MMS, however, socket support will be included.  As
+distributed, perl5 for VMS includes support for the SOCKETSHR socket library,
+which is layered on MadGoat software's vendor-independent NETLIB interface. 
+This provides support for all socket calls used by perl5 except the
+[g|s]et*ent() routines, which are replaced for the moment by stubs which
+generate a fatal error if a perl script attempts to call one of these routines. 
+If you'd like to link perl directly to your IP stack to take advantage of these
+routines or to eliminate the intermediate NETLIB, then make the following
+changes:
+  - In Descrip.MMS, locate the section beginning with .ifdef SOCKET, and
+    change the SOCKLIB macro so that it translates to  the filespec of your
+    IP stack's socket library.  This will be added to the RTL options file.
+  - Edit the file SockAdapt.H in the [.VMS] subdirectory so that it
+    includes the In.H, NetDb.H, and, if necessary, Errno.H header files
+    for your IP stack, or so that it declares the standard TCP/IP data
+    structures appropriately (see the distributed copy of SockAdapt.H
+    for a collection of the structures needed by perl.)  You should also
+    define any logical names necessary to find these files before invoking
+    MMS to build perl.
+  - Edit the file SockAdapt.C in the [.VMS] subdirectory so that it
+    contains routines which substitute for any IP library routines
+    required by perl which your IP stack does not provide.  This may
+    require a little trial and error; we'll try to compile a complete
+    list soon of socket routines required by perl5.
+
+* Building perl under VMS
+
+Since you're reading this, presumable you've unpacked the perl distribution
+into its directory tree, in which you will find a [.vms] subdirectory below
+the directory in which this file is found.  If this isn't the case, then you'll
+need to unpack the distribution properly, or manually edit Descrip.MMS or
+the VMS Makefile. to alter directory paths as necessary.  (I'd advise using the 
+`normal' directory tree, at least for the first time through.)  This
+subdirectory contains several files, among which are the following:
+  Config.VMS     - A template C header file set up for VMS.
+  Descrip.MMS    - The MMS/MMK dependency file for building perl
+  GenConfig.Pl   - A perl script to generate Config.SH retrospectively
+                   from Config.VMS, since the Configure shell script which
+                   normally generates Config.SH doesn't run under VMS.
+  GenOpt.Com     - A little DCL procedure used to write some linker options
+                   files, since not all make utilities can do this easily.
+  Gen_ShrFls.Pl  - A perl script which generates linker options files and
+                   MACRO declarations for PerlShr.Exe.
+  Makefile.      - The make dependency file for building perl  
+  MMS2Make.Pl    - A perl script used to generate Makefile. from Descrip.MMS
+  VMSish.H       - C header file containing VMS-specific definitions
+  VMS.C          - C source code for VMS-specific routines
+  WriteMain.Pl   - A perl script used to generate perlmain.c during the build.
+There may also be other files pertaining to features under development; for the
+most part, you can ignore them.
+
+Config.VMS and Decrip.MMS/Makefile. are set up to build a version of perl which
+includes all features known to work when this release was assembled.  If you
+have code at your site which would support additional features (e.g. emulation
+of Unix system calls), feel free to make the appropriate changes to these
+files.  (Note: Do not use or edit config.h in the main perl source directory;
+it is superseded by the current Config.VMS during the build.)  You may also
+wish to make site-specific changes to Descrip.MMS or Makefile. to reflect local
+conventions for naming of files, etc.
+
+At the moment, system-specific information which becomes part of the perl5
+Config extension is hard-coded into the file genconfig.pl in the vms
+subdirectory.  Before you build perl, you should make any changes to the list
+at the end of this file necessary to reflect your system (e.g your hostname and
+VMS version).
+
+Examine the information at the beginning of Descrip.MMS for information about
+specifying alternate C compilers or building a version of perl with debugging
+support.  For instance, if you want to use DECC, you'll need to include the
+/macro="decc=1" qualifier to MMS  (If you're using make, these options are not
+supported.)  If you're on an AXP system, define the macro __AXP__ (MMK does
+this for you), and DECC will automatically be selected.
+
+To start the build, set default to the main source directory. 
+Then, if you are using MMS or MMK, issue the command
+$ MMS/Descrip=[.VMS] ! or MMK
+If you are using make, issue the command
+$ Make -f [.VMS]Makefile.
+Note that the Makefile. doesn't support conditional compilation, and is
+set up to use VAXC on a VAX, and does not include socket support.  You can
+either edit the Makefile. by hand, using Descrip.MMS as a guide, or use the
+Makefile. to build Miniperl.Exe, and then run the Perl script MMS@Make.pl,
+found in the [.VMS] subdirectory, to generate a new Makefile with the options
+appropriate to your site.
+
+Note for sites using early versions of DECC:  A bug in some versions of the
+DECC RTL causes newlines to be lost when writing to a pipe.  This causes
+Gen_ShrFls.pl to fail, since it can't read the preprocessor output to identify
+global variables and routines.  You can work around this problem by defining
+the macro DECC_PIPES_BROKEN when you invoke MMS or MMK.
+
+This will build the following files:
+  Miniperl.Exe        - a stand-alone version of without any extensions.
+                        Miniperl has all the intrinsic capabilities of perl,
+                        but cannot make use of the DynaLoader or any
+                        extensions which use XS code.
+  PerlShr.Exe         - a shareable image containing most of perl's internal
+                        routines and global variables.  Perl.Exe is linked to
+                        this image, as are all dynamic extensions, so everyone's
+                        using the same set of global variables and routines.
+  Perl.Exe            - the main perl executable image.  It's contains the
+                        main() routine, plus code for any statically linked
+                        extensions.
+  PerlShr_Attr.Opt    - A linker options file which specifies psect attributes
+                        matching those in PerlShr.Exe.  It should be used when
+                        linking images against PerlShr.Exe
+  [.Lib]Config.pm     - the perl extension which saves configuration information
+                        about perl and your system.
+  [.lib]DynaLoader.pm - The perl extension which performs dynamic linking of
+                        shareable images for extensions.
+There are, of course, a number of other files created for use during the build. 
+Once you've got the binaries built, you may wish to `build' the `tidy' or
+`clean' targets to remove extra files.
+
+
+* Installing perl once it's built
+
+Once the build is complete, you'll need to do the following:
+  - Put PerlShr.Exe in a common directory, and make it world-readable.
+    If you place it in a location other than Sys$Share, you'll need to
+    define the logical name PerlShr to point to the image.
+  - Put Perl.Exe in a common directory, and make it world executable
+  - Define a foreign command to invoke perl, using a statement like
+    $ Perl == "$dev:[dir]Perl.Exe"
+  - Create a world-readable directory tree for perl library modules,
+    scripts, and what-have-you, and define PERL_ROOT as a rooted logical
+    name pointing to the top of this tree (i.e. if your perl files were
+    going to live in DKA1:[Perl5...], then you should
+      $ Define/Translation=Concealed Perl_Root DKA1:[Perl5.]
+  - Define the logical name PERLSHR as the full file specification of
+    PERLSHR.EXE, so executable images linked to it can find it.  Alternatively,
+    you can justput PERLSHR.EXE int SYS$SHARE.
+  - Place the files from the [.lib] subdirectory in the distribution package
+    into a [.lib] subdirectory off the root directory described above.
+  - Most of the perl5 documentation lives in the [.pod] subdirectory, and
+    is written in a simple markup format which can be easily read.  In this
+    directory as well are pod2man and pod2html translators to reformat the
+    docs for common display engines; a pod2hlp translator is under development.
+    Information on perl5 can also be gleaned from the files in the [.doc]
+    subdirectory (internals documents and summaries of changes), and from
+    the test scripts in the [.t...] subdirectories.
+For now, that's it.
+
+
+* For more information
+
+If you're interested in more information on perl in general, consult the Usenet
+newsgroup comp.lang.perl.  The FAQ for that group provides pointers to other
+online sources of information, as well as books describing perl in depth.
+
+If you're interested in up-to-date information on perl5 development and
+internals, you might want to subscribe to the perl5-porters mailing list.  You
+can do this by sending a message to perl5-porters-request@isi.edu, containing
+the single line
+subscribe perl5-porters Your Name Here
+This is a moderately high-volume list at the moment (25-50 messages/day).
+
+Finally, if you're interested in ongoing information about the VMS port, you
+can subscribe to the VMSperl mailing list by sending a request to
+bailey@genetics.upenn.edu (it's to a human, not a list server - this is a small
+operation at the moment).  And, as always, we welcome any help or code you'd
+like to offer - you can send mail to bailey@genetics.upenn.edu or directly to
+the VMSperl list at vmsperl@genetics.upenn.edu.
+
+Good luck using perl.  Please let us know how it works for you - we can't
+guarantee that we'll be able to fix bugs quickly, but we'll try, and we'd
+certainly like to know they're out there.
+
+
+* Acknowledgements
+
+There are, of course, far too many people involved in the porting and testing
+of perl5 to mention everyone who deserves it, so please forgive us if we've
+missed someone.  That said, special thanks are due to the following:
+  David Denholm <denholm@conmat.phys.soton.ac.uk>
+     for extensive testing and provision of pipe and SocketShr code,
+  Mark Pizzolato <mark@infocomm.com>
+     for the getredirection() code
+  Rich Salz <rsalz@bbn.com>
+     for readdir() and related routines
+  Denis Haskin <DWH@epub.ziff.com>
+     for work on a pod-to-hlp translator for the perl5 documentation
+  Richard Dyson <dyson@blaze.physics.uiowa.edu> and
+  Kent Covert <kacovert@miavx1.acs.muohio.edu>
+     for additional testing on the AXP.
+and to the entire VMSperl group for useful advice and suggestions.  In addition
+the perl5-porters, especially Andy Dougherty <doughera@lafcol.lafayette.edu>
+and Tim Bunce <Tim.Bunce@ig.co.uk>,  deserve credit for their creativity and
+willingness to work with the VMS newcomers.  Finally, the greatest debt of
+gratitude is due to Larry Wall <lwall@netlabs.com>, for having the ideas which
+have made our sleepless nights possible.
+
+Thanks,
+The VMSperl group