X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.vms;h=b1002e919235f10d4d5cc279a6be03d441804bcc;hb=4beedc23b598a493399ba23c8c4bd5448e52283a;hp=dbf62513116267ccdc9c3ef31311d68c67fdbd96;hpb=a0d0e21ea6ea90a22318550944fe6cb09ae10cda;p=p5sagit%2Fp5-mst-13.2.git diff --git a/README.vms b/README.vms index dbf6251..b1002e9 100644 --- a/README.vms +++ b/README.vms @@ -1,231 +1,367 @@ -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. +Last Revised 21-July-1998 by Dan Sugalski +Originally by Charles Bailey +* 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 +VaxC and 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 for AXP, or Dec C, or gcc for 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. + + +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 quotes 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 you 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. + +* 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. + +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) 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. + +5) Optionally define the command PERLBUG (the Perl bug report generator) as +PERLBUG :== "$PERL_ROOT:[000000]PERL PERL_ROOT:[LIB]PERLBUG.COM" + +6) 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" + +7) 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,a s they can cause some fairly subtle problems. + +* 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. + +* 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. + +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: + - Newlines are lost on I/O through pipes, causing lines to run together. + This shows up as RMS RTB errors when reading from a pipe. You can + work around this by having one process write data to a file, and + then having the other read the file, instead of the pipe. This is + fixed in version 4 of DECC. + - The modf() routine returns a non-integral value for some values above + INT_MAX; the Perl "int" operator will return a non-integral value in + these cases. This is fixed in version 4 of DECC. + - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine + changes the process default device and directory permanently, even + though the call specified that the change should not persist after + Perl exited. This is fixed by DEC CSC patch AXPACRT04_061. + +* 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's usually a low-volume (10-12 +messages a week) mailing list. + +The subscription address is VMSPERL-REQUEST@NEWMAN.UPENN.EDU. Send a mail +message with just the words SUBSCRIBE VMSPERL in the body of the message. + +The VMSPERL mailing list address is VMSPERL@NEWMAN.UPENN.EDU. Any mail +sent there gets echoed to all subscribers of the list. + +The Perl5-Porters list is for anyone involved in porting Perl to a +platform. This includes you, if you want to participate. It's a high-volume +list (60-100 messages a day during active development times), so be sure +you want to be there. The subscription address is +Perl5-Porters-request@perl.org. Send a message with just the word SUBSCRIBE +in the body. The posting address is Perl5-Porters@perl.org. * Acknowledgements +A real big thanks needs to go to Charles Bailey +, 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: + Tim Adye + for the VMS emulations of getpw*() David Denholm for extensive testing and provision of pipe and SocketShr code, Mark Pizzolato for the getredirection() code Rich Salz 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 + 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 the opportunity to test and develop for the AXP, +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 , for having the ideas which have made our sleepless nights possible. Thanks,