[win32] integrate mainline
[p5sagit/p5-mst-13.2.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
207 7) Optionally define the command PERLBUG (the Perl bug report generator) as
208 PERLBUG :== $PERL_ROOT:[000000]PERL PERL_ROOT:[LIB]PERLBUG.COM"
209
210 8) Optionally define the command POD2MAN (Converts POD files to nroff
211 source suitable for converting to man pages. Also quiets complaints during
212 module builds) as
213
214 DEFINE/NOLOG POD2MAN PERL_ROOT:[LIB.POD]POD2MAN.COM
215 POD2MAN :== $PERL_ROOT:[000000]PERL POD2MAN
216
217 * Installing Perl into DCLTABLES
218
219 Courtesy of Brad  Hughes:
220
221 Put the following, modified to reflect where your .exe is, in PERL.CLD:
222
223 define verb perl
224 image perl_root:[exe]perl.exe
225 cliflags (foreign)
226
227 and then
228
229 $ set command perl /table=sys$common:[syslib]dcltables.exe -
230  /output=sys$common:[syslib]dcltables.exe
231 $ install replace sys$common:[syslib]dcltables.exe
232
233 and you don't need perl :== $perl_root:[exe]perl.exe.
234
235 * Changing compile-time things
236
237 Most of the user-definable features of Perl are enabled or disabled in
238 [.VMS]CONFIG.VMS. There's code in there to Do The Right Thing, but that may
239 end up being the wrong thing for you. Make sure you understand what you're
240 doing, since changes here can get you a busted perl.
241
242 Odds are that there's nothing here to change, unless you're on a version of
243 VMS later than 6.2 and Dec C later than 5.6. Even if you are, the correct
244 values will still be chosen, most likely. Poking around here should be
245 unnecessary.
246
247 The one exception is the various *DIR install locations. Changing those
248 requires changes in genconfig.pl as well. Be really careful if you need to
249 change these,a s they can cause some fairly subtle problems.
250
251 * Extra things in the Perl distribution
252
253 In addition to the standard stuff that gets installed, there are two
254 optional extensions, DCLSYM and STDIO, that are handy. Instructions for
255 these two modules are in [.VMS.EXT.DCLSYM] and [.VMS.EXT.STDIO],
256 respectively.
257
258 * Socket Support
259
260 Perl includes a number of functions for IP sockets, which are available if
261 you choose to compile Perl with socket support. (See the section Compiling
262 Perl for more info on selecting a socket stack) Since IP networking is an
263 optional addition to VMS, there are several different IP stacks
264 available. How well integrated they are into the system depends on the
265 stack, your version of VMS, and the version of your C compiler.
266
267 The most portable solution uses the SOCKETSHR library. In combination with
268 either UCX or NetLib, this supports all the major TCP stacks (Multinet,
269 Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with
270 all the compilers on both VAX and Alpha. The socket interface is also
271 consistent across versions of VMS and C compilers. It has a problem with
272 UDP sockets when used with Multinet, though, so you should be aware of
273 that.
274
275 The other solution available is to use the socket routines built into Dec
276 C. Which routines are available depend on the version of VMS you're
277 running, and require proper UCX emulation by your TCP/IP vendor.
278 Relatively current versions of Multinet, TCPWare, Pathway, and UCX all
279 provide the required libraries--check your manuals or release notes to see
280 if your version is new enough.
281
282 * Reporting Bugs
283
284 If you come across what you think might be a bug in Perl, please report
285 it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through
286 the process of creating a bug report. This script includes details of your
287 installation, and is very handy. Completed bug reports should go to
288 PERLBUG@PERL.COM.
289
290 * Gotchas to watch out for
291
292 Probably the single biggest gotcha in compiling Perl is giving the wrong
293 switches to MMS/MMK when you build. If Perl's building oddly, double-check
294 your switches. If you're on a VAX, be sure to add a /Macro=("decc=1") if
295 you're using Dec C, and if you're on an alpha and using MMS, you'll need a
296 /Macro=("__AXP__=1")
297
298 The next big gotcha is directory depth. Perl can create directories four
299 and five levels deep during the build, so you don't have to be too deep to
300 start to hit the RMS 8 level point. It's best to do a
301 $DEFINE/TRANS=(CONC,TERM) PERLSRC disk:[dir.dir.dir.perldir.]"  (note the
302 trailing period) and $SET DEFAULT PERLSRC:[000000] before building. Perl
303 modules can be just as bad (or worse), so watch out for them, too.
304
305 Finally, the third thing that bites people is leftover pieces from a failed
306 build. If things go wrong, make sure you do a "(MMK|MMS|make) realclean"
307 before you rebuild.
308
309 * Dec C issues
310
311 Note to DECC users: Some early versions (pre-5.2, some pre-4. If you're Dec
312 C 5.x or higher, with current patches if anym you're fine) of the DECCRTL
313 contained a few bugs which affect Perl performance:
314     - Newlines are lost on I/O through pipes, causing lines to run together.
315       This shows up as RMS RTB errors when reading from a pipe.  You can
316       work around this by having one process write data to a file, and
317       then having the other read the file, instead of the pipe.  This is
318       fixed in version 4 of DECC.
319     - The modf() routine returns a non-integral value for some values above
320       INT_MAX; the Perl "int" operator will return a non-integral value in
321       these cases.  This is fixed in version 4 of DECC.
322     - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine
323       changes the process default device and directory permanently, even
324       though the call specified that the change should not persist after
325       Perl exited.  This is fixed by DEC CSC patch AXPACRT04_061.
326
327 * Mailing Lists
328
329 There are several mailing lists available to the Perl porter. For VMS
330 specific issues (including both Perl questions and installation problems)
331 there is the VMSPERL mailing list. It's usually a low-volume (10-12
332 messages a week) mailing list.
333
334 The subscription address is VMSPERL-REQUEST@NEWMAN.UPENN.EDU. Send a mail
335 message with just the words SUBSCRIBE VMSPERL in the body of the message.
336
337 The VMSPERL mailing list address is VMSPERL@NEWMAN.UPENN.EDU. Any mail
338 sent there gets echoed to all subscribers of the list.
339
340 The Perl5-Porters list is for anyone involved in porting Perl to a
341 platform. This includes you, if you want to participate. It's a high-volume
342 list (60-100 messages a day during active development times), so be sure
343 you want to be there. The subscription address is
344 Perl5-Porters-request@perl.org. Send a message with just the word SUBSCRIBE
345 in the body. The posting address is Perl5-Porters@perl.org.
346
347 * Acknowledgements
348
349 A real big thanks needs to go to Charles Bailey
350 <bailey@newman.upenn.edu>, who is ultimately responsible for Perl 5.004
351 running on VMS. Without him, nothing the rest of us have done would be at
352 all important.
353
354 There are, of course, far too many people involved in the porting and testing
355 of Perl to mention everyone who deserves it, so please forgive us if we've
356 missed someone.  That said, special thanks are due to the following:
357   Tim Adye <T.J.Adye@rl.ac.uk>
358      for the VMS emulations of getpw*()
359   David Denholm <denholm@conmat.phys.soton.ac.uk>
360      for extensive testing and provision of pipe and SocketShr code,
361   Mark Pizzolato <mark@infocomm.com>
362      for the getredirection() code
363   Rich Salz <rsalz@bbn.com>
364      for readdir() and related routines
365   Peter Prymmer <pvhp@lns62.lns.cornell.edu)
366      for extensive testing, as well as development work on
367      configuration and documentation for VMS Perl,
368   Dan Sugalski <sugalsd@stargate.lbcc.cc.or.us>
369      for extensive contributions to recent version support,
370      development of VMS-specific extensions, and dissemination
371      of information about VMS Perl,
372   the Stanford Synchrotron Radiation Laboratory and the
373      Laboratory of Nuclear Studies at Cornell University for
374      the the opportunity to test and develop for the AXP,
375 and to the entire VMSperl group for useful advice and suggestions.  In
376 addition the perl5-porters deserve credit for their creativity and
377 willingness to work with the VMS newcomers.  Finally, the greatest debt of
378 gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which
379 have made our sleepless nights possible.
380
381 Thanks,
382 The VMSperl group