| 1 | If you read this file _as_is_, just ignore the equal signs on the left. |
| 2 | This file is written in the POD format (see [.POD]PERLPOD.POD;1) which is |
| 3 | specially designed to be readable as is. |
| 4 | |
| 5 | =head1 NAME |
| 6 | |
| 7 | README.vms - Configuring, building, testing, and installing perl on VMS |
| 8 | |
| 9 | =head1 SYNOPSIS |
| 10 | |
| 11 | To configure, build, test, and install perl on VMS: |
| 12 | |
| 13 | @ Configure |
| 14 | mms |
| 15 | mms test |
| 16 | mms install |
| 17 | |
| 18 | mmk may be used in place of mms in the last three steps. |
| 19 | |
| 20 | =head1 DESCRIPTION |
| 21 | |
| 22 | =head2 Important safety tip |
| 23 | |
| 24 | The build and install procedures have changed significantly from the 5.004 |
| 25 | releases! Make sure you read the "Configuring the Perl Build", "Building |
| 26 | Perl", and "Installing Perl" sections of this document before you build or |
| 27 | install. Also please note other changes in the current release by having |
| 28 | a look at L<perldelta/VMS>. |
| 29 | |
| 30 | Also note that, as of Perl version 5.005 and later, an ANSI C compliant |
| 31 | compiler is required to build Perl. VAX C is *not* ANSI compliant, as it |
| 32 | died a natural death some time before the standard was set. Therefore |
| 33 | VAX C will not compile Perl 5.005 or later. We are sorry about that. |
| 34 | |
| 35 | If you are stuck without Compaq (formerly DEC) C consider trying Gnu C |
| 36 | instead, though there have been no recent reports of builds using Gnu C. |
| 37 | There is minimal support for Compaq C++ but this support is not complete; |
| 38 | if you get it working please write to the vmsperl list (for info see |
| 39 | L</"Mailing Lists">). |
| 40 | |
| 41 | |
| 42 | =head2 Introduction to Perl on VMS |
| 43 | |
| 44 | The VMS port of Perl is as functionally complete as any other Perl port |
| 45 | (and as complete as the ports on some Unix systems). The Perl binaries |
| 46 | provide all the Perl system calls that are either available under VMS or |
| 47 | reasonably emulated. There are some incompatibilities in process handling |
| 48 | (e.g. the fork/exec model for creating subprocesses doesn't do what you |
| 49 | might expect under Unix), mainly because VMS and Unix handle processes and |
| 50 | sub-processes very differently. |
| 51 | |
| 52 | There are still some unimplemented system functions, and of course we |
| 53 | could use modules implementing useful VMS system services, so if you'd like |
| 54 | to lend a hand we'd love to have you. Join the Perl Porting Team Now! |
| 55 | |
| 56 | The current sources and build procedures have been tested on a VAX using |
| 57 | DEC C, and on an AXP using DEC C. If you run into problems with |
| 58 | other compilers, please let us know. (Note: DEC C was renamed to Compaq C |
| 59 | around version 6.2). |
| 60 | |
| 61 | There are issues with various versions of DEC C, so if you're not running a |
| 62 | relatively modern version, check the "DEC C issues" section later on in this |
| 63 | document. |
| 64 | |
| 65 | =head2 Other required software for Compiling Perl on VMS |
| 66 | |
| 67 | In addition to VMS and DCL you will need two things: |
| 68 | |
| 69 | =over 4 |
| 70 | |
| 71 | =item 1 A C compiler. |
| 72 | |
| 73 | DEC (now Compaq) C or gcc for VMS (AXP or VAX). |
| 74 | |
| 75 | =item 2 A make tool. |
| 76 | |
| 77 | DEC's MMS (v2.6 or later), or MadGoat's free MMS |
| 78 | analog MMK (available from ftp.madgoat.com/madgoat) both work |
| 79 | just fine. Gnu Make might work, but it's been so long since |
| 80 | anyone's tested it that we're not sure. MMK is free though, so |
| 81 | go ahead and use that. |
| 82 | |
| 83 | =back |
| 84 | |
| 85 | =head2 Additional software that is optional for Perl on VMS |
| 86 | |
| 87 | You may also want to have on hand: |
| 88 | |
| 89 | =over 4 |
| 90 | |
| 91 | =item 1 GUNZIP/GZIP.EXE for VMS |
| 92 | |
| 93 | A de-compressor for *.gz and *.tgz files available from a number |
| 94 | of web/ftp sites and is distributed on the OpenVMS Freeware CD-ROM |
| 95 | from Compaq. |
| 96 | |
| 97 | http://www.fsf.org/order/ftp.html |
| 98 | http://www.openvms.compaq.com/freeware/ |
| 99 | http://www.crinoid.com/utils/ |
| 100 | |
| 101 | =item 2 VMS TAR |
| 102 | |
| 103 | For reading and writing unix tape archives (*.tar files). Vmstar is also |
| 104 | available from a number of web/ftp sites and is distributed on the OpenVMS |
| 105 | Freeware CD-ROM from Compaq. |
| 106 | |
| 107 | ftp://ftp.lp.se/vms/ |
| 108 | http://www.openvms.compaq.com/freeware/ |
| 109 | |
| 110 | Recent versions of VMS tar on ODS-5 volumes may extract tape archive |
| 111 | files with ^. escaped periods in them. See below for further workarounds. |
| 112 | |
| 113 | =item 3 UNZIP.EXE for VMS |
| 114 | |
| 115 | A combination decompressor and archive reader/writer for *.zip files. |
| 116 | Unzip is available from a number of web/ftp sites. |
| 117 | |
| 118 | http://www.info-zip.org/UnZip.html |
| 119 | http://www.openvms.compaq.com/freeware/ |
| 120 | ftp://ftp.openvms.compaq.com/ |
| 121 | ftp://ftp.madgoat.com/madgoat/ |
| 122 | ftp://ftp.process.com/vms-freeware/ |
| 123 | |
| 124 | =item 4 MOST |
| 125 | |
| 126 | Most is an optional pager that is convenient to use with perldoc (unlike |
| 127 | TYPE/PAGE, MOST can go forward and backwards in a document and supports |
| 128 | regular expression searching). Most builds with the slang |
| 129 | library on VMS. Most and slang are available from: |
| 130 | |
| 131 | ftp://space.mit.edu/pub/davis/ |
| 132 | ftp://ftp.process.com/vms-freeware/narnia/ |
| 133 | |
| 134 | =item 5 GNU PATCH and DIFFUTILS for VMS |
| 135 | |
| 136 | Patches to Perl are usually distributed as GNU unified or contextual diffs. |
| 137 | Such patches are created by the GNU diff program (part of the diffutils |
| 138 | distribution) and applied with GNU patch. VMS ports of these utilities are |
| 139 | available here: |
| 140 | |
| 141 | http://www.crinoid.com/utils/ |
| 142 | http://www.openvms.compaq.com/freeware/ |
| 143 | |
| 144 | =back |
| 145 | |
| 146 | Please note that UNZIP and GUNZIP are not the same thing (they work with |
| 147 | different formats). Many of the useful files from CPAN (the Comprehensive |
| 148 | Perl Archive Network) are in *.tar.gz or *.tgz format (this includes copies |
| 149 | of the source code for perl as well as modules and scripts that you may |
| 150 | wish to add later) hence you probably want to have GUNZIP.EXE and |
| 151 | VMSTAR.EXE on your VMS machine. |
| 152 | |
| 153 | If you want to include socket support, you'll need a TCP/IP stack and either |
| 154 | DEC C, or socket libraries. See the "Socket Support (optional)" topic |
| 155 | for more details. |
| 156 | |
| 157 | =head1 Unpacking the Perl source code |
| 158 | |
| 159 | You may need to set up a foreign symbol for the unpacking utility of choice. |
| 160 | |
| 161 | If you unpack a perl source kit with a name containing multiple periods on |
| 162 | an ODS-5 volume using recent versions of vmstar (e.g. V3.4 or later) you may |
| 163 | need to be especially careful in unpacking the tape archive file. Try to use |
| 164 | the ODS-2 compatability qualifiers such as: |
| 165 | |
| 166 | vmstar /extract/verbose/ods2 perl-V^.VIII^.III.tar |
| 167 | |
| 168 | or: |
| 169 | |
| 170 | vmstar -xvof perl-5^.8^.3.tar |
| 171 | |
| 172 | If you neglected to use the /ODS2 qualifier or the -o switch then you |
| 173 | could rename the source directory: |
| 174 | |
| 175 | set security/protection=(o:rwed) perl-5^.8^.3.dir |
| 176 | rename perl-5^.8^.3.dir perl-5_8_3.dir |
| 177 | |
| 178 | Perl on VMS as of 5.8.3 does not completely handle extended file |
| 179 | parse styles such as are encountered on ODS-5. While it can be built, |
| 180 | installed, and run on ODS-5 filesystems; it may encounter |
| 181 | trouble with characters that are otherwise illegal on ODS-2 |
| 182 | volumes (notably the ^. escaped period sequence). |
| 183 | |
| 184 | =head1 Configuring the Perl build |
| 185 | |
| 186 | To configure perl (a necessary first step), issue the command |
| 187 | |
| 188 | @ Configure |
| 189 | |
| 190 | from the top of an unpacked perl source directory. You will be asked a |
| 191 | series of questions, and the answers to them (along with the capabilities |
| 192 | of your C compiler and network stack) will determine how perl is custom |
| 193 | built for your machine. |
| 194 | |
| 195 | If you have multiple C compilers installed, you'll have your choice of |
| 196 | which one to use. Various older versions of DEC C had some caveats, so if |
| 197 | you're using a version older than 5.2, check the "DEC C Issues" section. |
| 198 | |
| 199 | If you have any symbols or logical names in your environment that may |
| 200 | interfere with the build or regression testing of perl then configure.com |
| 201 | will try to warn you about them. If a logical name is causing |
| 202 | you trouble but is in an LNM table that you do not have write access to |
| 203 | then try defining your own to a harmless equivalence string in a table |
| 204 | such that it is resolved before the other (e.g. if TMP is defined in the |
| 205 | SYSTEM table then try DEFINE TMP "NL:" or somesuch in your process table) |
| 206 | otherwise simply deassign the dangerous logical names. The potentially |
| 207 | troublesome logicals and symbols are: |
| 208 | |
| 209 | COMP "LOGICAL" |
| 210 | EXT "LOGICAL" |
| 211 | FOO "LOGICAL" |
| 212 | LIB "LOGICAL" |
| 213 | LIST "LOGICAL" |
| 214 | MIME "LOGICAL" |
| 215 | POSIX "LOGICAL" |
| 216 | SYS "LOGICAL" |
| 217 | T "LOGICAL" |
| 218 | THREAD "LOGICAL" |
| 219 | THREADS "LOGICAL" |
| 220 | TIME "LOGICAL" |
| 221 | TMP "LOGICAL" |
| 222 | UNICODE "LOGICAL" |
| 223 | UTIL "LOGICAL" |
| 224 | TEST "SYMBOL" |
| 225 | |
| 226 | As a handy shortcut, the command: |
| 227 | |
| 228 | @ Configure "-des" |
| 229 | |
| 230 | (note the quotation marks and case) will choose reasonable defaults |
| 231 | automatically (it takes DEC C over Gnu C, DEC C sockets over SOCKETSHR |
| 232 | sockets, and either over no sockets). Some options can be given |
| 233 | explicitly on the command line; the following example specifies a |
| 234 | non-default location for where Perl will be installed: |
| 235 | |
| 236 | @ Configure "-d" "-Dprefix=dka100:[utils.perl5.]" |
| 237 | |
| 238 | Note that the installation location would be by default where you unpacked |
| 239 | the source with a "_ROOT." appended. For example if you unpacked the perl |
| 240 | source into: |
| 241 | |
| 242 | DKA200:[PERL-5_10_2...] |
| 243 | |
| 244 | Then the PERL_SETUP.COM that gets written out by CONFIGURE.COM will |
| 245 | try to DEFINE your installation PERL_ROOT to be: |
| 246 | |
| 247 | DKA200:[PERL-5_10_2_ROOT.] |
| 248 | |
| 249 | More help with configure.com is available from: |
| 250 | |
| 251 | @ Configure "-h" |
| 252 | |
| 253 | See the "Changing compile-time options (optional)" section below to learn |
| 254 | even more details about how to influence the outcome of the important |
| 255 | configuration step. If you find yourself reconfiguring and rebuilding |
| 256 | then be sure to also follow the advice in the "Cleaning up and starting |
| 257 | fresh (optional)" and the checklist of items in the "CAVEATS" sections |
| 258 | below. |
| 259 | |
| 260 | =head2 Changing compile-time options (optional) for Perl on VMS |
| 261 | |
| 262 | Most of the user definable features of Perl are enabled or disabled in |
| 263 | configure.com, which processes the hints file config_h.SH. There is |
| 264 | code in there to Do The Right Thing, but that may end up being the |
| 265 | wrong thing for you. Make sure you understand what you are doing since |
| 266 | inappropriate changes to configure.com or config_h.SH can render perl |
| 267 | unbuildable; odds are that there's nothing in there you'll need to |
| 268 | change. |
| 269 | |
| 270 | The one exception is the various *DIR install locations. Changing those |
| 271 | requires changes in genconfig.pl as well. Be really careful if you need to |
| 272 | change these, as they can cause some fairly subtle problems. |
| 273 | |
| 274 | =head2 Socket Support (optional) for Perl on VMS |
| 275 | |
| 276 | Perl includes a number of functions for IP sockets, which are available if |
| 277 | you choose to compile Perl with socket support. Since IP networking is an |
| 278 | optional addition to VMS, there are several different IP stacks available. |
| 279 | How well integrated they are into the system depends on the stack, your |
| 280 | version of VMS, and the version of your C compiler. |
| 281 | |
| 282 | The most portable solution uses the SOCKETSHR library. In combination with |
| 283 | either UCX or NetLib, this supports all the major TCP stacks (Multinet, |
| 284 | Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with |
| 285 | all the compilers on both VAX and Alpha. The socket interface is also |
| 286 | consistent across versions of VMS and C compilers. It has a problem with |
| 287 | UDP sockets when used with Multinet, though, so you should be aware of |
| 288 | that. |
| 289 | |
| 290 | The other solution available is to use the socket routines built into DEC |
| 291 | C. Which routines are available depend on the version of VMS you're |
| 292 | running, and require proper UCX emulation by your TCP/IP vendor. |
| 293 | Relatively current versions of Multinet, TCPWare, Pathway, and UCX all |
| 294 | provide the required libraries--check your manuals or release notes to see |
| 295 | if your version is new enough. |
| 296 | |
| 297 | =head1 Building Perl |
| 298 | |
| 299 | The configuration script will print out, at the very end, the MMS or MMK |
| 300 | command you need to compile perl. Issue it (exactly as printed) to start |
| 301 | the build. |
| 302 | |
| 303 | Once you issue your MMS or MMK command, sit back and wait. Perl should |
| 304 | compile and link without a problem. If a problem does occur check the |
| 305 | "CAVEATS" section of this document. If that does not help send some |
| 306 | mail to the VMSPERL mailing list. Instructions are in the "Mailing Lists" |
| 307 | section of this document. |
| 308 | |
| 309 | =head1 Testing Perl |
| 310 | |
| 311 | Once Perl has built cleanly you need to test it to make sure things work. |
| 312 | This step is very important since there are always things that can go wrong |
| 313 | somehow and yield a dysfunctional Perl for you. |
| 314 | |
| 315 | Testing is very easy, though, as there's a full test suite in the perl |
| 316 | distribution. To run the tests, enter the *exact* MMS line you used to |
| 317 | compile Perl and add the word "test" to the end, like this: |
| 318 | |
| 319 | If the compile command was: |
| 320 | |
| 321 | MMS |
| 322 | |
| 323 | then the test command ought to be: |
| 324 | |
| 325 | MMS test |
| 326 | |
| 327 | MMS (or MMK) will run all the tests. This may take some time, as there are |
| 328 | a lot of tests. If any tests fail, there will be a note made on-screen. |
| 329 | At the end of all the tests, a summary of the tests, the number passed and |
| 330 | failed, and the time taken will be displayed. |
| 331 | |
| 332 | The test driver invoked via MMS TEST has a DCL wrapper ([.VMS]TEST.COM) that |
| 333 | downgrades privileges to NETMBX, TMPMBX for the duration of the test run, |
| 334 | and then restores them to their prior state upon completion of testing. |
| 335 | This is done to ensure that the tests run in a private sandbox and can do no |
| 336 | harm to your system even in the unlikely event something goes badly wrong in |
| 337 | one of the test scripts while running the tests from a privileged account. |
| 338 | A side effect of this safety precaution is that the account used to run the |
| 339 | test suite must be the owner of the directory tree in which Perl has been |
| 340 | built; otherwise the manipulations of temporary files and directories |
| 341 | attempted by some of the tests will fail. |
| 342 | |
| 343 | If any tests fail, it means something is wrong with Perl. If the test suite |
| 344 | hangs (some tests can take upwards of two or three minutes, or more if |
| 345 | you're on an especially slow machine, depending on your machine speed, so |
| 346 | don't be hasty), then the test *after* the last one displayed failed. Don't |
| 347 | install Perl unless you're confident that you're OK. Regardless of how |
| 348 | confident you are, make a bug report to the VMSPerl mailing list. |
| 349 | |
| 350 | If one or more tests fail, you can get more information on the failure by |
| 351 | issuing this command sequence: |
| 352 | |
| 353 | @ [.VMS]TEST .typ "" "-v" [.subdir]test.T |
| 354 | |
| 355 | where ".typ" is the file type of the Perl images you just built (if you |
| 356 | didn't do anything special, use .EXE), and "[.subdir]test.T" is the test |
| 357 | that failed. For example, with a normal Perl build, if the test indicated |
| 358 | that t/op/time failed, then you'd do this: |
| 359 | |
| 360 | @ [.VMS]TEST .EXE "" "-v" [.OP]TIME.T |
| 361 | |
| 362 | Note that test names are reported in UNIX syntax and relative to the |
| 363 | top-level build directory. When supplying them individually to the test |
| 364 | driver, you can use either UNIX or VMS syntax, but you must give the path |
| 365 | relative to the [.T] directory and you must also add the .T extension to the |
| 366 | filename. So, for example if the test lib/Math/Trig fails, you would run: |
| 367 | |
| 368 | @ [.VMS]TEST .EXE "" -"v" [-.lib.math]trig.t |
| 369 | |
| 370 | When you send in a bug report for failed tests, please include the output |
| 371 | from this command, which is run from the main source directory: |
| 372 | |
| 373 | MCR []MINIPERL "-V" |
| 374 | |
| 375 | Note that -"V" really is a capital V in double quotes. This will dump out a |
| 376 | couple of screens worth of configuration information, and can help us |
| 377 | diagnose the problem. If (and only if) that did not work then try enclosing |
| 378 | the output of: |
| 379 | |
| 380 | MMS printconfig |
| 381 | |
| 382 | If (and only if) that did not work then try enclosing the output of: |
| 383 | |
| 384 | @ [.vms]myconfig |
| 385 | |
| 386 | You may also be asked to provide your C compiler version ("CC/VERSION NL:" |
| 387 | with DEC C, "gcc --version" with GNU CC). To obtain the version of MMS or |
| 388 | MMK you are running try "MMS/ident" or "MMK /ident". The GNU make version |
| 389 | can be identified with "make --version". |
| 390 | |
| 391 | =head2 Cleaning up and starting fresh (optional) installing Perl on VMS |
| 392 | |
| 393 | If you need to recompile from scratch, you have to make sure you clean up |
| 394 | first. There is a procedure to do it--enter the *exact* MMS line you used |
| 395 | to compile and add "realclean" at the end, like this: |
| 396 | |
| 397 | if the compile command was: |
| 398 | |
| 399 | MMS |
| 400 | |
| 401 | then the cleanup command ought to be: |
| 402 | |
| 403 | MMS realclean |
| 404 | |
| 405 | If you do not do this things may behave erratically during the subsequent |
| 406 | rebuild attempt. They might not, too, so it is best to be sure and do it. |
| 407 | |
| 408 | =head1 Installing Perl |
| 409 | |
| 410 | There are several steps you need to take to get Perl installed and |
| 411 | running. |
| 412 | |
| 413 | =over 4 |
| 414 | |
| 415 | =item 1 |
| 416 | |
| 417 | Check your default file protections with |
| 418 | |
| 419 | SHOW PROTECTION /DEFAULT |
| 420 | |
| 421 | and adjust if necessary with SET PROTECTION=(code)/DEFAULT. |
| 422 | |
| 423 | =item 2 |
| 424 | |
| 425 | Decide where you want Perl to be installed (unless you have already done so |
| 426 | by using the "prefix" configuration parameter -- see the example in the |
| 427 | "Configuring the Perl build" section). |
| 428 | |
| 429 | The DCL script PERL_SETUP.COM that is written by CONFIGURE.COM will help you |
| 430 | with the definition of the PERL_ROOT and PERLSHR logical names and the PERL |
| 431 | foreign command symbol. Take a look at PERL_SETUP.COM and modify it if you |
| 432 | want to. The installation process will execute PERL_SETUP.COM and copy |
| 433 | files to the directory tree pointed to by the PERL_ROOT logical name defined |
| 434 | there, so make sure that you have write access to the parent directory of |
| 435 | what will become the root of your Perl installation. |
| 436 | |
| 437 | =item 3 |
| 438 | |
| 439 | Run the install script via: |
| 440 | |
| 441 | MMS install |
| 442 | |
| 443 | or |
| 444 | |
| 445 | MMK install |
| 446 | |
| 447 | If for some reason it complains about target INSTALL being up to date, |
| 448 | throw a /FORCE switch on the MMS or MMK command. |
| 449 | |
| 450 | =back |
| 451 | |
| 452 | Copy PERL_SETUP.COM to a place accessible to your perl users. |
| 453 | |
| 454 | For example: |
| 455 | |
| 456 | COPY PERL_SETUP.COM SYS$LIBRARY: |
| 457 | |
| 458 | If you want to have everyone on the system have access to perl |
| 459 | then add a line that reads |
| 460 | |
| 461 | $ @sys$library:perl_setup |
| 462 | |
| 463 | to SYS$MANAGER:SYLOGIN.COM. |
| 464 | |
| 465 | Two alternatives to the foreign symbol would be to install PERL into |
| 466 | DCLTABLES.EXE (Check out the section "Installing Perl into DCLTABLES |
| 467 | (optional)" for more information), or put the image in a |
| 468 | directory that's in your DCL$PATH (if you're using VMS V6.2 or higher). |
| 469 | |
| 470 | An alternative to having PERL_SETUP.COM define the PERLSHR logical name |
| 471 | is to simply copy it into the system shareable library directory with: |
| 472 | |
| 473 | copy perl_root:[000000]perlshr.exe sys$share: |
| 474 | |
| 475 | See also the "INSTALLing images (optional)" section. |
| 476 | |
| 477 | =head2 Installing Perl into DCLTABLES (optional) on VMS |
| 478 | |
| 479 | Execute the following command file to define PERL as a DCL command. |
| 480 | You'll need CMKRNL privilege to install the new dcltables.exe. |
| 481 | |
| 482 | $ create perl.cld |
| 483 | ! |
| 484 | ! modify to reflect location of your perl.exe |
| 485 | ! |
| 486 | define verb perl |
| 487 | image perl_root:[000000]perl.exe |
| 488 | cliflags (foreign) |
| 489 | $! |
| 490 | $ set command perl /table=sys$common:[syslib]dcltables.exe - |
| 491 | /output=sys$common:[syslib]dcltables.exe |
| 492 | $ install replace sys$common:[syslib]dcltables.exe |
| 493 | $ exit |
| 494 | |
| 495 | =head2 INSTALLing Perl images (optional) on VMS |
| 496 | |
| 497 | On systems that are using perl quite a bit, and particularly those with |
| 498 | minimal RAM, you can boost the performance of perl by INSTALLing it as |
| 499 | a known image. PERLSHR.EXE is typically larger than 3000 blocks |
| 500 | and that is a reasonably large amount of IO to load each time perl is |
| 501 | invoked. |
| 502 | |
| 503 | INSTALL ADD PERLSHR/SHARE |
| 504 | INSTALL ADD PERL/HEADER |
| 505 | |
| 506 | should be enough for PERLSHR.EXE (/share implies /header and /open), |
| 507 | while /HEADER should do for PERL.EXE (perl.exe is not a shared image). |
| 508 | |
| 509 | If your code 'use's modules, check to see if there is a shareable image for |
| 510 | them, too. In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File, |
| 511 | DCLsym, and Stdio, and other extensions all have shared images that can be |
| 512 | installed /SHARE. |
| 513 | |
| 514 | How much of a win depends on your memory situation, but if you are firing |
| 515 | off perl with any regularity (like more than once every 20 seconds or so) |
| 516 | it is probably beneficial to INSTALL at least portions of perl. |
| 517 | |
| 518 | While there is code in perl to remove privileges as it runs you are advised |
| 519 | to NOT INSTALL PERL.EXE with PRIVs! |
| 520 | |
| 521 | =head2 Running h2ph to create perl header files (optional) on VMS |
| 522 | |
| 523 | If using DEC C or Compaq C ensure that you have extracted loose versions |
| 524 | of your compiler's header or *.H files. Be sure to check the contents of: |
| 525 | |
| 526 | SYS$LIBRARY:DECC$RTLDEF.TLB |
| 527 | SYS$LIBRARY:SYS$LIB_C.TLB |
| 528 | SYS$LIBRARY:SYS$STARLET_C.TLB |
| 529 | |
| 530 | etcetera. |
| 531 | |
| 532 | If using GNU cc then also check your GNU_CC:[000000...] tree for the locations |
| 533 | of the GNU cc headers. |
| 534 | |
| 535 | =head1 Reporting Bugs |
| 536 | |
| 537 | If you come across what you think might be a bug in Perl, please report |
| 538 | it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through |
| 539 | the process of creating a bug report. This script includes details of your |
| 540 | installation, and is very handy. Completed bug reports should go to |
| 541 | perlbug@perl.com. |
| 542 | |
| 543 | =head1 CAVEATS |
| 544 | |
| 545 | Probably the single biggest gotcha in compiling Perl is giving the wrong |
| 546 | switches to MMS/MMK when you build. Use *exactly* what the configure.com |
| 547 | script prints! |
| 548 | |
| 549 | The next big gotcha is directory depth. Perl can create directories four, |
| 550 | five, or even six levels deep during the build, so you don't have to be |
| 551 | too deep to start to hit the RMS 8 level limit (for ODS 2 volumes which were |
| 552 | common on versions of VMS prior to V7.2 and even with V7.2 on the VAX). |
| 553 | It is best to do: |
| 554 | |
| 555 | DEFINE/TRANS=(CONC,TERM) PERLSRC "disk:[dir.dir.dir.perldir.]" |
| 556 | SET DEFAULT PERLSRC:[000000] |
| 557 | |
| 558 | before building in cases where you have to unpack the distribution so deep |
| 559 | (note the trailing period in the definition of PERLSRC). Perl modules |
| 560 | from CPAN can be just as bad (or worse), so watch out for them, too. Perl's |
| 561 | configuration script will warn if it thinks you are too deep (at least on |
| 562 | a VAX or on Alpha versions of VMS prior to 7.2). But MakeMaker will not |
| 563 | warn you if you start out building a module too deep in a directory. |
| 564 | |
| 565 | As noted above ODS-5 escape sequences such as ^. can break the perl |
| 566 | build. Solutions include renaming files and directories as needed or |
| 567 | being careful to use the -o switch or /ODS2 qualifier with latter |
| 568 | versions of the vmstar utility when unpacking perl or CPAN modules |
| 569 | on ODS-5 volumes. |
| 570 | |
| 571 | Be sure that the process that you use to build perl has a PGFLQ greater |
| 572 | than 100000. Be sure to have a correct local time zone to UTC offset |
| 573 | defined (in seconds) in the logical name SYS$TIMEZONE_DIFFERENTIAL before |
| 574 | running the regression test suite. The SYS$MANAGER:UTC$CONFIGURE_TDF.COM |
| 575 | procedure will help you set that logical for your system but may require |
| 576 | system privileges. For example, a location 5 hours west of UTC (such as |
| 577 | the US East coast while not on daylight savings time) would have: |
| 578 | |
| 579 | DEFINE SYS$TIMEZONE_DIFFERENTIAL "-18000" |
| 580 | |
| 581 | A final thing that causes trouble is leftover pieces from a failed |
| 582 | build. If things go wrong make sure you do a "(MMK|MMS|make) realclean" |
| 583 | before you rebuild. |
| 584 | |
| 585 | =head2 DEC C issues with Perl on VMS |
| 586 | |
| 587 | Note to DEC C users: Some early versions (pre-5.2, some pre-4. If you're DEC |
| 588 | C 5.x or higher, with current patches if any, you're fine) of the DECCRTL |
| 589 | contained a few bugs which affect Perl performance: |
| 590 | |
| 591 | =over 4 |
| 592 | |
| 593 | =item - pipes |
| 594 | |
| 595 | Newlines are lost on I/O through pipes, causing lines to run together. |
| 596 | This shows up as RMS RTB errors when reading from a pipe. You can |
| 597 | work around this by having one process write data to a file, and |
| 598 | then having the other read the file, instead of the pipe. This is |
| 599 | fixed in version 4 of DEC C. |
| 600 | |
| 601 | =item - modf() |
| 602 | |
| 603 | The modf() routine returns a non-integral value for some values above |
| 604 | INT_MAX; the Perl "int" operator will return a non-integral value in |
| 605 | these cases. This is fixed in version 4 of DEC C. |
| 606 | |
| 607 | =item - ALPACRT ECO |
| 608 | |
| 609 | On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine |
| 610 | changes the process default device and directory permanently, even |
| 611 | though the call specified that the change should not persist after |
| 612 | Perl exited. This is fixed by DEC CSC patch ALPACRT04_061 or later. |
| 613 | See also: |
| 614 | |
| 615 | http://ftp.support.compaq.com/patches/.new/openvms.shtml |
| 616 | |
| 617 | =back |
| 618 | |
| 619 | Please note that in later versions "DEC C" may also be known as |
| 620 | "Compaq C". |
| 621 | |
| 622 | =head2 GNU issues with Perl on VMS |
| 623 | |
| 624 | It has been a while since the GNU utilities such as GCC or GNU make |
| 625 | were used to build perl on VMS. Hence they may require a great deal |
| 626 | of source code modification to work again. |
| 627 | |
| 628 | http://slacvx.slac.stanford.edu/HELP/GCC |
| 629 | http://www.progis.de/ |
| 630 | http://www.lp.se/products/gnu.html |
| 631 | |
| 632 | =head2 Floating Point Considerations |
| 633 | |
| 634 | Prior to 5.8.0, Perl simply accepted the default floating point options of the |
| 635 | C compiler, namely representing doubles with D_FLOAT on VAX and G_FLOAT on |
| 636 | Alpha. Single precision floating point values are represented in F_FLOAT |
| 637 | format when either D_FLOAT or G_FLOAT is in use for doubles. Beginning with |
| 638 | 5.8.0, Alpha builds now use IEEE floating point formats by default, which in |
| 639 | VMS parlance are S_FLOAT for singles and T_FLOAT for doubles. IEEE is not |
| 640 | available on VAX, so F_FLOAT and D_FLOAT remain the defaults for singles and |
| 641 | doubles respectively. The available non-default options are G_FLOAT on VAX |
| 642 | and D_FLOAT or G_FLOAT on Alpha. |
| 643 | |
| 644 | The use of IEEE on Alpha introduces NaN, infinity, and denormalization |
| 645 | capabilities not available with D_FLOAT and G_FLOAT. When using one of those |
| 646 | non-IEEE formats, silent underflow and overflow are emulated in the conversion |
| 647 | of strings to numbers, but it is preferable to get the real thing by using |
| 648 | IEEE where possible. |
| 649 | |
| 650 | Regardless of what floating point format you consider preferable, be aware |
| 651 | that the choice may have an impact on compatibility with external libraries, |
| 652 | such as database interfaces, and with existing data, such as data created with |
| 653 | the C<pack> function and written to disk, or data stored via the Storable |
| 654 | extension. For example, a C<pack("d", $foo)")> will create a D_FLOAT, |
| 655 | G_FLOAT, or T_FLOAT depending on what your Perl was configured with. When |
| 656 | written to disk, the value can only be retrieved later by a Perl configured |
| 657 | with the same floating point option that was in effect when it was created. |
| 658 | |
| 659 | To obtain a non-IEEE build on Alpha, simply answer no to the "Use IEEE math?" |
| 660 | question during the configuration. To obtain an option different from the C |
| 661 | compiler default on either VAX or Alpha, put in the option that you want in |
| 662 | answer to the "Any additional cc flags?" question. For example, to obtain a |
| 663 | G_FLOAT build on VAX, put in C</FLOAT=G_FLOAT>. |
| 664 | |
| 665 | =head2 Multinet issues with Perl on VMS |
| 666 | |
| 667 | Prior to the release of Perl 5.8.0 it was noted that the regression |
| 668 | test for lib/Net/hostent (in file [.lib.Net]hostent.t) will fail owing |
| 669 | to problems with the hostent structure returned by C calls to either |
| 670 | gethostbyname() or gethostbyaddr() using DEC or Compaq C with a |
| 671 | Multinet TCP/IP stack. The problem was noted in Multinet 4.3A |
| 672 | using either Compaq C 6.5 or DEC C 6.0, and with Multinet 4.2A |
| 673 | using DEC C 5.2, but could easily affect other versions of Multinet. |
| 674 | Process Software Inc. has acknowledged a bug in the Multinet version |
| 675 | of UCX$IPC_SHR and has provided an ECO for it. The ECO is called |
| 676 | UCX_LIBRARY_EMULATION-010_A044 and is available from: |
| 677 | |
| 678 | http://www.multinet.process.com/eco.html |
| 679 | |
| 680 | As of this writing, the ECO is only available for Multinet versions |
| 681 | 4.3A and later. You may determine the version of Multinet that you |
| 682 | are running using the command: |
| 683 | |
| 684 | multinet show /version |
| 685 | |
| 686 | from the DCL command prompt. |
| 687 | |
| 688 | If the ECO is unavailable for your version of Multinet and you are |
| 689 | unable to upgrade, you might try using Perl programming constructs |
| 690 | such as: |
| 691 | |
| 692 | $address = substr($gethostbyname_addr,0,4); |
| 693 | |
| 694 | to temporarily work around the problem, or if you are brave |
| 695 | and do not mind the possibility of breaking IPv6 addresses, |
| 696 | you might modify the pp_sys.c file to add an ad-hoc correction |
| 697 | like so: |
| 698 | |
| 699 | |
| 700 | --- pp_sys.c;1 Thu May 30 14:42:17 2002 |
| 701 | +++ pp_sys.c Thu May 30 12:54:02 2002 |
| 702 | @@ -4684,6 +4684,10 @@ |
| 703 | } |
| 704 | #endif |
| 705 | |
| 706 | + if (hent) { |
| 707 | + hent->h_length = 4; |
| 708 | + } |
| 709 | + |
| 710 | if (GIMME != G_ARRAY) { |
| 711 | PUSHs(sv = sv_newmortal()); |
| 712 | if (hent) { |
| 713 | |
| 714 | then re-compile and re-test your perl. After the installation |
| 715 | of the Multinet ECO you ought to back out any such changes though. |
| 716 | |
| 717 | =head1 Mailing Lists |
| 718 | |
| 719 | There are several mailing lists available to the Perl porter. For VMS |
| 720 | specific issues (including both Perl questions and installation problems) |
| 721 | there is the VMSPERL mailing list. It is usually a low-volume (10-12 |
| 722 | messages a week) mailing list. |
| 723 | |
| 724 | To subscribe, send a mail message to VMSPERL-SUBSCRIBE@PERL.ORG. The VMSPERL |
| 725 | mailing list address is VMSPERL@PERL.ORG. Any mail sent there gets echoed |
| 726 | to all subscribers of the list. There is a searchable archive of the list |
| 727 | on the web at: |
| 728 | |
| 729 | http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/ |
| 730 | |
| 731 | To unsubscribe from VMSPERL send a message to VMSPERL-UNSUBSCRIBE@PERL.ORG. |
| 732 | Be sure to do so from the subscribed account that you are canceling. |
| 733 | |
| 734 | =head2 Web sites for Perl on VMS |
| 735 | |
| 736 | Vmsperl pages on the web include: |
| 737 | |
| 738 | http://www.sidhe.org/vmsperl/index.html |
| 739 | http://www.crinoid.com/ |
| 740 | http://duphy4.physics.drexel.edu/pub/cgi_info.htmlx |
| 741 | http://www.cpan.org/modules/by-module/VMS/ |
| 742 | http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/ |
| 743 | http://www.best.com/~pvhp/vms/ |
| 744 | http://www-ang.kfunigraz.ac.at/~binder/perl.html |
| 745 | http://lists.perl.org/showlist.cgi?name=vmsperl |
| 746 | http://archive.develooper.com/vmsperl@perl.org/ |
| 747 | http://www.openvms.compaq.com/openvms/products/ips/apache/csws_modperl.html |
| 748 | |
| 749 | =head1 SEE ALSO |
| 750 | |
| 751 | Perl information for users and programmers about the port of perl to VMS is |
| 752 | available from the [.VMS]PERLVMS.POD file that gets installed as L<perlvms>. |
| 753 | For administrators the perlvms document also includes a detailed discussion |
| 754 | of extending vmsperl with CPAN modules after Perl has been installed. |
| 755 | |
| 756 | =head1 AUTHORS |
| 757 | |
| 758 | Revised 10-October-2001 by Craig Berry craigberry@mac.com. |
| 759 | Revised 25-February-2000 by Peter Prymmer pvhp@best.com. |
| 760 | Revised 27-October-1999 by Craig Berry craigberry@mac.com. |
| 761 | Revised 01-March-1999 by Dan Sugalski dan@sidhe.org. |
| 762 | Originally by Charles Bailey bailey@newman.upenn.edu. |
| 763 | |
| 764 | =head1 ACKNOWLEDGEMENTS |
| 765 | |
| 766 | A real big thanks needs to go to Charles Bailey |
| 767 | bailey@newman.upenn.edu, who is ultimately responsible for Perl 5.004 |
| 768 | running on VMS. Without him, nothing the rest of us have done would be at |
| 769 | all important. |
| 770 | |
| 771 | There are, of course, far too many people involved in the porting and testing |
| 772 | of Perl to mention everyone who deserves it, so please forgive us if we've |
| 773 | missed someone. That said, special thanks are due to the following: |
| 774 | |
| 775 | Tim Adye T.J.Adye@rl.ac.uk |
| 776 | for the VMS emulations of getpw*() |
| 777 | David Denholm denholm@conmat.phys.soton.ac.uk |
| 778 | for extensive testing and provision of pipe and SocketShr code, |
| 779 | Mark Pizzolato mark@infocomm.com |
| 780 | for the getredirection() code |
| 781 | Rich Salz rsalz@bbn.com |
| 782 | for readdir() and related routines |
| 783 | Peter Prymmer pvhp@best.com |
| 784 | for extensive testing, as well as development work on |
| 785 | configuration and documentation for VMS Perl, |
| 786 | Dan Sugalski dan@sidhe.org |
| 787 | for extensive contributions to recent version support, |
| 788 | development of VMS-specific extensions, and dissemination |
| 789 | of information about VMS Perl, |
| 790 | the Stanford Synchrotron Radiation Laboratory and the |
| 791 | Laboratory of Nuclear Studies at Cornell University for |
| 792 | the opportunity to test and develop for the AXP, |
| 793 | John Hasstedt John.Hasstedt@sunysb.edu |
| 794 | for VAX VMS V7.2 support |
| 795 | |
| 796 | and to the entire VMSperl group for useful advice and suggestions. In |
| 797 | addition the perl5-porters deserve credit for their creativity and |
| 798 | willingness to work with the VMS newcomers. Finally, the greatest debt of |
| 799 | gratitude is due to Larry Wall larry@wall.org, for having the ideas which |
| 800 | have made our sleepless nights possible. |
| 801 | |
| 802 | Thanks, |
| 803 | The VMSperl group |
| 804 | |
| 805 | =cut |
| 806 | |