README.vms

   1 Last Revised 11-September-1997 by Dan Sugalski <sugalsd@lbcc.cc.or.us>
   2 Originally by Charles Bailey <bailey@newman.upenn.edu>
   3
   4 * Intro
   5
   6 The VMS port of Perl is as functionally complete as any other Perl port
   7 (and as complete as the ports on some Unix systems). The Perl binaries
   8 provide all the Perl system calls that are either available under VMS or
   9 reasonably emulated. There are some incompatibilites in process handling
  10 (e.g the fork/exec model for creating subprocesses doesn't do what you
  11 might expect under Unix), mainly because VMS and Unix handle processes and
  12 sub-processes very differently.
  13
  14 There are still some unimplemented system functions, and of coursse we
  15 could use modules implementing useful VMS system services, so if you'd like
  16 to lend a hand we'd love to have you. Join the Perl Porting Team Now!
  17
  18 The current sources and build procedures have been tested on a VAX using
  19 VaxC and Dec C, and on an AXP using Dec C. If you run into problems with
  20 other compilers, please let us know.
  21
  22 There are issues with varions versions of Dec C, so if you're not running a
  23 relatively modern version, check the Dec C issues section later on in this
  24 document.
  25
  26 * Other required software
  27
  28 In addition to VMS, you'll need:
  29         1) A C compiler. Dec C for AXP, or VAX C, Dec C, or gcc for the
  30            VAX.
  31         2) A make tool. Dec's MMS (v2.6 or later), or MadGoat's free MMS
  32            analog MMK (available from ftp.madgoat.com/madgoat) both work
  33            just fine. Gnu Make might work, but it's been so long since
  34            anyone's tested it that we're not sure. MMK's free, though, so
  35            go ahead and use that.
  36
  37
  38 If you want to include socket support, you'll need a TCP stack and either
  39 Dec C, or socket libraries. See the Socket Support topic for more details.
  40
  41 * Compiling Perl
  42
  43 >From the top level of the Perl source directory, do this:
  44
  45 MMS/DESCRIP=[.VMS]DESCRIP.MMS
  46
  47 If you're on an Alpha, add /Macro=("__AXP__=1","decc=1")
  48 If you're using Dec C as your C compiler (you are on all alphas), add
  49 /Macro=("decc=1")
  50 If Vac C is your default C compiler and you want to use Dec C, add
  51 /Macro=("CC=CC/DECC") (Don't forget the /macro=("decc=1")
  52 If Dec C is your default C compiler and you want to use Vax C, add
  53 /Macro=("CC=CC/VAXC")
  54 If you want Socket support and are using the SOCKETSHR socket library, add
  55 /Macro=("SOCKETSHR_SOCKETS=1")
  56 If you want Socket support and are using the Dec C RTL socket interface
  57 (You must be using Dec C for this), add /Macro=("DECC_SOCKETS=1")
  58
  59 If you have multiple /macro= items, combine them together in one /Macro=()
  60 switch, with all the options inside the parentheses separated by commas.
  61
  62 Samples:
  63
  64 VMS AXP, with Socketshr sockets:
  65
  66 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("decc=1","__AXP__=1","SOCKETSHR_SOCKETS=1")
  67
  68 VMS AXP with no sockets
  69
  70 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("decc=1","__AXP__=1")
  71
  72 VMS AXP with the Dec C RTL sockets
  73
  74 $MMS/DESCRIP=[.VMS]/Macro=("decc=1","__AXP__=1","DECC_SOCKETS=1")
  75
  76 VMS VAX with default system compiler, no sockets
  77
  78 $MMS/DESCRIP=[.VMS]DESCRIP.MMS
  79
  80 VMS VAX with Dec C compiler, no sockets
  81
  82 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("CC=CC/DECC","decc=1")
  83
  84 VMS VAX with Dec C compiler, Dec C RTL sockets
  85
  86 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("CC=CC/DECC","decc=1","DECC_SOCKETS=1")
  87
  88 VMS VAX with Dec C compiler, Socketshr sockets
  89
  90 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("CC=CC/DECC","decc=1","SOCKETSHR_SOCKETS=1")
  91
  92 Using Dec C is recommended over Vax C. The compiler is newer, and
  93 supported. (Vax C was decommisioned around 1993) Various older versions had
  94 some gotchas, so if you're using a version older than 5.2, check the Dec C
  95 Issues section.
  96
  97 We'll also point out that Dec C will get you at least a ten-fold increase
  98 in line-oriented IO over Vax C. The optimizer is amazingly better, too. If
  99 you can use Dec C, then you *really*, *really* should.
 100
 101
 102 Once you issue your MMS command, sit back and wait. Perl should build and
 103 link without a problem. If it doesn't, check the Gotchas to watch out for
 104 section. If that doesn't help, send some mail to the VMSPERL mailing list.
 105 Instructions are in the Mailing Lists section.
 106
 107 * Testing Perl
 108
 109 Once Perl has built cleanly, you need to test it to make sure things work.
 110 This step is very important--there are always things that can go wrong
 111 somehow and get you a dysfunctional Perl.
 112
 113 Testing is very easy, though, as there's a full test suite in the perl
 114 distribution. To run the tests, enter the *exact* MMS line you used to
 115 compile Perl and add the word "test" to the end, like this:
 116
 117 Compile Command:
 118
 119 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1")
 120
 121 Test Command:
 122
 123 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1") test
 124
 125 MMS will run all the tests. This may take some time, as there are a lot of
 126 tests. If any tests fail, there will be a note made on-screen. At the end
 127 of all the tests, a summary of the tests, the number passed and failed, and
 128 the time taken will be displayed.
 129
 130 If any tests fail, it means something's wrong with Perl. If the test suite
 131 hangs (some tests can take upwards of two or three minutes, or more if
 132 you're on an especially slow machine, depending on you machine speed, so
 133 don't be hasty), then the test *after* the last one displayed failed. Don't
 134 install Perl unless you're confident that you're OK. Regardless of how
 135 confident you are, make a bug report to the VMSPerl mailing list.
 136
 137 If one or more tests fail, you can get more info on the failure by issuing
 138 this command sequence:
 139
 140 $ SET DEFAULT [.T]
 141 $ @[-.VMS]TEST .typ -v [.subdir]test.T
 142
 143 where ".typ" is the file type of the Perl images you just built (if you
 144 didn't do anything special, use .EXE), and "[.subdir]test.T" is the test
 145 that failed. For example, with a normal Perl build, if the test indicated
 146 that [.op]time failed, then you'd do this:
 147
 148 $ SET DEFAULT [.T]
 149 $ @[-.VMS]TEST .EXE -v [.OP]TIME.T
 150
 151 When you send in a bug report for failed tests, please include the output
 152 from this command, which is run from the main source directory:
 153
 154 MCR []MINIPERL "-V"
 155
 156 Note that "-V" really is a capital V in double quotes. This will dump out a
 157 couple of screens worth of config info, and can help us diagnose the problem.
 158
 159 * Cleaning up and starting fresh
 160
 161 If you need to recompile from scratch, you have to make sure you clean up
 162 first. There's a procedure to do it--enter the *exact* MMS line you used to
 163 compile and add "realclean" at the end, like this:
 164
 165 Compile Command:
 166
 167 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1")
 168
 169 Cleanup Command:
 170
 171 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1") realclean
 172
 173 If you don't do this, things may behave erratically. They might not, too,
 174 so it's best to be sure and do it.
 175
 176 * Installing Perl
 177
 178 There are several steps you need to take to get Perl installed and
 179 running. At some point we'll have a working install in DESCRIP.MMS, but for
 180 right now the procedure's manual, and goes like this.
 181
 182 1) Create a directory somewhere and define the concealed logical PERL_ROOT
 183 to point to it. For example, DEFINE/TRANS=(CONC,TERM) PERL_ROOT dka200:[perl.]
 184
 185 2) Copy perl.exe into PERL_ROOT:[000000]
 186
 187 3) Copy everything in [.LIB] and [.UTILS] (including all the
 188 subdirectories!) to PERL_ROOT:[LIB] and PERL_ROOT:[UTILS].
 189
 190 4) Either copy PERLSHR.EXE to SYS$SHARE, or to somewhere globally accessble
 191 and define the logical PERLSHR to point to it (DEFINE PERLSHR
 192 PERL_ROOT:[000000]PERLSHR.EXE or something like that). The PerlShr image
 193 should have W:RE protections on it. (Just W:E triggers increased security in
 194 the image activator. Not a huge problem, but Perl will need to have any
 195 other shared image it accesses INSTALLed. It's a huge pain, so don't unless
 196 you know what you're doing)
 197
 198 5) Either define the symbol PERL somewhere, such as
 199 SYS$MANAGER:SYLOGIN.COM, to be "PERL :== $PERL_ROOT:[000000]PERL.EXE", or
 200 install Perl into DCLTABLES.EXE )Check out the section "Installing Perl
 201 into DCLTABLES" for more info), or put the image in a directory that's in
 202 your DCL$PATH (if you're using VMS 6.2 or higher).
 203
 204 6) Optionally define the command PERLDOC as
 205 PERLDOC :== $PERL_ROOT:[000000]PERL PERL_ROOT:[LIB.POD]PERLDOC.COM -T
 206
 207 7) Optionally define the command PERLBUG (the Perl bug report generator) as
 208 PERLBUG :== $PERL_ROOT:[000000]PERL PERL_ROOT:[LIB]PERLBUG.COM"
 209
 210 8) Optionally define the command POD2MAN (Converts POD files to nroff
 211 source suitable for converting to man pages. Also quiets complaints during
 212 module builds) as
 213
 214 DEFINE/NOLOG POD2MAN PERL_ROOT:[LIB.POD]POD2MAN.COM
 215 POD2MAN :== $PERL_ROOT:[000000]PERL POD2MAN
 216
 217 * Installing Perl into DCLTABLES
 218
 219 Courtesy of Brad  Hughes:
 220
 221 Put the following, modified to reflect where your .exe is, in PERL.CLD:
 222
 223 define verb perl
 224 image perl_root:[exe]perl.exe
 225 cliflags (foreign)
 226
 227 and then
 228
 229 $ set command perl /table=sys$common:[syslib]dcltables.exe -
 230  /output=sys$common:[syslib]dcltables.exe
 231 $ install replace sys$common:[syslib]dcltables.exe
 232
 233 and you don't need perl :== $perl_root:[exe]perl.exe.
 234
 235 * Changing compile-time things
 236
 237 Most of the user-definable features of Perl are enabled or disabled in
 238 [.VMS]CONFIG.VMS. There's code in there to Do The Right Thing, but that may
 239 end up being the wrong thing for you. Make sure you understand what you're
 240 doing, since changes here can get you a busted perl.
 241
 242 Odds are that there's nothing here to change, unless you're on a version of
 243 VMS later than 6.2 and Dec C later than 5.6. Even if you are, the correct
 244 values will still be chosen, most likely. Poking around here should be
 245 unnecessary.
 246
 247 The one exception is the various *DIR install locations. Changing those
 248 requires changes in genconfig.pl as well. Be really careful if you need to
 249 change these,a s they can cause some fairly subtle problems.
 250
 251 * Extra things in the Perl distribution
 252
 253 In addition to the standard stuff that gets installed, there are two
 254 optional extensions, DCLSYM and STDIO, that are handy. Instructions for
 255 these two modules are in [.VMS.EXT.DCLSYM] and [.VMS.EXT.STDIO],
 256 respectively.
 257
 258 * Socket Support
 259
 260 Perl includes a number of functions for IP sockets, which are available if
 261 you choose to compile Perl with socket support. (See the section Compiling
 262 Perl for more info on selecting a socket stack) Since IP networking is an
 263 optional addition to VMS, there are several different IP stacks
 264 available. How well integrated they are into the system depends on the
 265 stack, your version of VMS, and the version of your C compiler.
 266
 267 The most portable solution uses the SOCKETSHR library. In combination with
 268 either UCX or NetLib, this supports all the major TCP stacks (Multinet,
 269 Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with
 270 all the compilers on both VAX and Alpha. The socket interface is also
 271 consistent across versions of VMS and C compilers. It has a problem with
 272 UDP sockets when used with Multinet, though, so you should be aware of
 273 that.
 274
 275 The other solution available is to use the socket routines built into Dec
 276 C. Which routines are available depend on the version of VMS you're
 277 running, and require proper UCX emulation by your TCP/IP vendor.
 278 Relatively current versions of Multinet, TCPWare, Pathway, and UCX all
 279 provide the required libraries--check your manuals or release notes to see
 280 if your version is new enough.
 281
 282 * Reporting Bugs
 283
 284 If you come across what you think might be a bug in Perl, please report
 285 it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through
 286 the process of creating a bug report. This script includes details of your
 287 installation, and is very handy. Completed bug reports should go to
 288 PERLBUG@PERL.COM.
 289
 290 * Gotchas to watch out for
 291
 292 Probably the single biggest gotcha in compiling Perl is giving the wrong
 293 switches to MMS/MMK when you build. If Perl's building oddly, double-check
 294 your switches. If you're on a VAX, be sure to add a /Macro=("decc=1") if
 295 you're using Dec C, and if you're on an alpha and using MMS, you'll need a
 296 /Macro=("__AXP__=1")
 297
 298 The next big gotcha is directory depth. Perl can create directories four
 299 and five levels deep during the build, so you don't have to be too deep to
 300 start to hit the RMS 8 level point. It's best to do a
 301 $DEFINE/TRANS=(CONC,TERM) PERLSRC disk:[dir.dir.dir.perldir.]"  (note the
 302 trailing period) and $SET DEFAULT PERLSRC:[000000] before building. Perl
 303 modules can be just as bad (or worse), so watch out for them, too.
 304
 305 Finally, the third thing that bites people is leftover pieces from a failed
 306 build. If things go wrong, make sure you do a "(MMK|MMS|make) realclean"
 307 before you rebuild.
 308
 309 * Dec C issues
 310
 311 Note to DECC users: Some early versions (pre-5.2, some pre-4. If you're Dec
 312 C 5.x or higher, with current patches if anym you're fine) of the DECCRTL
 313 contained a few bugs which affect Perl performance:
 314     - Newlines are lost on I/O through pipes, causing lines to run together.
 315       This shows up as RMS RTB errors when reading from a pipe.  You can
 316       work around this by having one process write data to a file, and
 317       then having the other read the file, instead of the pipe.  This is
 318       fixed in version 4 of DECC.
 319     - The modf() routine returns a non-integral value for some values above
 320       INT_MAX; the Perl "int" operator will return a non-integral value in
 321       these cases.  This is fixed in version 4 of DECC.
 322     - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine
 323       changes the process default device and directory permanently, even
 324       though the call specified that the change should not persist after
 325       Perl exited.  This is fixed by DEC CSC patch AXPACRT04_061.
 326
 327 * Mailing Lists
 328
 329 There are several mailing lists available to the Perl porter. For VMS
 330 specific issues (including both Perl questions and installation problems)
 331 there is the VMSPERL mailing list. It's usually a low-volume (10-12
 332 messages a week) mailing list.
 333
 334 The subscription address is VMSPERL-REQUEST@NEWMAN.UPENN.EDU. Send a mail
 335 message with just the words SUBSCRIBE VMSPERL in the body of the message.
 336
 337 The VMSPERL mailing list address is VMSPERL@NEWMAN.UPENN.EDU. Any mail
 338 sent there gets echoed to all subscribers of the list.
 339
 340 The Perl5-Porters list is for anyone involved in porting Perl to a
 341 platform. This includes you, if you want to participate. It's a high-volume
 342 list (60-100 messages a day during active development times), so be sure
 343 you want to be there. The subscription address is
 344 Perl5-Porters-request@perl.org. Send a message with just the word SUBSCRIBE
 345 in the body. The posting address is Perl5-Porters@perl.org.
 346
 347 * Acknowledgements
 348
 349 A real big thanks needs to go to Charles Bailey
 350 <bailey@newman.upenn.edu>, who is ultimately responsible for Perl 5.004
 351 running on VMS. Without him, nothing the rest of us have done would be at
 352 all important.
 353
 354 There are, of course, far too many people involved in the porting and testing
 355 of Perl to mention everyone who deserves it, so please forgive us if we've
 356 missed someone.  That said, special thanks are due to the following:
 357   Tim Adye <T.J.Adye@rl.ac.uk>
 358      for the VMS emulations of getpw*()
 359   David Denholm <denholm@conmat.phys.soton.ac.uk>
 360      for extensive testing and provision of pipe and SocketShr code,
 361   Mark Pizzolato <mark@infocomm.com>
 362      for the getredirection() code
 363   Rich Salz <rsalz@bbn.com>
 364      for readdir() and related routines
 365   Peter Prymmer <pvhp@lns62.lns.cornell.edu)
 366      for extensive testing, as well as development work on
 367      configuration and documentation for VMS Perl,
 368   Dan Sugalski <sugalsd@stargate.lbcc.cc.or.us>
 369      for extensive contributions to recent version support,
 370      development of VMS-specific extensions, and dissemination
 371      of information about VMS Perl,
 372   the Stanford Synchrotron Radiation Laboratory and the
 373      Laboratory of Nuclear Studies at Cornell University for
 374      the the opportunity to test and develop for the AXP,
 375 and to the entire VMSperl group for useful advice and suggestions.  In
 376 addition the perl5-porters deserve credit for their creativity and
 377 willingness to work with the VMS newcomers.  Finally, the greatest debt of
 378 gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which
 379 have made our sleepless nights possible.
 380
 381 Thanks,
 382 The VMSperl group