/[[:alpha]/ now dies on unmatched [] instead of
[p5sagit/p5-mst-13.2.git] / README.vms
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.
28
29 Also note that, as of Perl version 5.005 and later, an ANSI C compliant 
30 compiler is required to build Perl.  VAX C is *not* ANSI compliant, as it 
31 died a natural death some time before the standard was set.  Therefore 
32 VAX C will not compile perl 5.005.  We are sorry about that.
33
34 If you are stuck without DEC C (the VAX C license should be good for DEC C,
35 but the media charges might prohibit an upgrade), consider getting Gnu C
36 instead.
37
38
39 =head2 Introduction
40
41 The VMS port of Perl is as functionally complete as any other Perl port
42 (and as complete as the ports on some Unix systems). The Perl binaries
43 provide all the Perl system calls that are either available under VMS or
44 reasonably emulated. There are some incompatibilities in process handling
45 (e.g. the fork/exec model for creating subprocesses doesn't do what you
46 might expect under Unix), mainly because VMS and Unix handle processes and
47 sub-processes very differently.
48
49 There are still some unimplemented system functions, and of course we
50 could use modules implementing useful VMS system services, so if you'd like
51 to lend a hand we'd love to have you.  Join the Perl Porting Team Now!
52
53 The current sources and build procedures have been tested on a VAX using
54 DEC C, and on an AXP using DEC C. If you run into problems with
55 other compilers, please let us know.
56
57 There are issues with various versions of DEC C, so if you're not running a
58 relatively modern version, check the "DEC C issues" section later on in this
59 document.
60
61 =head2 Other required software
62
63 In addition to VMS and DCL you will need two things:
64
65 =over 4
66
67 =item 1  A C compiler. 
68
69 DEC C or gcc for VMS (AXP or VAX).
70
71 =item 2  A make tool. 
72
73 DEC's MMS (v2.6 or later), or MadGoat's free MMS
74 analog MMK (available from ftp.madgoat.com/madgoat) both work
75 just fine. Gnu Make might work, but it's been so long since
76 anyone's tested it that we're not sure.  MMK is free though, so
77 go ahead and use that.
78
79 =back
80
81 =head2 Additional software that is optional
82
83 You may also want to have on hand:
84
85 =over 4
86
87 =item 1  GUNZIP/GZIP.EXE for VMS 
88
89 A de-compressor for *.gz and *.tgz files available from a number 
90 of web/ftp sites.
91
92     http://www.fsf.org/order/ftp.html
93     ftp://ftp.uu.net/archive/systems/gnu/diffutils*.tar.gz
94     ftp://gatekeeper.dec.com/pub/GNU/diffutils*.tar.gz
95     ftp://ftp.gnu.org/pub/gnu/diffutils*.tar.gz 
96     http://www.openvms.digital.com/cd/GZIP/
97     ftp://ftp.digital.com/pub/VMS/
98
99 =item 2  VMS TAR 
100
101 For reading and writing unix tape archives (*.tar files).  Vmstar is also 
102 available from a number of web/ftp sites.
103
104     ftp://ftp.lp.se/vms/
105     http://www.openvms.digital.com/cd/VMSTAR/
106     ftp://ftp.digital.com/pub/VMS/
107
108 =item 3  UNZIP.EXE for VMS
109
110 A combination decompressor and archive reader/writer for *.zip files.  
111 Unzip is available from a number of web/ftp sites.
112
113     http://www.cdrom.com/pub/infozip/UnZip.html
114     http://www.openvms.digital.com/cd/INFO-ZIP/
115     ftp://ftp.digital.com/pub/VMS/
116     ftp://ftp.openvms.digital.com/
117     ftp://ftp.madgoat.com/madgoat/
118     ftp://ftp.wku.edu/vms/
119
120 =item 4  MOST
121
122 Most is an optional pager that is convenient to use with perldoc (unlike 
123 TYPE/PAGE, MOST can go forward and backwards in a document and supports 
124 regular expression searching).  Most builds with the slang 
125 library on VMS.  Most and slang are available from:
126
127     ftp://space.mit.edu/pub/davis/
128     ftp://ftp.wku.edu/vms/narnia/most.zip
129
130 =back
131
132 Please note that UNZIP and GUNZIP are not the same thing (they work with
133 different formats).  Many of the useful files from CPAN (the Comprehensive
134 Perl Archive Network) are in *.tar.gz format (this includes copies of the
135 source code for perl as well as modules and scripts that you may wish to
136 add later) hence you probably want to have GUNZIP.EXE and VMSTAR.EXE on
137 your VMS machine.
138
139 If you want to include socket support, you'll need a TCP/IP stack and either
140 DEC C, or socket libraries.  See the "Socket Support (optional)" topic 
141 for more details.
142
143 =head1 Configuring the Perl build
144
145 To configure perl (a necessary first step), issue the command
146
147    @ Configure
148
149 from the top of an unpacked perl source directory.  You will be asked a 
150 series of questions, and the answers to them (along with the capabilities 
151 of your C compiler and network stack) will determine how perl is custom 
152 built for your machine.
153
154 If you have multiple C compilers installed, you'll have your choice of
155 which one to use.  Various older versions of DEC C had some caveats, so if
156 you're using a version older than 5.2, check the "DEC C Issues" section.
157
158 If you have any symbols or logical names in your environment that may 
159 interfere with the build or regression testing of perl then configure.com 
160 will try to warn you about them.  If a logical name is causing
161 you trouble but is in an LNM table that you do not have write access to
162 then try defining your own to a harmless equivalence string in a table 
163 such that it is resolved before the other (e.g. if TMP is defined in the
164 SYSTEM table then try DEFINE TMP "NL:" or somesuch in your process table) 
165 otherwise simply deassign the dangerous logical names.  The potentially 
166 troublesome logicals and symbols are:
167
168     TMP  "LOGICAL"
169     LIB  "LOGICAL"
170     T    "LOGICAL"
171     FOO  "LOGICAL"
172     EXT  "LOGICAL"
173     TEST "SYMBOL"
174
175 As a handy shortcut, the command:
176
177     @ Configure "-des"
178
179 (note the quotation marks and case) will choose reasonable defaults 
180 automatically (it takes DEC C over Gnu C, DEC C sockets over SOCKETSHR 
181 sockets, and either over no sockets).  More help with configure.com is 
182 available from:
183
184     @ Configure "-h"
185
186 See the "Changing compile-time options (optional)" section below to learn
187 even more details about how to influence the outcome of the important 
188 configuration step.  If you find yourself reconfiguring and rebuilding 
189 then be sure to also follow the advice in the "Cleaning up and starting 
190 fresh (optional)" and the checklist of items in the "CAVEATS" sections 
191 below.
192
193 =head2 Changing compile-time options (optional)
194
195 Most of the user definable features of Perl are enabled or disabled in
196 [.VMS]CONFIG.VMS. There is code in there to Do The Right Thing, but that 
197 may end up being the wrong thing for you.  Make sure you understand what 
198 you are doing since inappropriate changes to CONFIG.VMS can render perl 
199 unbuildable.
200
201 Odds are that there's nothing here to change, unless you're on a version of
202 VMS later than 6.2 and DEC C later than 5.6.  Even if you are, the correct
203 values will still be chosen, most likely.  Poking around here should be
204 unnecessary.
205
206 The one exception is the various *DIR install locations. Changing those
207 requires changes in genconfig.pl as well.  Be really careful if you need to
208 change these, as they can cause some fairly subtle problems.
209
210 =head2 Socket Support (optional)
211
212 Perl includes a number of functions for IP sockets, which are available if
213 you choose to compile Perl with socket support.  Since IP networking is an 
214 optional addition to VMS, there are several different IP stacks available.  
215 How well integrated they are into the system depends on the stack, your 
216 version of VMS, and the version of your C compiler.
217
218 The most portable solution uses the SOCKETSHR library. In combination with
219 either UCX or NetLib, this supports all the major TCP stacks (Multinet,
220 Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with
221 all the compilers on both VAX and Alpha. The socket interface is also
222 consistent across versions of VMS and C compilers. It has a problem with
223 UDP sockets when used with Multinet, though, so you should be aware of
224 that.
225
226 The other solution available is to use the socket routines built into DEC
227 C. Which routines are available depend on the version of VMS you're
228 running, and require proper UCX emulation by your TCP/IP vendor.
229 Relatively current versions of Multinet, TCPWare, Pathway, and UCX all
230 provide the required libraries--check your manuals or release notes to see
231 if your version is new enough.
232
233 =head1 Building Perl
234
235 The configuration script will print out, at the very end, the MMS or MMK
236 command you need to compile perl.  Issue it (exactly as printed) to start
237 the build.  
238
239 Once you issue your MMS or MMK command, sit back and wait.  Perl should 
240 compile and link without a problem.  If a problem does occur check the 
241 "CAVEATS" section of this document.  If that does not help send some 
242 mail to the VMSPERL mailing list.  Instructions are in the "Mailing Lists" 
243 section of this document.
244
245 =head1 Testing Perl
246
247 Once Perl has built cleanly you need to test it to make sure things work.
248 This step is very important since there are always things that can go wrong
249 somehow and yield a dysfunctional Perl for you.
250
251 Testing is very easy, though, as there's a full test suite in the perl
252 distribution.  To run the tests, enter the *exact* MMS line you used to
253 compile Perl and add the word "test" to the end, like this:
254
255 If the compile command was:
256
257     MMS
258
259 then the test command ought to be:
260
261     MMS test
262
263 MMS (or MMK) will run all the tests.  This may take some time, as there are 
264 a lot of tests.  If any tests fail, there will be a note made on-screen. 
265 At the end of all the tests, a summary of the tests, the number passed and 
266 failed, and the time taken will be displayed.
267
268 If any tests fail, it means something is wrong with Perl. If the test suite
269 hangs (some tests can take upwards of two or three minutes, or more if
270 you're on an especially slow machine, depending on your machine speed, so
271 don't be hasty), then the test *after* the last one displayed failed. Don't
272 install Perl unless you're confident that you're OK. Regardless of how
273 confident you are, make a bug report to the VMSPerl mailing list.
274
275 If one or more tests fail, you can get more information on the failure by 
276 issuing this command sequence:
277
278     @ [.VMS]TEST .typ "" "-v" [.subdir]test.T
279
280 where ".typ" is the file type of the Perl images you just built (if you
281 didn't do anything special, use .EXE), and "[.subdir]test.T" is the test
282 that failed. For example, with a normal Perl build, if the test indicated
283 that [.op]time failed, then you'd do this:
284
285     @ [.VMS]TEST .EXE "" "-v" [.OP]TIME.T
286
287 When you send in a bug report for failed tests, please include the output
288 from this command, which is run from the main source directory:
289
290     MCR []MINIPERL "-V"
291
292 Note that -"V" really is a capital V in double quotes. This will dump out a
293 couple of screens worth of configuration information, and can help us 
294 diagnose the problem.  If (and only if) that did not work then try enclosing 
295 the output of:
296
297     MMS printconfig
298
299 If (and only if) that did not work then try enclosing the output of:
300
301     @ [.vms]myconfig
302
303 You may also be asked to provide your C compiler version ("CC/VERSION NL:" 
304 with DEC C, "gcc --version" with GNU CC).  To obtain the version of MMS or 
305 MMK you are running try "MMS/ident" or "MMK /ident".  The GNU make version 
306 can be identified with "make --version".
307
308 =head2 Cleaning up and starting fresh (optional)
309
310 If you need to recompile from scratch, you have to make sure you clean up
311 first.  There is a procedure to do it--enter the *exact* MMS line you used 
312 to compile and add "realclean" at the end, like this:
313
314 if the compile command was:
315
316     MMS
317
318 then the cleanup command ought to be:
319
320     MMS realclean
321
322 If you do not do this things may behave erratically during the subsequent 
323 rebuild attempt.  They might not, too, so it is best to be sure and do it.
324
325 =head1 Installing Perl
326
327 There are several steps you need to take to get Perl installed and
328 running.
329
330 =over 4
331
332 =item 1
333
334 Check your default file protections with
335
336      SHOW PROTECTION /DEFAULT
337
338 and adjust if necessary with SET PROTECTION=(code)/DEFAULT.
339
340 =item 2
341
342 Create a directory somewhere and either run @perl_setup or 
343 define the concealed logical PERL_ROOT to point to it by hand. 
344 For example, 
345
346     CREATE/DIRECTORY dka200:[perl]
347     @PERL_SETUP
348     SHOW LOGICAL PERL_ROOT
349
350 or,
351
352     CREATE/DIRECTORY dka200:[perl]
353     DEFINE/TRANS=(CONC,TERM) PERL_ROOT dka200:[perl.]
354
355
356 =item 3
357
358 Run the install script via:
359
360     MMS install
361
362 or
363
364     MMK install
365
366 If for some reason it complains about target INSTALL being up to date,
367 throw a /FORCE switch on the MMS or MMK command.
368
369 =back
370
371 The DCL script PERL_SETUP.COM that is written by CONFIGURE.COM
372 will help you with the definition of PERL_ROOT, PERLSHR and the PERL
373 Foreign symbol.  Take a look at PERL_SETUP.COM and modify it if you want 
374 to.  Then copy PERL_SETUP.COM to a place accessible to your perl users.  
375 For example:
376
377     COPY PERL_SETUP.COM SYS$LIBRARY: 
378
379 If you want to have everyone on the system have access to perl
380 then add a line that reads
381
382     $ @sys$library:perl_setup
383
384 to SYS$MANAGER:SYLOGIN.COM.
385
386 Two alternatives to the foreign symbol would be to install PERL into 
387 DCLTABLES.EXE (Check out the section "Installing Perl into DCLTABLES 
388 (optional)" for more information), or put the image in a 
389 directory that's in your DCL$PATH (if you're using VMS V6.2 or higher).
390
391 An alternative to having PERL_SETUP.COM define the PERLSHR logical name
392 is to simply copy it into the system shareable library directory with:
393
394     copy perl_root:[000000]perlshr.exe sys$share:
395
396 See also the "INSTALLing images (optional)" section.
397
398 =head2 Installing Perl into DCLTABLES (optional)
399
400 Execute the following command file to define PERL as a DCL command.
401 You'll need CMKRNL privilege to install the new dcltables.exe.
402
403     $ create perl.cld
404     !
405     ! modify to reflect location of your perl.exe
406     !
407     define verb perl
408       image perl_root:[000000]perl.exe
409       cliflags (foreign)
410     $!
411     $ set command perl /table=sys$common:[syslib]dcltables.exe -
412      /output=sys$common:[syslib]dcltables.exe
413     $ install replace sys$common:[syslib]dcltables.exe
414     $ exit
415
416 =head2 INSTALLing images (optional)
417
418 On systems that are using perl quite a bit, and particularly those with 
419 minimal RAM, you can boost the performance of perl by INSTALLing it as
420 a known image.  PERLSHR.EXE is typically larger than 2000 blocks
421 and that is a reasonably large amount of IO to load each time perl is 
422 invoked. 
423
424    INSTALL ADD PERLSHR/SHARE
425    INSTALL ADD PERL/HEADER
426
427 should be enough for PERLSHR.EXE (/share implies /header and /open), 
428 while /HEADER should do for PERL.EXE (perl.exe is not a shared image).
429
430 If your code 'use's modules, check to see if there is a shareable image for
431 them, too.  In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File,
432 DCLsym, and Stdio all have shared images that can be installed /SHARE.
433
434 How much of a win depends on your memory situation, but if you are firing
435 off perl with any regularity (like more than once every 20 seconds or so)
436 it is probably beneficial to INSTALL at least portions of perl.
437
438 While there is code in perl to remove privileges as it runs you are advised
439 to NOT INSTALL PERL.EXE with PRIVs!
440
441 =head1 Reporting Bugs
442
443 If you come across what you think might be a bug in Perl, please report
444 it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through
445 the process of creating a bug report. This script includes details of your
446 installation, and is very handy. Completed bug reports should go to
447 perlbug@perl.com.
448
449 =head1 CAVEATS
450
451 Probably the single biggest gotcha in compiling Perl is giving the wrong
452 switches to MMS/MMK when you build. Use *exactly* what the configure.com 
453 script prints!
454
455 The next big gotcha is directory depth.  Perl can create directories four,
456 five, or even six levels deep during the build, so you don't have to be 
457 too deep to start to hit the RMS 8 level limit (for versions of VMS prior 
458 to V7.2 and even with V7.2 on the VAX).  It is best to do
459
460     DEFINE/TRANS=(CONC,TERM) PERLSRC "disk:[dir.dir.dir.perldir.]"
461     SET DEFAULT PERLSRC:[000000]
462
463 before building in cases where you have to unpack the distribution so deep
464 (note the trailing period in the definition of PERLSRC).  Perl modules 
465 from CPAN can be just as bad (or worse), so watch out for them, too. Perl's
466 configuration script will warn if it thinks you are too deep (at least on 
467 a VAX or on Alpha versions of VMS prior to 7.2).  But MakeMaker will not 
468 warn you if you start out building a module too deep in a directory.
469
470 Be sure that the process that you use to build perl has a PGFLQ greater
471 than 100000.  Be sure to have a correct local time zone to UTC offset
472 defined (in seconds) in the logical name SYS$TIMEZONE_DIFFERENTIAL before
473 running the regression test suite.  The SYS$MANAGER:UTC$CONFIGURE_TDF.COM 
474 procedure will help you set that logical for your system but may require 
475 system privileges.  For example, a location 5 hours west of UTC (such as 
476 the US East coast while not on daylight savings time) would have:
477
478     DEFINE SYS$TIMEZONE_DIFFERENTIAL "-18000"
479
480 A final thing that causes trouble is leftover pieces from a failed
481 build.  If things go wrong make sure you do a "(MMK|MMS|make) realclean"
482 before you rebuild.
483
484 =head2 DEC C issues
485
486 Note to DEC C users: Some early versions (pre-5.2, some pre-4. If you're DEC
487 C 5.x or higher, with current patches if any, you're fine) of the DECCRTL
488 contained a few bugs which affect Perl performance:
489
490 =over 4
491
492 =item - pipes
493
494 Newlines are lost on I/O through pipes, causing lines to run together.
495 This shows up as RMS RTB errors when reading from a pipe.  You can
496 work around this by having one process write data to a file, and
497 then having the other read the file, instead of the pipe.  This is
498 fixed in version 4 of DEC C.
499
500 =item - modf()
501
502 The modf() routine returns a non-integral value for some values above
503 INT_MAX; the Perl "int" operator will return a non-integral value in
504 these cases.  This is fixed in version 4 of DEC C.
505
506 =item - ALPACRT ECO
507
508 On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine
509 changes the process default device and directory permanently, even
510 though the call specified that the change should not persist after
511 Perl exited.  This is fixed by DEC CSC patch ALPACRT04_061 or later.
512 See also:
513
514     http://ftp.service.digital.com/patches/.new/openvms.html
515
516 =back
517
518 Please note that in later versions "DEC C" may also be known as 
519 "Compaq C".
520
521 =head2 GNU issues
522
523 It has been a while since the GNU utilities such as GCC or GNU make
524 were used to build perl on VMS.  Hence they may require a great deal
525 of source code modification to work again.
526
527     http://slacvx.slac.stanford.edu/HELP/GCC
528     http://www.progis.de/
529     http://vms.gnu.org/
530     http://www.lp.se/products/gnu.html
531
532 =head1 Mailing Lists
533
534 There are several mailing lists available to the Perl porter.  For VMS
535 specific issues (including both Perl questions and installation problems)
536 there is the VMSPERL mailing list.  It is usually a low-volume (10-12
537 messages a week) mailing list.
538
539 The subscription address is MAJORDOMO@PERL.ORG.  Send a mail message with 
540 just the words SUBSCRIBE VMSPERL in the body of the message.
541    
542 The VMSPERL mailing list address is VMSPERL@PERL.ORG.  Any mail sent there
543 gets echoed to all subscribers of the list.  There is a searchable archive of
544 the list on the web at:
545
546     http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/
547    
548 To unsubscribe from VMSPERL send the message UNSUBSCRIBE VMSPERL to
549 MAJORDOMO@PERL.ORG.  Be sure to do so from the subscribed account that 
550 you are canceling.
551
552 =head2 Web sites
553
554 Vmsperl pages on the web include:
555
556     http://www.sidhe.org/vmsperl/index.html
557     http://duphy4.physics.drexel.edu/pub/cgi_info.htmlx
558     http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/
559     http://www.cpan.org/modules/by-module/VMS/
560     http://nucwww.chem.sunysb.edu/htbin/software_list.cgi
561     http://www.best.com/~pvhp/vms/
562     http://bkfug.kfunigraz.ac.at/~binder/perl.html
563
564 =head1 SEE ALSO
565
566 Perl information for users and programmers about the port of perl to VMS is
567 available from the [.VMS]PERLVMS.POD file that gets installed as L<perlvms>.
568 For administrators the perlvms document also includes a detailed discussion 
569 of extending vmsperl with CPAN modules after Perl has been installed.
570
571 =head1 AUTHORS
572
573 Last revised 25-February-2000 by Peter Prymmer pvhp@best.com.  
574 Revised 27-October-1999 by Craig Berry craig.berry@metamorgs.com.  
575 Revised 01-March-1999 by Dan Sugalski dan@sidhe.org.  
576 Originally by Charles Bailey bailey@newman.upenn.edu.
577
578 =head1 ACKNOWLEDGEMENTS
579
580 A real big thanks needs to go to Charles Bailey
581 bailey@newman.upenn.edu, who is ultimately responsible for Perl 5.004
582 running on VMS. Without him, nothing the rest of us have done would be at
583 all important.
584
585 There are, of course, far too many people involved in the porting and testing
586 of Perl to mention everyone who deserves it, so please forgive us if we've
587 missed someone.  That said, special thanks are due to the following:
588
589   Tim Adye T.J.Adye@rl.ac.uk
590      for the VMS emulations of getpw*()
591   David Denholm denholm@conmat.phys.soton.ac.uk
592      for extensive testing and provision of pipe and SocketShr code,
593   Mark Pizzolato mark@infocomm.com
594      for the getredirection() code
595   Rich Salz rsalz@bbn.com
596      for readdir() and related routines
597   Peter Prymmer pvhp@best.com 
598      for extensive testing, as well as development work on
599      configuration and documentation for VMS Perl,
600   Dan Sugalski dan@sidhe.org
601      for extensive contributions to recent version support,
602      development of VMS-specific extensions, and dissemination
603      of information about VMS Perl,
604   the Stanford Synchrotron Radiation Laboratory and the
605      Laboratory of Nuclear Studies at Cornell University for
606      the opportunity to test and develop for the AXP,
607   John Hasstedt John.Hasstedt@sunysb.edu
608      for VAX VMS V7.2 support
609
610 and to the entire VMSperl group for useful advice and suggestions.  In
611 addition the perl5-porters deserve credit for their creativity and
612 willingness to work with the VMS newcomers.  Finally, the greatest debt of
613 gratitude is due to Larry Wall larry@wall.org, for having the ideas which
614 have made our sleepless nights possible.
615
616 Thanks,
617 The VMSperl group
618
619 =cut
620