+Last Revised 21-July-1998 by Dan Sugalski <sugalskd@ous.edu>
+Originally by Charles Bailey <bailey@newman.upenn.edu>
+
+* Important safety tip
+
+The build and install procedures have changed significantly from the 5.004
+releases! Make sure you read the "Building Perl" and "Installing Perl"
+sections before you build or install.
+
+Also note that, as of 5.005, an ANSI C compliant compiler is required to
+build Perl. Vax C is *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. Sorry about that.
+
+If you're stuck without Dec C (the Vax C license should be good for Dec C,
+but the media charges might prohibit an upgrade), consider getting Gnu C
+instead.
+
+* Intro
+
+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 incompatibilites 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 coursse 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!
+
+The current sources and build procedures have been tested on a VAX using
+Dec C, and on an AXP using Dec C. If you run into problems with
+other compilers, please let us know.
+
+There are issues with varions versions of Dec C, so if you're not running a
+relatively modern version, check the Dec C issues section later on in this
+document.
+
+* Other required software
+
+In addition to VMS, you'll need:
+ 1) A C compiler. Dec C or gcc for AXP or the VAX.
+ 2) A make tool. Dec's MMS (v2.6 or later), or MadGoat's free MMS
+ analog MMK (available from ftp.madgoat.com/madgoat) both work
+ just fine. Gnu Make might work, but it's been so long since
+ anyone's tested it that we're not sure. MMK's free, though, so
+ go ahead and use that.
+
+You may also want to have on hand:
+ 1) UNZIP.EXE for VMS available from a number of web/ftp sites.
+ http://www.cdrom.com/pub/infozip/UnZip.html
+ http://www.openvms.digital.com/cd/INFO-ZIP/
+ ftp://ftp.digital.com/pub/VMS/
+ ftp://ftp.openvms.digital.com/
+ ftp://ftp.madgoat.com/madgoat/
+ ftp://ftp.wku.edu/vms/
+ 2) GUNZIP/GZIP.EXE for VMS available from a number of web/ftp sites.
+ http://www.fsf.org/order/ftp.html
+ ftp://ftp.uu.net/archive/systems/gnu/diffutils*.tar.gz
+ ftp://gatekeeper.dec.com/pub/GNU/diffutils*.tar.gz
+ ftp://ftp.gnu.org/pub/gnu/diffutils*.tar.gz
+ http://www.openvms.digital.com/cd/GZIP/
+ ftp://ftp.digital.com/pub/VMS/
+ 3) VMS TAR also available from a number of web/ftp sites.
+ ftp://ftp.lp.se/vms/
+ http://www.openvms.digital.com/cd/VMSTAR/
+ ftp://ftp.digital.com/pub/VMS/
+Please note that UNZIP and GUNZIP are not the same thing (they work with
+different formats). Most of the useful files from CPAN (the Comprehensive
+Perl Archive Network) are in .tar.gz 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 stack and either
+Dec C, or socket libraries. See the Socket Support topic for more details.
+
+* Building Perl
+
+Building perl has two steps, configuration and compilation.
+
+To configure perl (a necessary first step), issue the command
+
+@CONFIGURE
+
+from the top of an unpacked perl directory. You'll 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's built.
+
+If you've got multiple C compilers installed, you'll have your choice of
+which one to use. Various older versions of Dec C had some gotchas, so if
+you're using a version older than 5.2, check the Dec C Issues section.
+
+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 command, sit back and wait. Perl should build and
+link without a problem. If it doesn't, check the Gotchas to watch out for
+section. If that doesn't help, send some mail to the VMSPERL mailing list.
+Instructions are in the Mailing Lists section.
+
+As a handy shortcut, the command:
+
+@CONFIGURE "-des"
+
+(note the quotation marks and case) will choose reasonable defaults. (It
+takes Dec C over Gnu C, Dec C sockets over SOCKETSHR sockets, and either
+over no sockets)
+
+* Testing Perl
+
+Once Perl has built cleanly, you need to test it to make sure things work.
+This step is very important--there are always things that can go wrong
+somehow and get you a dysfunctional Perl.
+
+Testing is very easy, though, as there's a full test suite in the perl
+distribution. To run the tests, enter the *exact* MMS line you used to
+compile Perl and add the word "test" to the end, like this:
+
+Compile Command:
+
+$MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1")
+
+Test Command:
+
+$MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1") test
+
+MMS 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.
+
+If any tests fail, it means something's wrong with Perl. 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 *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 info 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 [.op]time failed, then you'd do this:
+
+$ @[.VMS]TEST .EXE "-v" [.OP]TIME.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 config info, and can help us diagnose the problem.
+If (and only if) that did not work then try enclosing the output of:
+
+@[.vms]myconfig
+
+* Cleaning up and starting fresh
+
+If you need to recompile from scratch, you have to make sure you clean up
+first. There's a procedure to do it--enter the *exact* MMS line you used to
+compile and add "realclean" at the end, like this:
+
+Compile Command:
+
+$MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1")
+
+Cleanup Command:
+
+$MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1") realclean
+
+If you don't do this, things may behave erratically. They might not, too,
+so it's best to be sure and do it.
+
+* Installing Perl
+
+There are several steps you need to take to get Perl installed and
+running.
+
+1) Create a directory somewhere and define the concealed logical PERL_ROOT
+to point to it. For example, DEFINE/TRANS=(CONC,TERM) PERL_ROOT dka200:[perl.]
+
+2) 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.
+
+The script [.VMS]PERL_SETUP.COM that is written by CONFIGURE.COM
+will take care of most of the following:
+
+3) Either define the symbol PERL somewhere, such as
+SYS$MANAGER:SYLOGIN.COM, to be "PERL :== $PERL_ROOT:[000000]PERL.EXE", or
+install Perl into DCLTABLES.EXE (Check out the section "Installing Perl
+into DCLTABLES" for more info), or put the image in a directory that's in
+your DCL$PATH (if you're using VMS 6.2 or higher).
+
+4) Either define the logical name PERLSHR somewhere
+(such as in PERL_SETUP.COM) like so:
+DEFINE/NOLOG PERLSHR PERL_ROOT:[000000]PERLSHR.EXE
+or copy perl_root:[000000]perlshr.exe sys$share:.
+
+5) Optionally define the command PERLDOC as
+PERLDOC == "$PERL_ROOT:[000000]PERL PERL_ROOT:[LIB.POD]PERLDOC.COM -t"
+Note that if you wish to use most as a pager please see
+ftp://space.mit.edu/pub/davis/ for both most and slang (or perhaps
+ftp://ftp.wku.edu/vms/narnia/most.zip ).
+
+6) Optionally define the command PERLBUG (the Perl bug report generator) as
+PERLBUG == "$PERL_ROOT:[000000]PERL PERL_ROOT:[LIB]PERLBUG.COM"
+
+7) Optionally define the command POD2MAN (Converts POD files to nroff
+source suitable for converting to man pages. Also quiets complaints during
+module builds) as
+
+DEFINE/NOLOG POD2MAN PERL_ROOT:[LIB.POD]POD2MAN.COM
+POD2MAN == "$PERL_ROOT:[000000]PERL POD2MAN"
+
+8) Optionally define the command POD2TEXT (Converts POD files to text,
+which is required for perldoc -f to work properly) as
+
+DEFINE/NOLOG POD2TEXT PERL_ROOT:[LIB.POD]POD2TEXT.COM
+POD2TEXT == "$PERL_ROOT:[000000]PERL POD2TEXT"
+
+In all these cases, if you've got PERL defined as a foreign command, you
+can replace $PERL_ROOT:[000000]PERL with ''perl'. If you've installed perl
+into DCLTABLES, replace it with just perl.
+
+* Installing Perl into DCLTABLES
+
+Execute the following command file to define PERL as a DCL command.
+You'll need CMKRNL priv 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
+
+* Changing compile-time things
+
+Most of the user-definable features of Perl are enabled or disabled in
+[.VMS]CONFIG.VMS. There's 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're
+doing, since changes here can get you a busted perl.
+
+Odds are that there's nothing here to change, unless you're on a version of
+VMS later than 6.2 and Dec C later than 5.6. Even if you are, the correct
+values will still be chosen, most likely. Poking around here should be
+unnecessary.
+
+The one exception is the various *DIR install locations. Changing those
+requires changes in genconfig.pl as well. Be really careful if you need to
+change these, as they can cause some fairly subtle problems.
+
+* INSTALLing images
+
+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 1500 blocks
+and that is a reasonably large amount of IO to load each time perl is
+invoked.
+
+ INSTALL ADD PERLSHR/SHARE
+
+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's an executable for
+them, too. In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File,
+DCLsym, and Stdio all have shared images that can be installed /SHARE.
+
+How much of a win depends on your memory situation, but if you're firing
+off perl with any regularity (like more than once every 20 seconds or so)
+it's probably a win.
+
+While there is code in perl to remove privileges as it runs you are advised
+to NOT INSTALL PERL.EXE with PRIVs!
+
+* Extra things in the Perl distribution
+
+In addition to the standard stuff that gets installed, there are two
+optional extensions, DCLSYM and STDIO, that are handy. Instructions for
+these two modules are in [.VMS.EXT.DCLSYM] and [.VMS.EXT.STDIO],
+respectively. They are built automatically for versions of perl >= 5.005.
+
+* Socket Support
+
+Perl includes a number of functions for IP sockets, which are available if
+you choose to compile Perl with socket support (see the section Compiling
+Perl for more info on selecting a socket stack). 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 most portable solution uses the SOCKETSHR library. In combination with
+either UCX or NetLib, this supports all the major TCP stacks (Multinet,
+Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with
+all the compilers on both VAX and Alpha. The socket interface is 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.
+
+The other 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.
+
+* 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.
+
+* Gotchas to watch out for
+
+Probably the single biggest gotcha in compiling Perl is giving the wrong
+switches to MMS/MMK when you build. Use *exactly* what the configure script
+prints!
+
+The next big gotcha is directory depth. Perl can create directories four
+and five levels deep during the build, so you don't have to be too deep to
+start to hit the RMS 8 level point. It's best to do a
+$DEFINE/TRANS=(CONC,TERM) PERLSRC disk:[dir.dir.dir.perldir.]" (note the
+trailing period) and $SET DEFAULT PERLSRC:[000000] before building. Perl
+modules can be just as bad (or worse), so watch out for them, too. The
+configuration script will warn if it thinks you're too deep (at least on
+versions of VMS prior to 7.2).
+
+Finally, the third thing that bites people is leftover pieces from a failed
+build. If things go wrong, make sure you do a "(MMK|MMS|make) realclean"
+before you rebuild.
+
+* Dec C issues
+
+Note to DECC users: Some early versions (pre-5.2, some pre-4. If you're Dec
+C 5.x or higher, with current patches if anym you're fine) of the DECCRTL
+contained a few bugs which affect Perl performance: