X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/a0d0e21ea6ea90a22318550944fe6cb09ae10cda..df062bd814a144622e66051206fe09cb86c87d07:/README.vms diff --git a/README.vms b/README.vms index dbf6251..04947e0 100644 --- a/README.vms +++ b/README.vms @@ -1,232 +1,673 @@ -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. + +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 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). + + +=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 use the ODS-2 +compatibility qualifier. Instead, use a command like the following: + + vmstar -xvf perl-5^.17^.6.tar + +Then rename the top-level source directory like so: + + set security/protection=(o:rwed) perl-5^.17^.6.dir + rename perl-5^.17^.6.dir perl-5_17_6.dir + +The reason for this last step is that while filenames with multiple dots +are generally supported by Perl on VMS, I 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. 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. It does this via the socket +routines built into the CRTL regarless of which TCP/IP stack your system +has. + +=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 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 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 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 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 function and written to disk, or data stored via the Storable +extension. For example, a C 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. + +=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. +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 + + 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 Pizzolato mark@infocomm.com for the getredirection() code - Rich Salz + Rich Salz rsalz@bbn.com for readdir() and related routines - Denis Haskin - for work on a pod-to-hlp translator for the perl5 documentation - Richard Dyson and - Kent Covert - 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 -and Tim Bunce , 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 , 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 +