| 1 | Last Revised 01-March-1999 by Dan Sugalski <sugalskd@ous.edu> |
| 2 | Originally by Charles Bailey <bailey@newman.upenn.edu> |
| 3 | |
| 4 | * Important safety tip |
| 5 | |
| 6 | The build and install procedures have changed significantly from the 5.004 |
| 7 | releases! Make sure you read the "Building Perl" and "Installing Perl" |
| 8 | sections before you build or install. |
| 9 | |
| 10 | Also note that, as of 5.005, an ANSI C compliant compiler is required to |
| 11 | build Perl. Vax C is *not* ANSI compliant, as it died a natural death some |
| 12 | time before the standard was set. Therefore Vax C will not compile perl |
| 13 | 5.005. Sorry about that. |
| 14 | |
| 15 | If you're stuck without Dec C (the Vax C license should be good for Dec C, |
| 16 | but the media charges might prohibit an upgrade), consider getting Gnu C |
| 17 | instead. |
| 18 | |
| 19 | * Intro |
| 20 | |
| 21 | The VMS port of Perl is as functionally complete as any other Perl port |
| 22 | (and as complete as the ports on some Unix systems). The Perl binaries |
| 23 | provide all the Perl system calls that are either available under VMS or |
| 24 | reasonably emulated. There are some incompatibilites in process handling |
| 25 | (e.g the fork/exec model for creating subprocesses doesn't do what you |
| 26 | might expect under Unix), mainly because VMS and Unix handle processes and |
| 27 | sub-processes very differently. |
| 28 | |
| 29 | There are still some unimplemented system functions, and of coursse we |
| 30 | could use modules implementing useful VMS system services, so if you'd like |
| 31 | to lend a hand we'd love to have you. Join the Perl Porting Team Now! |
| 32 | |
| 33 | The current sources and build procedures have been tested on a VAX using |
| 34 | Dec C, and on an AXP using Dec C. If you run into problems with |
| 35 | other compilers, please let us know. |
| 36 | |
| 37 | There are issues with varions versions of Dec C, so if you're not running a |
| 38 | relatively modern version, check the Dec C issues section later on in this |
| 39 | document. |
| 40 | |
| 41 | * Other required software |
| 42 | |
| 43 | In addition to VMS, you'll need: |
| 44 | 1) A C compiler. Dec C or gcc for AXP or the VAX. |
| 45 | 2) A make tool. Dec's MMS (v2.6 or later), or MadGoat's free MMS |
| 46 | analog MMK (available from ftp.madgoat.com/madgoat) both work |
| 47 | just fine. Gnu Make might work, but it's been so long since |
| 48 | anyone's tested it that we're not sure. MMK's free, though, so |
| 49 | go ahead and use that. |
| 50 | |
| 51 | You may also want to have on hand: |
| 52 | 1) UNZIP.EXE for VMS available from a number of web/ftp sites. |
| 53 | http://www.cdrom.com/pub/infozip/UnZip.html |
| 54 | http://www.openvms.digital.com/cd/INFO-ZIP/ |
| 55 | ftp://ftp.digital.com/pub/VMS/ |
| 56 | ftp://ftp.openvms.digital.com/ |
| 57 | ftp://ftp.madgoat.com/madgoat/ |
| 58 | ftp://ftp.wku.edu/vms/ |
| 59 | 2) GUNZIP/GZIP.EXE for VMS available from a number of web/ftp sites. |
| 60 | http://www.fsf.org/order/ftp.html |
| 61 | ftp://ftp.uu.net/archive/systems/gnu/diffutils*.tar.gz |
| 62 | ftp://gatekeeper.dec.com/pub/GNU/diffutils*.tar.gz |
| 63 | ftp://ftp.gnu.org/pub/gnu/diffutils*.tar.gz |
| 64 | http://www.openvms.digital.com/cd/GZIP/ |
| 65 | ftp://ftp.digital.com/pub/VMS/ |
| 66 | 3) VMS TAR also available from a number of web/ftp sites. |
| 67 | ftp://ftp.lp.se/vms/ |
| 68 | http://www.openvms.digital.com/cd/VMSTAR/ |
| 69 | ftp://ftp.digital.com/pub/VMS/ |
| 70 | Please note that UNZIP and GUNZIP are not the same thing (they work with |
| 71 | different formats). Most of the useful files from CPAN (the Comprehensive |
| 72 | Perl Archive Network) are in .tar.gz format (this includes copies of the |
| 73 | source code for perl as well as modules and scripts that you may wish to |
| 74 | add later) hence you probably want to have GUNZIP.EXE and VMSTAR.EXE on |
| 75 | your VMS machine. |
| 76 | |
| 77 | If you want to include socket support, you'll need a TCP stack and either |
| 78 | Dec C, or socket libraries. See the Socket Support topic for more details. |
| 79 | |
| 80 | * Building Perl |
| 81 | |
| 82 | Building perl has two steps, configuration and compilation. |
| 83 | |
| 84 | To configure perl (a necessary first step), issue the command |
| 85 | |
| 86 | @CONFIGURE |
| 87 | |
| 88 | from the top of an unpacked perl directory. You'll be asked a series of |
| 89 | questions, and the answers to them (along with the capabilities of your C |
| 90 | compiler and network stack) will determine how perl's built. |
| 91 | |
| 92 | If you've got multiple C compilers installed, you'll have your choice of |
| 93 | which one to use. Various older versions of Dec C had some gotchas, so if |
| 94 | you're using a version older than 5.2, check the Dec C Issues section. |
| 95 | |
| 96 | The configuration script will print out, at the very end, the MMS or MMK |
| 97 | command you need to compile perl. Issue it (exactly as printed) to start |
| 98 | the build. |
| 99 | |
| 100 | Once you issue your MMS command, sit back and wait. Perl should build and |
| 101 | link without a problem. If it doesn't, check the Gotchas to watch out for |
| 102 | section. If that doesn't help, send some mail to the VMSPERL mailing list. |
| 103 | Instructions are in the Mailing Lists section. |
| 104 | |
| 105 | As a handy shortcut, the command: |
| 106 | |
| 107 | @CONFIGURE "-des" |
| 108 | |
| 109 | (note the quotation marks and case) will choose reasonable defaults. (It |
| 110 | takes Dec C over Gnu C, Dec C sockets over SOCKETSHR sockets, and either |
| 111 | over no sockets) |
| 112 | |
| 113 | * Testing Perl |
| 114 | |
| 115 | Once Perl has built cleanly, you need to test it to make sure things work. |
| 116 | This step is very important--there are always things that can go wrong |
| 117 | somehow and get you a dysfunctional Perl. |
| 118 | |
| 119 | Testing is very easy, though, as there's a full test suite in the perl |
| 120 | distribution. To run the tests, enter the *exact* MMS line you used to |
| 121 | compile Perl and add the word "test" to the end, like this: |
| 122 | |
| 123 | Compile Command: |
| 124 | |
| 125 | $MMS |
| 126 | |
| 127 | Test Command: |
| 128 | |
| 129 | $MMS test |
| 130 | |
| 131 | MMS will run all the tests. This may take some time, as there are a lot of |
| 132 | tests. If any tests fail, there will be a note made on-screen. At the end |
| 133 | of all the tests, a summary of the tests, the number passed and failed, and |
| 134 | the time taken will be displayed. |
| 135 | |
| 136 | If any tests fail, it means something's wrong with Perl. If the test suite |
| 137 | hangs (some tests can take upwards of two or three minutes, or more if |
| 138 | you're on an especially slow machine, depending on your machine speed, so |
| 139 | don't be hasty), then the test *after* the last one displayed failed. Don't |
| 140 | install Perl unless you're confident that you're OK. Regardless of how |
| 141 | confident you are, make a bug report to the VMSPerl mailing list. |
| 142 | |
| 143 | If one or more tests fail, you can get more info on the failure by issuing |
| 144 | this command sequence: |
| 145 | |
| 146 | $ @[.VMS]TEST .typ "-v" [.subdir]test.T |
| 147 | |
| 148 | where ".typ" is the file type of the Perl images you just built (if you |
| 149 | didn't do anything special, use .EXE), and "[.subdir]test.T" is the test |
| 150 | that failed. For example, with a normal Perl build, if the test indicated |
| 151 | that [.op]time failed, then you'd do this: |
| 152 | |
| 153 | $ @[.VMS]TEST .EXE "-v" [.OP]TIME.T |
| 154 | |
| 155 | When you send in a bug report for failed tests, please include the output |
| 156 | from this command, which is run from the main source directory: |
| 157 | |
| 158 | MCR []MINIPERL "-V" |
| 159 | |
| 160 | Note that "-V" really is a capital V in double quotes. This will dump out a |
| 161 | couple of screens worth of config info, and can help us diagnose the problem. |
| 162 | If (and only if) that did not work then try enclosing the output of: |
| 163 | |
| 164 | @[.vms]myconfig |
| 165 | |
| 166 | * Cleaning up and starting fresh |
| 167 | |
| 168 | If you need to recompile from scratch, you have to make sure you clean up |
| 169 | first. There's a procedure to do it--enter the *exact* MMS line you used to |
| 170 | compile and add "realclean" at the end, like this: |
| 171 | |
| 172 | Compile Command: |
| 173 | |
| 174 | $MMS |
| 175 | |
| 176 | Cleanup Command: |
| 177 | |
| 178 | $MMS realclean |
| 179 | |
| 180 | If you don't do this, things may behave erratically. They might not, too, |
| 181 | so it's best to be sure and do it. |
| 182 | |
| 183 | * Installing Perl |
| 184 | |
| 185 | There are several steps you need to take to get Perl installed and |
| 186 | running. |
| 187 | |
| 188 | 1) Create a directory somewhere and define the concealed logical PERL_ROOT |
| 189 | to point to it. For example, DEFINE/TRANS=(CONC,TERM) PERL_ROOT dka200:[perl.] |
| 190 | |
| 191 | 2) Run the install script via: |
| 192 | |
| 193 | MMS install |
| 194 | |
| 195 | or |
| 196 | |
| 197 | MMK install |
| 198 | |
| 199 | If for some reason it complains about target INSTALL being up to date, |
| 200 | throw a /FORCE switch on the MMS or MMK command. |
| 201 | |
| 202 | The script [.VMS]PERL_SETUP.COM that is written by CONFIGURE.COM |
| 203 | will take care of most of the following: |
| 204 | |
| 205 | 3) Either define the symbol PERL somewhere, such as |
| 206 | SYS$MANAGER:SYLOGIN.COM, to be "PERL :== $PERL_ROOT:[000000]PERL.EXE", or |
| 207 | install Perl into DCLTABLES.EXE (Check out the section "Installing Perl |
| 208 | into DCLTABLES" for more info), or put the image in a directory that's in |
| 209 | your DCL$PATH (if you're using VMS 6.2 or higher). |
| 210 | |
| 211 | 4) Either define the logical name PERLSHR somewhere |
| 212 | (such as in PERL_SETUP.COM) like so: |
| 213 | DEFINE/NOLOG PERLSHR PERL_ROOT:[000000]PERLSHR.EXE |
| 214 | or copy perl_root:[000000]perlshr.exe sys$share:. |
| 215 | |
| 216 | 5) Optionally define the command PERLDOC as |
| 217 | PERLDOC == "$PERL_ROOT:[000000]PERL PERL_ROOT:[LIB.POD]PERLDOC.COM -t" |
| 218 | Note that if you wish to use most as a pager please see |
| 219 | ftp://space.mit.edu/pub/davis/ for both most and slang (or perhaps |
| 220 | ftp://ftp.wku.edu/vms/narnia/most.zip ). |
| 221 | |
| 222 | 6) Optionally define the command PERLBUG (the Perl bug report generator) as |
| 223 | PERLBUG == "$PERL_ROOT:[000000]PERL PERL_ROOT:[LIB]PERLBUG.COM" |
| 224 | |
| 225 | 7) Optionally define the command POD2MAN (Converts POD files to nroff |
| 226 | source suitable for converting to man pages. Also quiets complaints during |
| 227 | module builds) as |
| 228 | |
| 229 | DEFINE/NOLOG POD2MAN PERL_ROOT:[LIB.POD]POD2MAN.COM |
| 230 | POD2MAN == "$PERL_ROOT:[000000]PERL POD2MAN" |
| 231 | |
| 232 | 8) Optionally define the command POD2TEXT (Converts POD files to text, |
| 233 | which is required for perldoc -f to work properly) as |
| 234 | |
| 235 | DEFINE/NOLOG POD2TEXT PERL_ROOT:[LIB.POD]POD2TEXT.COM |
| 236 | POD2TEXT == "$PERL_ROOT:[000000]PERL POD2TEXT" |
| 237 | |
| 238 | In all these cases, if you've got PERL defined as a foreign command, you |
| 239 | can replace $PERL_ROOT:[000000]PERL with ''perl'. If you've installed perl |
| 240 | into DCLTABLES, replace it with just perl. |
| 241 | |
| 242 | * Installing Perl into DCLTABLES |
| 243 | |
| 244 | Execute the following command file to define PERL as a DCL command. |
| 245 | You'll need CMKRNL priv to install the new dcltables.exe. |
| 246 | |
| 247 | $ create perl.cld |
| 248 | ! |
| 249 | ! modify to reflect location of your perl.exe |
| 250 | ! |
| 251 | define verb perl |
| 252 | image perl_root:[000000]perl.exe |
| 253 | cliflags (foreign) |
| 254 | $! |
| 255 | $ set command perl /table=sys$common:[syslib]dcltables.exe - |
| 256 | /output=sys$common:[syslib]dcltables.exe |
| 257 | $ install replace sys$common:[syslib]dcltables.exe |
| 258 | $ exit |
| 259 | |
| 260 | * Changing compile-time things |
| 261 | |
| 262 | Most of the user-definable features of Perl are enabled or disabled in |
| 263 | [.VMS]CONFIG.VMS. There's code in there to Do The Right Thing, but that may |
| 264 | end up being the wrong thing for you. Make sure you understand what you're |
| 265 | doing, since changes here can get you a busted perl. |
| 266 | |
| 267 | Odds are that there's nothing here to change, unless you're on a version of |
| 268 | VMS later than 6.2 and Dec C later than 5.6. Even if you are, the correct |
| 269 | values will still be chosen, most likely. Poking around here should be |
| 270 | unnecessary. |
| 271 | |
| 272 | The one exception is the various *DIR install locations. Changing those |
| 273 | requires changes in genconfig.pl as well. Be really careful if you need to |
| 274 | change these, as they can cause some fairly subtle problems. |
| 275 | |
| 276 | * INSTALLing images |
| 277 | |
| 278 | On systems that are using perl quite a bit, and particularly those with |
| 279 | minimal RAM, you can boost the performance of perl by INSTALLing it as |
| 280 | a known image. PERLSHR.EXE is typically larger than 1500 blocks |
| 281 | and that is a reasonably large amount of IO to load each time perl is |
| 282 | invoked. |
| 283 | |
| 284 | INSTALL ADD PERLSHR/SHARE |
| 285 | |
| 286 | should be enough for PERLSHR.EXE (/share implies /header and /open), |
| 287 | while /HEADER should do for PERL.EXE (perl.exe is not a shared image). |
| 288 | |
| 289 | If your code 'use's modules, check to see if there's an executable for |
| 290 | them, too. In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File, |
| 291 | DCLsym, and Stdio all have shared images that can be installed /SHARE. |
| 292 | |
| 293 | How much of a win depends on your memory situation, but if you're firing |
| 294 | off perl with any regularity (like more than once every 20 seconds or so) |
| 295 | it's probably a win. |
| 296 | |
| 297 | While there is code in perl to remove privileges as it runs you are advised |
| 298 | to NOT INSTALL PERL.EXE with PRIVs! |
| 299 | |
| 300 | * Extra things in the Perl distribution |
| 301 | |
| 302 | In addition to the standard stuff that gets installed, there are two |
| 303 | optional extensions, DCLSYM and STDIO, that are handy. Instructions for |
| 304 | these two modules are in [.VMS.EXT.DCLSYM] and [.VMS.EXT.STDIO], |
| 305 | respectively. They are built automatically for versions of perl >= 5.005. |
| 306 | |
| 307 | * Socket Support |
| 308 | |
| 309 | Perl includes a number of functions for IP sockets, which are available if |
| 310 | you choose to compile Perl with socket support (see the section Compiling |
| 311 | Perl for more info on selecting a socket stack). Since IP networking is an |
| 312 | optional addition to VMS, there are several different IP stacks |
| 313 | available. How well integrated they are into the system depends on the |
| 314 | stack, your version of VMS, and the version of your C compiler. |
| 315 | |
| 316 | The most portable solution uses the SOCKETSHR library. In combination with |
| 317 | either UCX or NetLib, this supports all the major TCP stacks (Multinet, |
| 318 | Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with |
| 319 | all the compilers on both VAX and Alpha. The socket interface is also |
| 320 | consistent across versions of VMS and C compilers. It has a problem with |
| 321 | UDP sockets when used with Multinet, though, so you should be aware of |
| 322 | that. |
| 323 | |
| 324 | The other solution available is to use the socket routines built into Dec |
| 325 | C. Which routines are available depend on the version of VMS you're |
| 326 | running, and require proper UCX emulation by your TCP/IP vendor. |
| 327 | Relatively current versions of Multinet, TCPWare, Pathway, and UCX all |
| 328 | provide the required libraries--check your manuals or release notes to see |
| 329 | if your version is new enough. |
| 330 | |
| 331 | * Reporting Bugs |
| 332 | |
| 333 | If you come across what you think might be a bug in Perl, please report |
| 334 | it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through |
| 335 | the process of creating a bug report. This script includes details of your |
| 336 | installation, and is very handy. Completed bug reports should go to |
| 337 | perlbug@perl.com. |
| 338 | |
| 339 | * Gotchas to watch out for |
| 340 | |
| 341 | Probably the single biggest gotcha in compiling Perl is giving the wrong |
| 342 | switches to MMS/MMK when you build. Use *exactly* what the configure script |
| 343 | prints! |
| 344 | |
| 345 | The next big gotcha is directory depth. Perl can create directories four |
| 346 | and five levels deep during the build, so you don't have to be too deep to |
| 347 | start to hit the RMS 8 level point. It's best to do a |
| 348 | $DEFINE/TRANS=(CONC,TERM) PERLSRC disk:[dir.dir.dir.perldir.]" (note the |
| 349 | trailing period) and $SET DEFAULT PERLSRC:[000000] before building. Perl |
| 350 | modules can be just as bad (or worse), so watch out for them, too. The |
| 351 | configuration script will warn if it thinks you're too deep (at least on |
| 352 | versions of VMS prior to 7.2). |
| 353 | |
| 354 | Finally, the third thing that bites people is leftover pieces from a failed |
| 355 | build. If things go wrong, make sure you do a "(MMK|MMS|make) realclean" |
| 356 | before you rebuild. |
| 357 | |
| 358 | * Dec C issues |
| 359 | |
| 360 | Note to DECC users: Some early versions (pre-5.2, some pre-4. If you're Dec |
| 361 | C 5.x or higher, with current patches if anym you're fine) of the DECCRTL |
| 362 | contained a few bugs which affect Perl performance: |
| 363 | - Newlines are lost on I/O through pipes, causing lines to run together. |
| 364 | This shows up as RMS RTB errors when reading from a pipe. You can |
| 365 | work around this by having one process write data to a file, and |
| 366 | then having the other read the file, instead of the pipe. This is |
| 367 | fixed in version 4 of DECC. |
| 368 | - The modf() routine returns a non-integral value for some values above |
| 369 | INT_MAX; the Perl "int" operator will return a non-integral value in |
| 370 | these cases. This is fixed in version 4 of DECC. |
| 371 | - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine |
| 372 | changes the process default device and directory permanently, even |
| 373 | though the call specified that the change should not persist after |
| 374 | Perl exited. This is fixed by DEC CSC patch AXPACRT04_061. |
| 375 | |
| 376 | * Mailing Lists |
| 377 | |
| 378 | There are several mailing lists available to the Perl porter. For VMS |
| 379 | specific issues (including both Perl questions and installation problems) |
| 380 | there is the VMSPERL mailing list. It's usually a low-volume (10-12 |
| 381 | messages a week) mailing list. |
| 382 | |
| 383 | The subscription address is VMSPERL-REQUEST@NEWMAN.UPENN.EDU. Send a mail |
| 384 | message with just the words SUBSCRIBE VMSPERL in the body of the message. |
| 385 | |
| 386 | The VMSPERL mailing list address is VMSPERL@NEWMAN.UPENN.EDU. Any mail |
| 387 | sent there gets echoed to all subscribers of the list. |
| 388 | |
| 389 | To unsubscribe from VMSPERL send the message UNSUBSCRIBE VMSPERL to |
| 390 | VMSPERL-REQUEST@NEWMAN.UPENN.EDU. Be sure to do so from the subscribed |
| 391 | account that you are cancelling. |
| 392 | |
| 393 | |
| 394 | * Acknowledgements |
| 395 | |
| 396 | A real big thanks needs to go to Charles Bailey |
| 397 | <bailey@newman.upenn.edu>, who is ultimately responsible for Perl 5.004 |
| 398 | running on VMS. Without him, nothing the rest of us have done would be at |
| 399 | all important. |
| 400 | |
| 401 | There are, of course, far too many people involved in the porting and testing |
| 402 | of Perl to mention everyone who deserves it, so please forgive us if we've |
| 403 | missed someone. That said, special thanks are due to the following: |
| 404 | Tim Adye <T.J.Adye@rl.ac.uk> |
| 405 | for the VMS emulations of getpw*() |
| 406 | David Denholm <denholm@conmat.phys.soton.ac.uk> |
| 407 | for extensive testing and provision of pipe and SocketShr code, |
| 408 | Mark Pizzolato <mark@infocomm.com> |
| 409 | for the getredirection() code |
| 410 | Rich Salz <rsalz@bbn.com> |
| 411 | for readdir() and related routines |
| 412 | Peter Prymmer <pvhp@forte.com> or <pvhp@lns62.lns.cornell.edu> |
| 413 | for extensive testing, as well as development work on |
| 414 | configuration and documentation for VMS Perl, |
| 415 | Dan Sugalski <sugalskd@ous.edu> |
| 416 | for extensive contributions to recent version support, |
| 417 | development of VMS-specific extensions, and dissemination |
| 418 | of information about VMS Perl, |
| 419 | the Stanford Synchrotron Radiation Laboratory and the |
| 420 | Laboratory of Nuclear Studies at Cornell University for |
| 421 | the opportunity to test and develop for the AXP, |
| 422 | and to the entire VMSperl group for useful advice and suggestions. In |
| 423 | addition the perl5-porters deserve credit for their creativity and |
| 424 | willingness to work with the VMS newcomers. Finally, the greatest debt of |
| 425 | gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which |
| 426 | have made our sleepless nights possible. |
| 427 | |
| 428 | Thanks, |
| 429 | The VMSperl group |