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