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