-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
+If you read this file _as_is_, just ignore the equal signs on the left.
+This file is written in the POD format (see [.POD]PERLPOD.POD;1) which is
+specially designed to be readable as is.
+
+=head1 NAME
+
+perlvms - Configuring, building, testing, and installing perl on VMS
+
+=head1 SYNOPSIS
+
+To configure, build, test, and install perl on VMS:
+
+ @ Configure
+ mms
+ mms test
+ mms install
+
+mmk may be used in place of mms in the last three steps.
+
+=head1 DESCRIPTION
+
+=head2 Important safety tip
+
+For best results, make sure you read the "Configuring the Perl Build",
+"Building Perl", and "Installing Perl" sections of this document before
+you build or install. Also please note other changes in the current
+release by having a look at L<perldelta/VMS>.
+
+Also note that, as of Perl version 5.005 and later, an ANSI C compliant
+compiler is required to build Perl. VAX C is I<not> ANSI compliant, as it
+died a natural death some time before the standard was set. Therefore
+VAX C will not compile Perl 5.005 or later. We are sorry about that.
+
+There have been no recent reports of builds using Gnu C, but latent
+(and most likely outdated) support for it is still present in various
+parts of the sources. Currently the HP (formerly Compaq, and even
+more formerly DEC) C compiler is the only viable alternative for
+building Perl.
+
+There is minimal support for HP C++ but this support is not complete;
+if you get it working please write to the vmsperl list (for info see
+L</"Mailing Lists">).
+
+
+=head2 Introduction to Perl on VMS
+
+The VMS port of Perl is as functionally complete as any other Perl port
+(and as complete as the ports on some Unix systems). The Perl binaries
+provide all the Perl system calls that are either available under VMS or
+reasonably emulated. There are some incompatibilities in process handling
+(e.g. the fork/exec model for creating subprocesses doesn't do what you
+might expect under Unix), mainly because VMS and Unix handle processes and
+sub-processes very differently.
+
+There are still some unimplemented system functions, and of course we
+could use modules implementing useful VMS system services, so if you'd like
+to lend a hand we'd love to have you. Join the Perl Porting Team Now!
+
+=head2 Other required software for Compiling Perl on VMS
+
+In addition to VMS and DCL you will need two things:
+
+=over 4
+
+=item 1 A C compiler.
+
+HP (formerly Compaq, more formerly DEC) C for VMS (VAX, Alpha, or Itanium).
+Various ancient versions of DEC C had some caveats, so if you're using a
+version older than 7.x on Alpha or Itanium or 6.x on VAX, you may need to
+upgrade to get a successful build.
+
+=item 2 A make tool.
+
+HP's MMS may work, but MadGoat's free MMS analog MMK (available from
+http://www.kednos.com/kednos/Resources/MMK) has consistently worked
+better. Gnu Make might work, but it's been so long since anyone's tested
+it that we're not sure. MMK is free though, so go ahead and use that.
+
+=back
+
+=head2 Additional software that is optional for Perl on VMS
+
+You may also want to have on hand:
+
+=over 4
+
+=item 1 GUNZIP/GZIP for VMS
+
+A de-compressor for *.gz and *.tgz files available from a number
+of web/ftp sites and is distributed on the OpenVMS Freeware CD-ROM
+from HP.
+
+ http://www.hp.com/go/openvms/freeware/
+
+=item 2 VMS TAR
+
+For reading and writing unix tape archives (*.tar files). Vmstar is also
+available from a number of web/ftp sites and is distributed on the OpenVMS
+Freeware CD-ROM from HP.
+
+ http://www.hp.com/go/openvms/freeware/
+
+Recent versions of VMS tar on ODS-5 volumes may extract tape archive
+files with ^. escaped periods in them. See below for further workarounds.
+
+A port of GNU tar is also available as part of the GNV package:
+
+ http://h71000.www7.hp.com/opensource/gnv.html
+
+=item 3 UNZIP for VMS
+
+A combination decompressor and archive reader/writer for *.zip files.
+Unzip is available from a number of web/ftp sites.
+
+ http://www.info-zip.org/UnZip.html
+ http://www.hp.com/go/openvms/freeware/
+ ftp://ftp.process.com/vms-freeware/fileserv/
+
+=item 5 GNU PATCH and DIFFUTILS for VMS
+
+Patches to Perl are usually distributed as GNU unified or contextual diffs.
+Such patches are created by the GNU diff program (part of the diffutils
+distribution) and applied with GNU patch. VMS ports of these utilities are
+available here:
+
+ http://www.antinode.info/dec/sw/diffutils.html
+ http://www.hp.com/go/openvms/freeware/
+
+=back
+
+Please note that UNZIP and GUNZIP are not the same thing (they work with
+different formats). Many of the useful files from CPAN (the Comprehensive
+Perl Archive Network) are in *.tar.gz or *.tgz format (this includes copies
+of the source code for perl as well as modules and scripts that you may
+wish to add later) hence you probably want to have GUNZIP.EXE and
+VMSTAR.EXE on your VMS machine.
+
+If you want to include socket support, you'll need a TCP/IP stack and either
+DEC C, or socket libraries. See the "Socket Support (optional)" topic
+for more details.
+
+=head1 Unpacking the Perl source code
+
+You may need to set up a foreign symbol for the unpacking utility of choice.
+
+As of version 5.10.0, Perl will still build and run on ODS-2 volumes,
+including on VAX, but there are a number of modules whose temporary
+files and tests are much happier residing on ODS-5 volumes. For
+example, CPANPLUS will fail most of its tests on an ODS-2 volume because
+it includes files with multiple dots that will have been converted to
+underscores and the tests will have difficulty finding them. So your
+best bet is to unpack the Perl source kit on an ODS-5 volume using
+recent versions of vmstar (e.g. V3.4 or later). Contrary to advice
+provided with previous versions of Perl, do I<not> use the ODS-2
+compatibility qualifier. Instead, use a command like the following:
+
+ vmstar -xvf perl-5^.15^.1.tar
+
+Then rename the top-level source directory like so:
+
+ set security/protection=(o:rwed) perl-5^.15^.1.dir
+ rename perl-5^.15^.1.dir perl-5_15_1.dir
+
+The reason for this last step is that while filenames with multiple dots
+are generally supported by Perl on VMS, I<directory> names with multiple
+dots are a special case with special problems because the dot is the
+traditional directory delimiter on VMS. Rudimentary support for
+multi-dot directory names is available, but some of the oldest and most
+essential parts of Perl (such as searching for and loading library
+modules) do not yet fully support the ODS-5 caret-escape syntax.
+
+=head1 Configuring the Perl build
+
+To configure perl (a necessary first step), issue the command
+
+ @ Configure
+
+from the top of an unpacked perl source directory. You will be asked a
+series of questions, and the answers to them (along with the capabilities
+of your C compiler and network stack) will determine how perl is custom
+built for your machine.
+
+If you have any symbols or logical names in your environment that may
+interfere with the build or regression testing of perl then configure.com
+will try to warn you about them. If a logical name is causing
+you trouble but is in an LNM table that you do not have write access to
+then try defining your own to a harmless equivalence string in a table
+such that it is resolved before the other (e.g. if TMP is defined in the
+SYSTEM table then try DEFINE TMP "NL:" or somesuch in your process table)
+otherwise simply deassign the dangerous logical names. The potentially
+troublesome logicals and symbols are:
+
+ COMP "LOGICAL"
+ EXT "LOGICAL"
+ FOO "LOGICAL"
+ LIB "LOGICAL"
+ LIST "LOGICAL"
+ MIME "LOGICAL"
+ POSIX "LOGICAL"
+ SYS "LOGICAL"
+ T "LOGICAL"
+ THREAD "LOGICAL"
+ THREADS "LOGICAL"
+ TIME "LOGICAL"
+ TMP "LOGICAL"
+ UNICODE "LOGICAL"
+ UTIL "LOGICAL"
+ TEST "SYMBOL"
+
+As a handy shortcut, the command:
+
+ @ Configure "-des"
+
+(note the quotation marks and case) will choose reasonable defaults
+automatically (it takes DEC C over Gnu C, DEC C sockets over SOCKETSHR
+sockets, and either over no sockets). Some options can be given
+explicitly on the command line; the following example specifies a
+non-default location for where Perl will be installed:
+
+ @ Configure "-d" "-Dprefix=dka100:[utils.perl5.]"
+
+Note that the installation location would be by default where you unpacked
+the source with a "_ROOT." appended. For example if you unpacked the perl
+source into:
+
+ DKA200:[PERL-5_10_2...]
+
+Then the PERL_SETUP.COM that gets written out by CONFIGURE.COM will
+try to DEFINE your installation PERL_ROOT to be:
+
+ DKA200:[PERL-5_10_2_ROOT.]
+
+More help with configure.com is available from:
+
+ @ Configure "-h"
+
+See the "Changing compile-time options (optional)" section below to learn
+even more details about how to influence the outcome of the important
+configuration step. If you find yourself reconfiguring and rebuilding
+then be sure to also follow the advice in the "Cleaning up and starting
+fresh (optional)" and the checklist of items in the "CAVEATS" sections
+below.
+
+=head2 Changing compile-time options (optional) for Perl on VMS
+
+Most of the user definable features of Perl are enabled or disabled in
+configure.com, which processes the hints file config_h.SH. There is
+code in there to Do The Right Thing, but that may end up being the
+wrong thing for you. Make sure you understand what you are doing since
+inappropriate changes to configure.com or config_h.SH can render perl
+unbuildable; odds are that there's nothing in there you'll need to
+change.
+
+=head2 Socket Support (optional) for Perl on VMS
+
+Perl includes a number of functions for IP sockets, 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.
+How well integrated they are into the system depends on the stack, your
+version of VMS, and the version of your C compiler.
+
+The default solution available is to use the socket routines built into DEC
+C. Which routines are available depend on the version of VMS you're
+running, and require proper UCX emulation by your TCP/IP vendor.
+Relatively current versions of Multinet, TCPWare, Pathway, and UCX all
+provide the required libraries--check your manuals or release notes to see
+if your version is new enough.
+
+The other solution uses the SOCKETSHR library. Before VAX/VMS 5.5-2 it was
+the most portable solution. The SOCKETSHR library has not been maintained
+since VAX/VMS 5.5-2, and it is not known if will even compile with the ANSI
+C that Perl currently requires. It remains an option for historical reasons,
+just in case someone might find it useful.
+
+In combination with either UCX or NetLib, this supported all the major TCP
+stacks (Multinet, Pathways, TCPWare, UCX, and CMU) on all versions of VMS
+Perl ran on up to VAX/VMS 6.2 and Alpha VMS 1.5 with all the compilers on
+both VAX and Alpha. The portion of the socket interface was also consistent
+across versions of VMS and C compilers.
+
+It has a problem with UDP sockets when used with Multinet, though, so you
+should be aware of that.
+
+As of VAX/VMS 5.5-2 and later, CMU is the only TCP/IP program that requires
+socketshr, and the sources have been lost to the most recent CMU bug fixes,
+so CMU is limited to OpenVMS/VAX 6.2 or earlier, which is the last release
+that binaries for the last released patches are known to exist.
+
+There is currently no official web site for downloading either CMU or
+SOCKETSHR; however, copies may be found in the DECUS archives.
+
+=head1 Building Perl
+
+The configuration script will print out, at the very end, the MMS or MMK
+command you need to compile perl. Issue it (exactly as printed) to start
+the build.
+
+Once you issue your MMS or MMK command, sit back and wait. Perl should
+compile and link without a problem. If a problem does occur check the
+"CAVEATS" section of this document. If that does not help send some
+mail to the VMSPERL mailing list. Instructions are in the "Mailing Lists"
+section of this document.
+
+=head1 Testing Perl
+
+Once Perl has built cleanly you need to test it to make sure things work.
+This step is very important since there are always things that can go wrong
+somehow and yield a dysfunctional Perl for you.
+
+Testing is very easy, though, as there's a full test suite in the perl
+distribution. To run the tests, enter the I<exact> MMS line you used to
+compile Perl and add the word "test" to the end, like this:
+
+If the compile command was:
+
+ MMS
+
+then the test command ought to be:
+
+ MMS test
+
+MMS (or MMK) will run all the tests. This may take some time, as there are
+a lot of tests. If any tests fail, there will be a note made on-screen.
+At the end of all the tests, a summary of the tests, the number passed and
+failed, and the time taken will be displayed.
+
+The test driver invoked via MMS TEST has a DCL wrapper ([.VMS]TEST.COM) that
+downgrades privileges to NETMBX, TMPMBX for the duration of the test run,
+and then restores them to their prior state upon completion of testing.
+This is done to ensure that the tests run in a private sandbox and can do no
+harm to your system even in the unlikely event something goes badly wrong in
+one of the test scripts while running the tests from a privileged account.
+A side effect of this safety precaution is that the account used to run the
+test suite must be the owner of the directory tree in which Perl has been
+built; otherwise the manipulations of temporary files and directories
+attempted by some of the tests will fail.
+
+If any tests fail, it means something is wrong with Perl, or at least
+with the particular module or feature that reported failure. If the test suite
+hangs (some tests can take upwards of two or three minutes, or more if
+you're on an especially slow machine, depending on your machine speed, so
+don't be hasty), then the test I<after> the last one displayed failed. Don't
+install Perl unless you're confident that you're OK. Regardless of how
+confident you are, make a bug report to the VMSPerl mailing list.
+
+If one or more tests fail, you can get more information on the failure by
+issuing this command sequence:
+
+ @ [.VMS]TEST .typ "" "-v" [.subdir]test.T
+
+where ".typ" is the file type of the Perl images you just built (if you
+didn't do anything special, use .EXE), and "[.subdir]test.T" is the test
+that failed. For example, with a normal Perl build, if the test indicated
+that t/op/time failed, then you'd do this:
+
+ @ [.VMS]TEST .EXE "" "-v" [.OP]TIME.T
+
+Note that test names are reported in UNIX syntax and relative to the
+top-level build directory. When supplying them individually to the test
+driver, you can use either UNIX or VMS syntax, but you must give the path
+relative to the [.T] directory and you must also add the .T extension to the
+filename. So, for example if the test lib/Math/Trig fails, you would run:
+
+ @ [.VMS]TEST .EXE "" -"v" [-.lib.math]trig.t
+
+When you send in a bug report for failed tests, please include the output
+from this command, which is run from the main source directory:
+
+ MCR []MINIPERL "-V"
+
+Note that -"V" really is a capital V in double quotes. This will dump out a
+couple of screens worth of configuration information, and can help us
+diagnose the problem. If (and only if) that did not work then try enclosing
+the output of:
+
+ MMS printconfig
+
+If (and only if) that did not work then try enclosing the output of:
+
+ @ [.vms]myconfig
+
+You may also be asked to provide your C compiler version ("CC/VERSION NL:"
+with DEC C, "gcc --version" with GNU CC). To obtain the version of MMS or
+MMK you are running try "MMS/ident" or "MMK /ident". The GNU make version
+can be identified with "make --version".
+
+=head2 Cleaning up and starting fresh (optional) installing Perl on VMS
+
+If you need to recompile from scratch, you have to make sure you clean up
+first. There is a procedure to do it--enter the I<exact> MMS line you used
+to compile and add "realclean" at the end, like this:
+
+if the compile command was:
+
+ MMS
+
+then the cleanup command ought to be:
+
+ MMS realclean
+
+If you do not do this things may behave erratically during the subsequent
+rebuild attempt. They might not, too, so it is best to be sure and do it.
+
+=head1 Installing Perl
+
+There are several steps you need to take to get Perl installed and
+running.
+
+=over 4
+
+=item 1
+
+Check your default file protections with
+
+ SHOW PROTECTION /DEFAULT
+
+and adjust if necessary with SET PROTECTION=(code)/DEFAULT.
+
+=item 2
+
+Decide where you want Perl to be installed (unless you have already done so
+by using the "prefix" configuration parameter -- see the example in the
+"Configuring the Perl build" section).
+
+The DCL script PERL_SETUP.COM that is written by CONFIGURE.COM will help you
+with the definition of the PERL_ROOT and PERLSHR logical names and the PERL
+foreign command symbol. Take a look at PERL_SETUP.COM and modify it if you
+want to. The installation process will execute PERL_SETUP.COM and copy
+files to the directory tree pointed to by the PERL_ROOT logical name defined
+there, so make sure that you have write access to the parent directory of
+what will become the root of your Perl installation.
+
+=item 3
+
+Run the install script via:
+
+ MMS install
+
+or
+
+ MMK install
+
+If for some reason it complains about target INSTALL being up to date,
+throw a /FORCE switch on the MMS or MMK command.
+
+=back
+
+Copy PERL_SETUP.COM to a place accessible to your perl users.
+
+For example:
+
+ COPY PERL_SETUP.COM SYS$LIBRARY:
+
+If you want to have everyone on the system have access to perl
+then add a line that reads
+
+ $ @sys$library:perl_setup
+
+to SYS$MANAGER:SYLOGIN.COM.
+
+Two alternatives to the foreign symbol would be to install PERL into
+DCLTABLES.EXE (Check out the section "Installing Perl into DCLTABLES
+(optional)" for more information), or put the image in a
+directory that's in your DCL$PATH (if you're using VMS V6.2 or higher).
+
+An alternative to having PERL_SETUP.COM define the PERLSHR logical name
+is to simply copy it into the system shareable library directory with:
+
+ copy perl_root:[000000]perlshr.exe sys$share:
+
+See also the "INSTALLing images (optional)" section.
+
+=head2 Installing Perl into DCLTABLES (optional) on VMS
+
+Execute the following command file to define PERL as a DCL command.
+You'll need CMKRNL privilege to install the new dcltables.exe.
+
+ $ create perl.cld
+ !
+ ! modify to reflect location of your perl.exe
+ !
+ define verb perl
+ image perl_root:[000000]perl.exe
+ cliflags (foreign)
+ $!
+ $ set command perl /table=sys$common:[syslib]dcltables.exe -
+ /output=sys$common:[syslib]dcltables.exe
+ $ install replace sys$common:[syslib]dcltables.exe
+ $ exit
+
+=head2 INSTALLing Perl images (optional) on VMS
+
+On systems that are using perl quite a bit, and particularly those with
+minimal RAM, you can boost the performance of perl by INSTALLing it as
+a known image. PERLSHR.EXE is typically larger than 3000 blocks
+and that is a reasonably large amount of IO to load each time perl is
+invoked.
+
+ INSTALL ADD PERLSHR/SHARE
+ INSTALL ADD PERL/HEADER
+
+should be enough for PERLSHR.EXE (/share implies /header and /open),
+while /HEADER should do for PERL.EXE (perl.exe is not a shared image).
+
+If your code 'use's modules, check to see if there is a shareable image for
+them, too. In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File,
+DCLsym, and Stdio, and other extensions all have shared images that can be
+installed /SHARE.
+
+How much of a win depends on your memory situation, but if you are firing
+off perl with any regularity (like more than once every 20 seconds or so)
+it is probably beneficial to INSTALL at least portions of perl.
+
+While there is code in perl to remove privileges as it runs you are advised
+to NOT INSTALL PERL.EXE with PRIVs!
+
+=head2 Running h2ph to create perl header files (optional) on VMS
+
+If using HP C, ensure that you have extracted loose versions of your
+compiler's header or *.H files. Be sure to check the contents of:
+
+ SYS$LIBRARY:DECC$RTLDEF.TLB
+ SYS$LIBRARY:SYS$LIB_C.TLB
+ SYS$LIBRARY:SYS$STARLET_C.TLB
+
+etcetera.
+
+If using GNU cc then also check your GNU_CC:[000000...] tree for the locations
+of the GNU cc headers.
+
+=head1 Reporting Bugs
+
+If you come across what you think might be a bug in Perl, please report
+it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through
+the process of creating a bug report. This script includes details of your
+installation, and is very handy. Completed bug reports should go to
+perlbug@perl.com.
+
+=head1 CAVEATS
+
+Probably the single biggest gotcha in compiling Perl is giving the wrong
+switches to MMS/MMK when you build. Use I<exactly> what the configure.com
+script prints!
+
+The next big gotcha is directory depth. Perl can create directories four,
+five, or even six levels deep during the build, so you don't have to be
+too deep to start to hit the RMS 8 level limit (for ODS 2 volumes which were
+common on versions of VMS prior to V7.2 and even with V7.3 on the VAX).
+It is best to do:
+
+ DEFINE/TRANS=(CONC,TERM) PERLSRC "disk:[dir.dir.dir.perldir.]"
+ SET DEFAULT PERLSRC:[000000]
+
+before building in cases where you have to unpack the distribution so deep
+(note the trailing period in the definition of PERLSRC). Perl modules
+from CPAN can be just as bad (or worse), so watch out for them, too. Perl's
+configuration script will warn if it thinks you are too deep (at least on
+a VAX or on Alpha versions of VMS prior to 7.2). But MakeMaker will not
+warn you if you start out building a module too deep in a directory.
+
+As noted above ODS-5 escape sequences such as ^. can break the perl
+build. Solutions include renaming files and directories as needed
+when unpacking perl or CPAN modules on ODS-5 volumes.
+
+Be sure that the process that you use to build perl has a PGFLQ greater
+than 100000. Be sure to have a correct local time zone to UTC offset
+defined (in seconds) in the logical name SYS$TIMEZONE_DIFFERENTIAL before
+running the regression test suite. The SYS$MANAGER:UTC$CONFIGURE_TDF.COM
+procedure will help you set that logical for your system but may require
+system privileges. For example, a location 5 hours west of UTC (such as
+the US East coast while not on daylight savings time) would have:
+
+ DEFINE SYS$TIMEZONE_DIFFERENTIAL "-18000"
+
+A final thing that causes trouble is leftover pieces from a failed
+build. If things go wrong make sure you do a "(MMK|MMS|make) realclean"
+before you rebuild.
+
+=head2 GNU issues with Perl on VMS
+
+It has been a while since the GNU utilities such as GCC or GNU make
+were used to build perl on VMS. Hence they may require a great deal
+of source code modification to work again.
+
+ http://www.progis.de/
+
+=head2 Floating Point Considerations
+
+Prior to 5.8.0, Perl simply accepted the default floating point options of the
+C compiler, namely representing doubles with D_FLOAT on VAX and G_FLOAT on
+Alpha. Single precision floating point values are represented in F_FLOAT
+format when either D_FLOAT or G_FLOAT is in use for doubles. Beginning with
+5.8.0, Alpha builds now use IEEE floating point formats by default, which in
+VMS parlance are S_FLOAT for singles and T_FLOAT for doubles. IEEE is not
+available on VAX, so F_FLOAT and D_FLOAT remain the defaults for singles and
+doubles respectively. Itanium builds have always used IEEE by default. The
+available non-default options are G_FLOAT on VAX and D_FLOAT or G_FLOAT on
+Alpha or Itanium.
+
+The use of IEEE on Alpha or Itanium introduces NaN, infinity, and denormalization
+capabilities not available with D_FLOAT and G_FLOAT. When using one of those
+non-IEEE formats, silent underflow and overflow are emulated in the conversion
+of strings to numbers, but it is preferable to get the real thing by using
+IEEE where possible.
+
+Regardless of what floating point format you consider preferable, be aware
+that the choice may have an impact on compatibility with external libraries,
+such as database interfaces, and with existing data, such as data created with
+the C<pack> function and written to disk, or data stored via the Storable
+extension. For example, a C<pack("d", $foo)")> will create a D_FLOAT,
+G_FLOAT, or T_FLOAT depending on what your Perl was configured with. When
+written to disk, the value can only be retrieved later by a Perl configured
+with the same floating point option that was in effect when it was created.
+
+To obtain a non-IEEE build on Alpha, simply answer no to the "Use IEEE math?"
+question during the configuration. To obtain an option different from the C
+compiler default on either VAX or Alpha, put in the option that you want in
+answer to the "Any additional cc flags?" question. For example, to obtain a
+G_FLOAT build on VAX, put in C</FLOAT=G_FLOAT>.
+
+=head1 Mailing Lists
+
+There are several mailing lists available to the Perl porter. For VMS
+specific issues (including both Perl questions and installation problems)
+there is the VMSPERL mailing list. It is usually a low-volume (10-12
+messages a week) mailing list.
+
+To subscribe, send a mail message to VMSPERL-SUBSCRIBE@PERL.ORG. The VMSPERL
+mailing list address is VMSPERL@PERL.ORG. Any mail sent there gets echoed
+to all subscribers of the list. There is a searchable archive of the list
+on the web at:
+
+ http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/
+
+To unsubscribe from VMSPERL send a message to VMSPERL-UNSUBSCRIBE@PERL.ORG.
+Be sure to do so from the subscribed account that you are canceling.
+
+=head2 Web sites for Perl on VMS
+
+Vmsperl pages on the web include:
+
+ http://www.sidhe.org/vmsperl/index.html
+ http://www.cpan.org/modules/by-module/VMS/
+ http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/
+ http://www-ang.kfunigraz.ac.at/~binder/perl.html
+ http://archive.develooper.com/vmsperl@perl.org/
+ http://h71000.www7.hp.com/openvms/products/ips/apache/csws_modperl.html
+
+=head1 SEE ALSO
+
+Perl information for users and programmers about the port of perl to VMS is
+available from the [.POD]PERLVMS.POD file that gets installed as L<perlvms>.
+For administrators the perlvms document also includes a detailed discussion
+of extending vmsperl with CPAN modules after Perl has been installed.
+
+=head1 AUTHORS
+
+Originally by Charles Bailey bailey@newman.upenn.edu. See the git repository
+for history.
+
+=head1 ACKNOWLEDGEMENTS
+
+A real big thanks needs to go to Charles Bailey
+bailey@newman.upenn.edu, who is ultimately responsible for Perl 5.004
+running on VMS. Without him, nothing the rest of us have done would be at
+all important.
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
+of Perl 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>
+
+ Tim Adye T.J.Adye@rl.ac.uk
+ for the VMS emulations of getpw*()
+ David Denholm denholm@conmat.phys.soton.ac.uk
for extensive testing and provision of pipe and SocketShr code,
- Mark Pizzolato <mark@infocomm.com>
+ Mark Pizzolato mark@infocomm.com
for the getredirection() code
- Rich Salz <rsalz@bbn.com>
+ 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
+ Peter Prymmer pvhp@best.com
+ for extensive testing, as well as development work on
+ configuration and documentation for VMS Perl,
+ Dan Sugalski dan@sidhe.org
+ for extensive contributions to recent version support,
+ development of VMS-specific extensions, and dissemination
+ of information about VMS Perl,
+ the Stanford Synchrotron Radiation Laboratory and the
+ Laboratory of Nuclear Studies at Cornell University for
+ the opportunity to test and develop for the AXP,
+ John Hasstedt John.Hasstedt@sunysb.edu
+ for VAX VMS V7.2 support
+ John Malmberg wb8tyw@qsl.net
+ for ODS-5 filename handling and other modernizations
+
+and to the entire VMSperl group for useful advice and suggestions. In
+addition the perl5-porters 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
+gratitude is due to Larry Wall larry@wall.org, for having the ideas which
have made our sleepless nights possible.
Thanks,
The VMSperl group
+
+=cut
+
https://perl5.git.perl.org / perl5.git / blobdiff