This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
21efaa04591137ea3ba2b5c8a4d469bc9b43d394
[perl5.git] / README.vms
1 Last Revised 11-September-1997 by Dan Sugalski <sugalsd@lbcc.cc.or.us>
2 Originally by Charles Bailey <bailey@newman.upenn.edu>
3
4 * Intro
5
6 The VMS port of Perl is as functionally complete as any other Perl port
7 (and as complete as the ports on some Unix systems). The Perl binaries
8 provide all the Perl system calls that are either available under VMS or
9 reasonably emulated. There are some incompatibilites in process handling
10 (e.g the fork/exec model for creating subprocesses doesn't do what you
11 might expect under Unix), mainly because VMS and Unix handle processes and
12 sub-processes very differently.
13
14 There are still some unimplemented system functions, and of coursse we
15 could use modules implementing useful VMS system services, so if you'd like
16 to lend a hand we'd love to have you. Join the Perl Porting Team Now!
17
18 The current sources and build procedures have been tested on a VAX using
19 VaxC and Dec C, and on an AXP using Dec C. If you run into problems with
20 other compilers, please let us know.
21
22 There are issues with varions versions of Dec C, so if you're not running a
23 relatively modern version, check the Dec C issues section later on in this
24 document.
25
26 * Other required software
27
28 In addition to VMS, you'll need:
29         1) A C compiler. Dec C for AXP, or VAX C, Dec C, or gcc for the
30            VAX.
31         2) A make tool. Dec's MMS (v2.6 or later), or MadGoat's free MMS
32            analog MMK (available from ftp.madgoat.com/madgoat) both work
33            just fine. Gnu Make might work, but it's been so long since
34            anyone's tested it that we're not sure. MMK's free, though, so
35            go ahead and use that.
36
37
38 If you want to include socket support, you'll need a TCP stack and either
39 Dec C, or socket libraries. See the Socket Support topic for more details.
40
41 * Compiling Perl
42
43 >From the top level of the Perl source directory, do this:
44
45 MMS/DESCRIP=[.VMS]DESCRIP.MMS
46
47 If you're on an Alpha, add /Macro=("__AXP__=1","decc=1")
48 If you're using Dec C as your C compiler (you are on all alphas), add
49 /Macro=("decc=1")
50 If Vac C is your default C compiler and you want to use Dec C, add
51 /Macro=("CC=CC/DECC") (Don't forget the /macro=("decc=1")
52 If Dec C is your default C compiler and you want to use Vax C, add
53 /Macro=("CC=CC/VAXC")
54 If you want Socket support and are using the SOCKETSHR socket library, add
55 /Macro=("SOCKETSHR_SOCKETS=1")
56 If you want Socket support and are using the Dec C RTL socket interface
57 (You must be using Dec C for this), add /Macro=("DECC_SOCKETS=1")
58
59 If you have multiple /macro= items, combine them together in one /Macro=()
60 switch, with all the options inside the parentheses separated by commas.
61
62 Samples:
63
64 VMS AXP, with Socketshr sockets:
65
66 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("decc=1","__AXP__=1","SOCKETSHR_SOCKETS=1")
67
68 VMS AXP with no sockets
69
70 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("decc=1","__AXP__=1")
71
72 VMS AXP with the Dec C RTL sockets
73
74 $MMS/DESCRIP=[.VMS]/Macro=("decc=1","__AXP__=1","DECC_SOCKETS=1")
75
76 VMS VAX with default system compiler, no sockets
77
78 $MMS/DESCRIP=[.VMS]DESCRIP.MMS
79
80 VMS VAX with Dec C compiler, no sockets
81
82 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("CC=CC/DECC","decc=1")
83
84 VMS VAX with Dec C compiler, Dec C RTL sockets
85
86 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("CC=CC/DECC","decc=1","DECC_SOCKETS=1")
87
88 VMS VAX with Dec C compiler, Socketshr sockets
89
90 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("CC=CC/DECC","decc=1","SOCKETSHR_SOCKETS=1")
91
92 Using Dec C is recommended over Vax C. The compiler is newer, and
93 supported. (Vax C was decommisioned around 1993) Various older versions had
94 some gotchas, so if you're using a version older than 5.2, check the Dec C
95 Issues section.
96
97 We'll also point out that Dec C will get you at least a ten-fold increase
98 in line-oriented IO over Vax C. The optimizer is amazingly better, too. If
99 you can use Dec C, then you *really*, *really* should.
100
101
102 Once you issue your MMS command, sit back and wait. Perl should build and
103 link without a problem. If it doesn't, check the Gotchas to watch out for
104 section. If that doesn't help, send some mail to the VMSPERL mailing list.
105 Instructions are in the Mailing Lists section.
106
107 * Testing Perl
108
109 Once Perl has built cleanly, you need to test it to make sure things work.
110 This step is very important--there are always things that can go wrong
111 somehow and get you a dysfunctional Perl.
112
113 Testing is very easy, though, as there's a full test suite in the perl
114 distribution. To run the tests, enter the *exact* MMS line you used to
115 compile Perl and add the word "test" to the end, like this:
116
117 Compile Command:
118
119 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1")
120
121 Test Command:
122
123 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1") test
124
125 MMS will run all the tests. This may take some time, as there are a lot of
126 tests. If any tests fail, there will be a note made on-screen. At the end
127 of all the tests, a summary of the tests, the number passed and failed, and
128 the time taken will be displayed.
129
130 If any tests fail, it means something's wrong with Perl. If the test suite
131 hangs (some tests can take upwards of two or three minutes, or more if
132 you're on an especially slow machine, depending on you machine speed, so
133 don't be hasty), then the test *after* the last one displayed failed. Don't
134 install Perl unless you're confident that you're OK. Regardless of how
135 confident you are, make a bug report to the VMSPerl mailing list.
136
137 If one or more tests fail, you can get more info on the failure by issuing
138 this command sequence:
139
140 $ SET DEFAULT [.T]
141 $ @[-.VMS]TEST .typ -v [.subdir]test.T
142
143 where ".typ" is the file type of the Perl images you just built (if you
144 didn't do anything special, use .EXE), and "[.subdir]test.T" is the test
145 that failed. For example, with a normal Perl build, if the test indicated
146 that [.op]time failed, then you'd do this:
147
148 $ SET DEFAULT [.T]
149 $ @[-.VMS]TEST .EXE -v [.OP]TIME.T
150
151 When you send in a bug report for failed tests, please include the output
152 from this command, which is run from the main source directory:
153
154 MCR []MINIPERL "-V"
155
156 Note that "-V" really is a capital V in double quotes. This will dump out a
157 couple of screens worth of config info, and can help us diagnose the problem.
158
159 * Cleaning up and starting fresh
160
161 If you need to recompile from scratch, you have to make sure you clean up
162 first. There's a procedure to do it--enter the *exact* MMS line you used to
163 compile and add "realclean" at the end, like this:
164
165 Compile Command:
166
167 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1")
168
169 Cleanup Command:
170
171 $MMS/DESCRIP=[.VMS]DESCRIP.MMS/Macro=("__AXP__=1","decc=1","DECCRTL_SOCKETS=1") realclean
172
173 If you don't do this, things may behave erratically. They might not, too,
174 so it's best to be sure and do it.
175
176 * Installing Perl
177
178 There are several steps you need to take to get Perl installed and
179 running. At some point we'll have a working install in DESCRIP.MMS, but for
180 right now the procedure's manual, and goes like this.
181
182 1) Create a directory somewhere and define the concealed logical PERL_ROOT
183 to point to it. For example, DEFINE/TRANS=(CONC,TERM) PERL_ROOT dka200:[perl.]
184
185 2) Copy perl.exe into PERL_ROOT:[000000]
186
187 3) Copy everything in [.LIB] and [.UTILS] (including all the
188 subdirectories!) to PERL_ROOT:[LIB] and PERL_ROOT:[UTILS].
189
190 4) Either copy PERLSHR.EXE to SYS$SHARE, or to somewhere globally accessble
191 and define the logical PERLSHR to point to it (DEFINE PERLSHR
192 PERL_ROOT:[000000]PERLSHR.EXE or something like that). The PerlShr image
193 should have W:RE protections on it. (Just W:E triggers increased security in
194 the image activator. Not a huge problem, but Perl will need to have any
195 other shared image it accesses INSTALLed. It's a huge pain, so don't unless
196 you know what you're doing)
197
198 5) Either define the symbol PERL somewhere, such as
199 SYS$MANAGER:SYLOGIN.COM, to be "PERL :== $PERL_ROOT:[000000]PERL.EXE", or
200 install Perl into DCLTABLES.EXE )Check out the section "Installing Perl
201 into DCLTABLES" for more info), or put the image in a directory that's in
202 your DCL$PATH (if you're using VMS 6.2 or higher).
203
204 6) Optionally define the command PERLDOC as 
205 PERLDOC :== $PERL_ROOT:[000000]PERL PERL_ROOT:[LIB.POD]PERLDOC.COM -T
206 Note that if you wish to use most as a pager please see
207 ftp://space.mit.edu/pub/davis/ for both most and slang.
208
209 7) Optionally define the command PERLBUG (the Perl bug report generator) as
210 PERLBUG :== $PERL_ROOT:[000000]PERL PERL_ROOT:[LIB]PERLBUG.COM"
211
212 8) Optionally define the command POD2MAN (Converts POD files to nroff
213 source suitable for converting to man pages. Also quiets complaints during
214 module builds) as
215
216 DEFINE/NOLOG POD2MAN PERL_ROOT:[LIB.POD]POD2MAN.COM
217 POD2MAN :== $PERL_ROOT:[000000]PERL POD2MAN
218
219 8) Optionally define the command POD2MAN (Converts POD files to nroff
220 source suitable for converting to man pages. Also quiets complaints during
221 module builds) as
222
223 DEFINE/NOLOG POD2MAN PERL_ROOT:[LIB.POD]POD2MAN.COM
224 POD2MAN :== $PERL_ROOT:[000000]PERL POD2MAN
225
226 * Installing Perl into DCLTABLES
227
228 Courtesy of Brad  Hughes:
229
230 Put the following, modified to reflect where your .exe is, in PERL.CLD:
231
232 define verb perl
233 image perl_root:[exe]perl.exe
234 cliflags (foreign)
235
236 and then
237
238 $ set command perl /table=sys$common:[syslib]dcltables.exe -
239  /output=sys$common:[syslib]dcltables.exe
240 $ install replace sys$common:[syslib]dcltables.exe
241
242 and you don't need perl :== $perl_root:[exe]perl.exe.
243
244 * Changing compile-time things
245
246 Most of the user-definable features of Perl are enabled or disabled in
247 [.VMS]CONFIG.VMS. There's code in there to Do The Right Thing, but that may
248 end up being the wrong thing for you. Make sure you understand what you're
249 doing, since changes here can get you a busted perl.
250
251 Odds are that there's nothing here to change, unless you're on a version of
252 VMS later than 6.2 and Dec C later than 5.6. Even if you are, the correct
253 values will still be chosen, most likely. Poking around here should be
254 unnecessary.
255
256 The one exception is the various *DIR install locations. Changing those
257 requires changes in genconfig.pl as well. Be really careful if you need to
258 change these,a s they can cause some fairly subtle problems.
259
260 * Extra things in the Perl distribution
261
262 In addition to the standard stuff that gets installed, there are two
263 optional extensions, DCLSYM and STDIO, that are handy. Instructions for
264 these two modules are in [.VMS.EXT.DCLSYM] and [.VMS.EXT.STDIO],
265 respectively.
266
267 * Socket Support
268
269 Perl includes a number of functions for IP sockets, which are available if
270 you choose to compile Perl with socket support. (See the section Compiling
271 Perl for more info on selecting a socket stack) Since IP networking is an
272 optional addition to VMS, there are several different IP stacks
273 available. How well integrated they are into the system depends on the
274 stack, your version of VMS, and the version of your C compiler.
275
276 The most portable solution uses the SOCKETSHR library. In combination with
277 either UCX or NetLib, this supports all the major TCP stacks (Multinet,
278 Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with
279 all the compilers on both VAX and Alpha. The socket interface is also
280 consistent across versions of VMS and C compilers. It has a problem with
281 UDP sockets when used with Multinet, though, so you should be aware of
282 that.
283
284 The other solution available is to use the socket routines built into Dec
285 C. Which routines are available depend on the version of VMS you're
286 running, and require proper UCX emulation by your TCP/IP vendor.
287 Relatively current versions of Multinet, TCPWare, Pathway, and UCX all
288 provide the required libraries--check your manuals or release notes to see
289 if your version is new enough.
290
291 * Reporting Bugs
292
293 If you come across what you think might be a bug in Perl, please report
294 it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through
295 the process of creating a bug report. This script includes details of your
296 installation, and is very handy. Completed bug reports should go to
297 PERLBUG@PERL.COM.
298
299 * Gotchas to watch out for
300
301 Probably the single biggest gotcha in compiling Perl is giving the wrong
302 switches to MMS/MMK when you build. If Perl's building oddly, double-check
303 your switches. If you're on a VAX, be sure to add a /Macro=("decc=1") if
304 you're using Dec C, and if you're on an alpha and using MMS, you'll need a
305 /Macro=("__AXP__=1")
306
307 The next big gotcha is directory depth. Perl can create directories four
308 and five levels deep during the build, so you don't have to be too deep to
309 start to hit the RMS 8 level point. It's best to do a
310 $DEFINE/TRANS=(CONC,TERM) PERLSRC disk:[dir.dir.dir.perldir.]"  (note the
311 trailing period) and $SET DEFAULT PERLSRC:[000000] before building. Perl
312 modules can be just as bad (or worse), so watch out for them, too.
313
314 Finally, the third thing that bites people is leftover pieces from a failed
315 build. If things go wrong, make sure you do a "(MMK|MMS|make) realclean"
316 before you rebuild.
317
318 * Dec C issues
319
320 Note to DECC users: Some early versions (pre-5.2, some pre-4. If you're Dec
321 C 5.x or higher, with current patches if anym you're fine) of the DECCRTL
322 contained a few bugs which affect Perl performance:
323     - Newlines are lost on I/O through pipes, causing lines to run together.
324       This shows up as RMS RTB errors when reading from a pipe.  You can
325       work around this by having one process write data to a file, and
326       then having the other read the file, instead of the pipe.  This is
327       fixed in version 4 of DECC.
328     - The modf() routine returns a non-integral value for some values above
329       INT_MAX; the Perl "int" operator will return a non-integral value in
330       these cases.  This is fixed in version 4 of DECC.
331     - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine
332       changes the process default device and directory permanently, even
333       though the call specified that the change should not persist after
334       Perl exited.  This is fixed by DEC CSC patch AXPACRT04_061.
335
336 * Mailing Lists
337
338 There are several mailing lists available to the Perl porter. For VMS
339 specific issues (including both Perl questions and installation problems)
340 there is the VMSPERL mailing list. It's usually a low-volume (10-12
341 messages a week) mailing list.
342
343 The subscription address is VMSPERL-REQUEST@NEWMAN.UPENN.EDU. Send a mail
344 message with just the words SUBSCRIBE VMSPERL in the body of the message.
345
346 The VMSPERL mailing list address is VMSPERL@NEWMAN.UPENN.EDU. Any mail
347 sent there gets echoed to all subscribers of the list.
348
349 The Perl5-Porters list is for anyone involved in porting Perl to a
350 platform. This includes you, if you want to participate. It's a high-volume
351 list (60-100 messages a day during active development times), so be sure
352 you want to be there. The subscription address is
353 Perl5-Porters-request@perl.org. Send a message with just the word SUBSCRIBE
354 in the body. The posting address is Perl5-Porters@perl.org.
355
356 * Acknowledgements
357
358 A real big thanks needs to go to Charles Bailey
359 <bailey@newman.upenn.edu>, who is ultimately responsible for Perl 5.004
360 running on VMS. Without him, nothing the rest of us have done would be at
361 all important.
362
363 There are, of course, far too many people involved in the porting and testing
364 of Perl to mention everyone who deserves it, so please forgive us if we've
365 missed someone.  That said, special thanks are due to the following:
366   Tim Adye <T.J.Adye@rl.ac.uk>
367      for the VMS emulations of getpw*()
368   David Denholm <denholm@conmat.phys.soton.ac.uk>
369      for extensive testing and provision of pipe and SocketShr code,
370   Mark Pizzolato <mark@infocomm.com>
371      for the getredirection() code
372   Rich Salz <rsalz@bbn.com>
373      for readdir() and related routines
374   Peter Prymmer <pvhp@lns62.lns.cornell.edu)
375      for extensive testing, as well as development work on
376      configuration and documentation for VMS Perl,
377   Dan Sugalski <sugalsd@stargate.lbcc.cc.or.us>
378      for extensive contributions to recent version support,
379      development of VMS-specific extensions, and dissemination
380      of information about VMS Perl,
381   the Stanford Synchrotron Radiation Laboratory and the
382      Laboratory of Nuclear Studies at Cornell University for
383      the the opportunity to test and develop for the AXP,
384 and to the entire VMSperl group for useful advice and suggestions.  In
385 addition the perl5-porters deserve credit for their creativity and
386 willingness to work with the VMS newcomers.  Finally, the greatest debt of
387 gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which
388 have made our sleepless nights possible.
389
390 Thanks,
391 The VMSperl group