Commit | Line | Data |
---|---|---|
fb73857a | 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 | ||
01ca579e HM |
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 | ||
fb73857a | 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 |