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