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