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 | * Installing Perl into DCLTABLES |
---|
211 | |
---|
212 | Courtesy of Brad Hughes: |
---|
213 | |
---|
214 | Put the following, modified to reflect where your .exe is, in PERL.CLD: |
---|
215 | |
---|
216 | define verb perl |
---|
217 | image perl_root:[exe]perl.exe |
---|
218 | cliflags (foreign) |
---|
219 | |
---|
220 | and then |
---|
221 | |
---|
222 | $ set command perl /table=sys$common:[syslib]dcltables.exe - |
---|
223 | /output=sys$common:[syslib]dcltables.exe |
---|
224 | $ install replace sys$common:[syslib]dcltables.exe |
---|
225 | |
---|
226 | and you don't need perl :== $perl_root:[exe]perl.exe. |
---|
227 | |
---|
228 | * Changing compile-time things |
---|
229 | |
---|
230 | Most of the user-definable features of Perl are enabled or disabled in |
---|
231 | [.VMS]CONFIG.VMS. There's code in there to Do The Right Thing, but that may |
---|
232 | end up being the wrong thing for you. Make sure you understand what you're |
---|
233 | doing, since changes here can get you a busted perl. |
---|
234 | |
---|
235 | Odds are that there's nothing here to change, unless you're on a version of |
---|
236 | VMS later than 6.2 and Dec C later than 5.6. Even if you are, the correct |
---|
237 | values will still be chosen, most likely. Poking around here should be |
---|
238 | unnecessary. |
---|
239 | |
---|
240 | The one exception is the various *DIR install locations. Changing those |
---|
241 | requires changes in genconfig.pl as well. Be really careful if you need to |
---|
242 | change these,a s they can cause some fairly subtle problems. |
---|
243 | |
---|
244 | * Extra things in the Perl distribution |
---|
245 | |
---|
246 | In addition to the standard stuff that gets installed, there are two |
---|
247 | optional extensions, DCLSYM and STDIO, that are handy. Instructions for |
---|
248 | these two modules are in [.VMS.EXT.DCLSYM] and [.VMS.EXT.STDIO], |
---|
249 | respectively. |
---|
250 | |
---|
251 | * Socket Support |
---|
252 | |
---|
253 | Perl includes a number of functions for IP sockets, which are available if |
---|
254 | you choose to compile Perl with socket support. (See the section Compiling |
---|
255 | Perl for more info on selecting a socket stack) Since IP networking is an |
---|
256 | optional addition to VMS, there are several different IP stacks |
---|
257 | available. How well integrated they are into the system depends on the |
---|
258 | stack, your version of VMS, and the version of your C compiler. |
---|
259 | |
---|
260 | The most portable solution uses the SOCKETSHR library. In combination with |
---|
261 | either UCX or NetLib, this supports all the major TCP stacks (Multinet, |
---|
262 | Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with |
---|
263 | all the compilers on both VAX and Alpha. The socket interface is also |
---|
264 | consistent across versions of VMS and C compilers. It has a problem with |
---|
265 | UDP sockets when used with Multinet, though, so you should be aware of |
---|
266 | that. |
---|
267 | |
---|
268 | The other solution available is to use the socket routines built into Dec |
---|
269 | C. Which routines are available depend on the version of VMS you're |
---|
270 | running, and require proper UCX emulation by your TCP/IP vendor. |
---|
271 | Relatively current versions of Multinet, TCPWare, Pathway, and UCX all |
---|
272 | provide the required libraries--check your manuals or release notes to see |
---|
273 | if your version is new enough. |
---|
274 | |
---|
275 | * Reporting Bugs |
---|
276 | |
---|
277 | If you come across what you think might be a bug in Perl, please report |
---|
278 | it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through |
---|
279 | the process of creating a bug report. This script includes details of your |
---|
280 | installation, and is very handy. Completed bug reports should go to |
---|
281 | PERLBUG@PERL.COM. |
---|
282 | |
---|
283 | * Gotchas to watch out for |
---|
284 | |
---|
285 | Probably the single biggest gotcha in compiling Perl is giving the wrong |
---|
286 | switches to MMS/MMK when you build. If Perl's building oddly, double-check |
---|
287 | your switches. If you're on a VAX, be sure to add a /Macro=("decc=1") if |
---|
288 | you're using Dec C, and if you're on an alpha and using MMS, you'll need a |
---|
289 | /Macro=("__AXP__=1") |
---|
290 | |
---|
291 | The next big gotcha is directory depth. Perl can create directories four |
---|
292 | and five levels deep during the build, so you don't have to be too deep to |
---|
293 | start to hit the RMS 8 level point. It's best to do a |
---|
294 | $DEFINE/TRANS=(CONC,TERM) PERLSRC disk:[dir.dir.dir.perldir.]" (note the |
---|
295 | trailing period) and $SET DEFAULT PERLSRC:[000000] before building. Perl |
---|
296 | modules can be just as bad (or worse), so watch out for them, too. |
---|
297 | |
---|
298 | Finally, the third thing that bites people is leftover pieces from a failed |
---|
299 | build. If things go wrong, make sure you do a "(MMK|MMS|make) realclean" |
---|
300 | before you rebuild. |
---|
301 | |
---|
302 | * Dec C issues |
---|
303 | |
---|
304 | Note to DECC users: Some early versions (pre-5.2, some pre-4. If you're Dec |
---|
305 | C 5.x or higher, with current patches if anym you're fine) of the DECCRTL |
---|
306 | contained a few bugs which affect Perl performance: |
---|
307 | - Newlines are lost on I/O through pipes, causing lines to run together. |
---|
308 | This shows up as RMS RTB errors when reading from a pipe. You can |
---|
309 | work around this by having one process write data to a file, and |
---|
310 | then having the other read the file, instead of the pipe. This is |
---|
311 | fixed in version 4 of DECC. |
---|
312 | - The modf() routine returns a non-integral value for some values above |
---|
313 | INT_MAX; the Perl "int" operator will return a non-integral value in |
---|
314 | these cases. This is fixed in version 4 of DECC. |
---|
315 | - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine |
---|
316 | changes the process default device and directory permanently, even |
---|
317 | though the call specified that the change should not persist after |
---|
318 | Perl exited. This is fixed by DEC CSC patch AXPACRT04_061. |
---|
319 | |
---|
320 | * Mailing Lists |
---|
321 | |
---|
322 | There are several mailing lists available to the Perl porter. For VMS |
---|
323 | specific issues (including both Perl questions and installation problems) |
---|
324 | there is the VMSPERL mailing list. It's usually a low-volume (10-12 |
---|
325 | messages a week) mailing list. |
---|
326 | |
---|
327 | The subscription address is VMSPERL-REQUEST@NEWMAN.UPENN.EDU. Send a mail |
---|
328 | message with just the words SUBSCRIBE VMSPERL in the body of the message. |
---|
329 | |
---|
330 | The VMSPERL mailing list address is VMSPERL@NEWMAN.UPENN.EDU. Any mail |
---|
331 | sent there gets echoed to all subscribers of the list. |
---|
332 | |
---|
333 | The Perl5-Porters list is for anyone involved in porting Perl to a |
---|
334 | platform. This includes you, if you want to participate. It's a high-volume |
---|
335 | list (60-100 messages a day during active development times), so be sure |
---|
336 | you want to be there. The subscription address is |
---|
337 | Perl5-Porters-request@perl.org. Send a message with just the word SUBSCRIBE |
---|
338 | in the body. The posting address is Perl5-Porters@perl.org. |
---|
339 | |
---|
340 | * Acknowledgements |
---|
341 | |
---|
342 | A real big thanks needs to go to Charles Bailey |
---|
343 | <bailey@newman.upenn.edu>, who is ultimately responsible for Perl 5.004 |
---|
344 | running on VMS. Without him, nothing the rest of us have done would be at |
---|
345 | all important. |
---|
346 | |
---|
347 | There are, of course, far too many people involved in the porting and testing |
---|
348 | of Perl to mention everyone who deserves it, so please forgive us if we've |
---|
349 | missed someone. That said, special thanks are due to the following: |
---|
350 | Tim Adye <T.J.Adye@rl.ac.uk> |
---|
351 | for the VMS emulations of getpw*() |
---|
352 | David Denholm <denholm@conmat.phys.soton.ac.uk> |
---|
353 | for extensive testing and provision of pipe and SocketShr code, |
---|
354 | Mark Pizzolato <mark@infocomm.com> |
---|
355 | for the getredirection() code |
---|
356 | Rich Salz <rsalz@bbn.com> |
---|
357 | for readdir() and related routines |
---|
358 | Peter Prymmer <pvhp@lns62.lns.cornell.edu) |
---|
359 | for extensive testing, as well as development work on |
---|
360 | configuration and documentation for VMS Perl, |
---|
361 | Dan Sugalski <sugalsd@stargate.lbcc.cc.or.us> |
---|
362 | for extensive contributions to recent version support, |
---|
363 | development of VMS-specific extensions, and dissemination |
---|
364 | of information about VMS Perl, |
---|
365 | the Stanford Synchrotron Radiation Laboratory and the |
---|
366 | Laboratory of Nuclear Studies at Cornell University for |
---|
367 | the the opportunity to test and develop for the AXP, |
---|
368 | and to the entire VMSperl group for useful advice and suggestions. In |
---|
369 | addition the perl5-porters deserve credit for their creativity and |
---|
370 | willingness to work with the VMS newcomers. Finally, the greatest debt of |
---|
371 | gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which |
---|
372 | have made our sleepless nights possible. |
---|
373 | |
---|
374 | Thanks, |
---|
375 | The VMSperl group |
---|
376 | |
---|
377 | |
---|
378 | --------------------------------------------------------------------------- |
---|
379 | [Here's the pre-5.004_04 version of README.vms, for the record.] |
---|
380 | |
---|
381 | Last revised: 19-Jan-1996 by Charles Bailey bailey@genetics.upenn.edu |
---|
382 | |
---|
383 | The VMS port of Perl is still under development. At this time, the Perl |
---|
384 | binaries built under VMS handle internal operations properly, for the most |
---|
385 | part, as well as most of the system calls which have close equivalents under |
---|
386 | VMS. There are still some incompatibilities in process handling (e.g the |
---|
387 | fork/exec model for creating subprocesses doesn't do what you might expect |
---|
388 | under Unix), and there remain some file handling differences from Unix. Over |
---|
389 | the longer term, we'll try to get many of the useful VMS system services |
---|
390 | integrated as well, depending on time and people available. Of course, if |
---|
391 | you'd like to add something yourself, or join the porting team, we'd love to |
---|
392 | have you! |
---|
393 | |
---|
394 | The current sources and build procedures have been tested on a VAX using VAXC |
---|
395 | and DECC, and on an AXP using DECC. If you run into problems with other |
---|
396 | compilers, please let us know. |
---|
397 | |
---|
398 | Note to DECC users: Some early versions of the DECCRTL contained a few bugs |
---|
399 | which affect Perl performance: |
---|
400 | - Newlines are lost on I/O through pipes, causing lines to run together. |
---|
401 | This shows up as RMS RTB errors when reading from a pipe. You can |
---|
402 | work around this by having one process write data to a file, and |
---|
403 | then having the other read the file, instead of the pipe. This is |
---|
404 | fixed in version 4 of DECC. |
---|
405 | - The modf() routine returns a non-integral value for some values above |
---|
406 | INT_MAX; the Perl "int" operator will return a non-integral value in |
---|
407 | these cases. This is fixed in version 4 of DECC. |
---|
408 | - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine |
---|
409 | changes the process default device and directory permanently, even |
---|
410 | though the call specified that the change should not persist after |
---|
411 | Perl exited. This is fixed by DEC CSC patch AXPACRT04_061. |
---|
412 | |
---|
413 | * Other software required |
---|
414 | |
---|
415 | At the moment, in addition to basic VMS, you'll need two things: |
---|
416 | - a C compiler: VAXC, DECC, or gcc for the VAX; DECC for the AXP |
---|
417 | - a make tool: DEC's MMS (version 2.6 or later) or the free analog MMK |
---|
418 | (available from ftp.spc.edu), or a standard make utility (e.g. GNU make, |
---|
419 | also available from ftp.spc.edu). |
---|
420 | In addition, you may include socket support if you have an IP stack running |
---|
421 | on your system. See the topic "Socket support" for more information. |
---|
422 | |
---|
423 | * Socket support |
---|
424 | |
---|
425 | Perl includes a number of IP socket routines among its builtin functions, |
---|
426 | which are available if you choose to compile Perl with socket support. Since |
---|
427 | IP networking is an optional addition to VMS, there are several different IP |
---|
428 | stacks available, so it's difficult to automate the process of building Perl |
---|
429 | with socket support in a way which will work on all systems. |
---|
430 | |
---|
431 | By default, Perl is built without IP socket support. If you define the macro |
---|
432 | SOCKET when invoking MMK, however, socket support will be included. As |
---|
433 | distributed, Perl for VMS includes support for the SOCKETSHR socket library, |
---|
434 | which is layered on MadGoat software's vendor-independent NETLIB interface. |
---|
435 | This provides support for all socket calls used by Perl except the |
---|
436 | [g|s]etnet*() routines, which are replaced for the moment by stubs which |
---|
437 | generate a fatal error if a Perl script attempts to call one of these routines. |
---|
438 | Both SOCKETSHR and NETLIB are available from MadGoat ftp sites, such as |
---|
439 | ftp.spc.edu or ftp.wku.edu. |
---|
440 | |
---|
441 | You can link Perl directly to your TCP/IP stack's library, *as long as* it |
---|
442 | supplies shims for stdio routines which will properly handle both sockets and |
---|
443 | normal file descriptors. This is necessary because Perl does not distinguish |
---|
444 | between the two, and will try to make normal stdio calls such as read() and |
---|
445 | getc() on socket file descriptors. If you'd like to link Perl directly to |
---|
446 | your IP stack, then make the following changes: |
---|
447 | - In Descrip.MMS, locate the section beginning with .ifdef SOCKET, and |
---|
448 | change the SOCKLIB macro so that it translates to the filespec of your |
---|
449 | IP stack's socket library. This will be added to the RTL options file. |
---|
450 | - Edit the file SockAdapt.H in the [.VMS] subdirectory so that it |
---|
451 | includes the Socket.H, In.H, Inet.H, NetDb.H, and, if necessary, |
---|
452 | Errno.H header files for your IP stack, or so that it declares the |
---|
453 | standard TCP/IP constants and data structures appropriately. (See |
---|
454 | the distributed copy of SockAdapt.H for a collection of the structures |
---|
455 | needed by Perl itself, and [.ext.Socket]Socket.xs for a list of the |
---|
456 | constants used by the Socket extension, if you elect to built it.) |
---|
457 | You should also define any logical names necessary for your C compiler |
---|
458 | to find these files before invoking MM[KS] to build Perl. |
---|
459 | - Edit the file SockAdapt.C in the [.VMS] subdirectory so that it |
---|
460 | contains routines which substitute for any IP library routines |
---|
461 | required by Perl which your IP stack does not provide. This may |
---|
462 | require a little trial and error; we'll try to compile a complete |
---|
463 | list soon of socket routines required by Perl. |
---|
464 | |
---|
465 | |
---|
466 | * Building Perl under VMS |
---|
467 | |
---|
468 | Since you're reading this, presumably you've unpacked the Perl distribution |
---|
469 | into its directory tree, in which you will find a [.vms] subdirectory below |
---|
470 | the directory in which this file is found. If this isn't the case, then you'll |
---|
471 | need to unpack the distribution properly, or manually edit Descrip.MMS or |
---|
472 | the VMS Makefile to alter directory paths as necessary. (I'd advise using the |
---|
473 | `normal' directory tree, at least for the first time through.) This |
---|
474 | subdirectory contains several files, among which are the following: |
---|
475 | Config.VMS - A template Config.H set up for VMS. |
---|
476 | Descrip.MMS - The MMS/MMK dependency file for building Perl |
---|
477 | GenConfig.Pl - A Perl script to generate Config.SH retrospectively |
---|
478 | from Config.VMS, since the Configure shell script which |
---|
479 | normally generates Config.SH doesn't run under VMS. |
---|
480 | GenOpt.Com - A little DCL procedure used to write some linker options |
---|
481 | files, since not all make utilities can do this easily. |
---|
482 | Gen_ShrFls.Pl - A Perl script which generates linker options files and |
---|
483 | MACRO declarations for PerlShr.Exe. |
---|
484 | Makefile - The make dependency file for building Perl |
---|
485 | MMS2Make.Pl - A Perl script used to generate Makefile from Descrip.MMS |
---|
486 | PerlVMS.pod - Documentation for VMS-specific behavior of Perl |
---|
487 | Perly_[CH].VMS - Versions of the byacc output from Perl's grammar, |
---|
488 | modified to include VMS-specific C compiler options |
---|
489 | SockAdapt.[CH] - C source code used to integrate VMS TCP/IP support |
---|
490 | Test.Com - DCL driver for Perl regression tests |
---|
491 | VMSish.H - C header file containing VMS-specific definitions |
---|
492 | VMS.C - C source code for VMS-specific routines |
---|
493 | VMS_Yfix.Pl - Perl script to convert Perly.[CH] to Perly_[CH].VMS |
---|
494 | WriteMain.Pl - Perl script to generate Perlmain.C |
---|
495 | The [.Ext...] directories contain VMS-specific extensions distributed with |
---|
496 | Perl. There may also be other files in [.VMS...] pertaining to features under |
---|
497 | development; for the most part, you can ignore them. Note that packages in |
---|
498 | [.ext.*] are not built with Perl by default; you build the ones you want |
---|
499 | once the basic Perl build is complete (see the perlvms docs for instructions |
---|
500 | on building extensions.) |
---|
501 | |
---|
502 | Config.VMS and Decrip.MMS/Makefile are set up to build a version of Perl which |
---|
503 | includes all features known to work when this release was assembled. If you |
---|
504 | have code at your site which would support additional features (e.g. emulation |
---|
505 | of Unix system calls), feel free to make the appropriate changes to these |
---|
506 | files. (Note: Do not use or edit config.h in the main Perl source directory; |
---|
507 | it is superseded by the current Config.VMS during the build.) You may also |
---|
508 | wish to make site-specific changes to Descrip.MMS or Makefile to reflect local |
---|
509 | conventions for naming of files, etc. |
---|
510 | |
---|
511 | There are several pieces of system-specific information which become part of |
---|
512 | the Perl Config extension. Under VMS, the data for Config are generated by the |
---|
513 | script GenConfig.Pl in the [.VMS] subdirectory. It tries to ascertain the |
---|
514 | necessary information from various files, or from the system itself, and |
---|
515 | generally does the right thing. There is a list of hard-coded values at the |
---|
516 | end of this script which specifies items that are correct for most VMS systems, |
---|
517 | but may be incorrect for you, if your site is set up in an unusual fashion. If |
---|
518 | you're familiar with Perl's Config extension, feel free to edit these values as |
---|
519 | necessary. If this doesn't mean much to you, don't worry -- the information is |
---|
520 | probably correct, and even if it's not, none of these parameters affect your |
---|
521 | ability to build or run Perl. You'll only get the wrong answer if you ask for |
---|
522 | it specifically from Config. |
---|
523 | |
---|
524 | Examine the information at the beginning of Descrip.MMS for information about |
---|
525 | specifying alternate C compilers or building a version of Perl with debugging |
---|
526 | support. For instance, if you want to use DECC, you'll need to include the |
---|
527 | /macro="decc=1" qualifier to MMK (If you're using make, these options are not |
---|
528 | supported.) If you're on an AXP system, define the macro __AXP__ (MMK does |
---|
529 | this for you), and DECC will automatically be selected. |
---|
530 | |
---|
531 | To start the build, set default to the main source directory. Since |
---|
532 | Descrip.MMS assumes that VMS commands have their usual meaning, and makes use |
---|
533 | of command-line macros, you may want to be certain that you haven't defined DCL |
---|
534 | symbols which would interfere with the build. Then, if you are using MMS or |
---|
535 | MMK, say |
---|
536 | $ MMS/Descrip=[.VMS] ! or MMK |
---|
537 | (N.B. If you are using MMS, you must use version 2.6 or later; a bug in |
---|
538 | earlier versions produces malformed cc command lines.) If you are using a |
---|
539 | version of make, say |
---|
540 | $ Make -f [.VMS]Makefile |
---|
541 | Note that the Makefile doesn't support conditional compilation, is |
---|
542 | set up to use VAXC on a VAX, and does not include socket support. You can |
---|
543 | either edit the Makefile by hand, using Descrip.MMS as a guide, or use the |
---|
544 | Makefile to build Miniperl.Exe, and then run the Perl script MMS2Make.pl, |
---|
545 | found in the [.VMS] subdirectory, to generate a new Makefile with the options |
---|
546 | appropriate to your site. |
---|
547 | |
---|
548 | If you are using MM[SK], and you decide to rebuild Perl with a different set |
---|
549 | of parameters (e.g. changing the C compiler, or adding socket support), be |
---|
550 | sure to say |
---|
551 | $ MMK/Descrip=[.VMS] realclean |
---|
552 | first, in order to remove files generated during the previous build. If |
---|
553 | you omit this step, you risk ending up with a copy of Perl which |
---|
554 | composed partially of old files and partially of new ones, which may lead |
---|
555 | to strange effects when you try to run Perl. |
---|
556 | |
---|
557 | A bug in some early versions of the DECC RTL on the AXP causes newlines |
---|
558 | to be lost when writing to a pipe. A different bug in some patched versions |
---|
559 | of DECC 4.0 for VAX can also scramble preprocessor output. Finally, gcc 2.7.2 |
---|
560 | has yet another preprocessor bug, which causes line breaks to be inserted |
---|
561 | into the output at inopportune times. Each of these bugs causes Gen_ShrFls.pl |
---|
562 | to fail, since it can't parse the preprocessor output to identify global |
---|
563 | variables and routines. This problem is generally manifested as missing |
---|
564 | global symbols when linking PerlShr.Exe or Perl.Exe. You can work around |
---|
565 | it by defining the macro PIPES_BROKEN when you invoke MMS or MMK. |
---|
566 | |
---|
567 | |
---|
568 | This will build the following files: |
---|
569 | Miniperl.Exe - a stand-alone version of without any extensions. |
---|
570 | Miniperl has all the intrinsic capabilities of Perl, |
---|
571 | but cannot make use of the DynaLoader or any |
---|
572 | extensions which use XS code. |
---|
573 | PerlShr.Exe - a shareable image containing most of Perl's internal |
---|
574 | routines and global variables. Perl.Exe is linked to |
---|
575 | this image, as are all dynamic extensions, so everyone's |
---|
576 | using the same set of global variables and routines. |
---|
577 | Perl.Exe - the main Perl executable image. It's contains the |
---|
578 | main() routine, plus code for any statically linked |
---|
579 | extensions. |
---|
580 | PerlShr_Attr.Opt - A linker options file which specifies psect attributes |
---|
581 | matching those in PerlShr.Exe. It should be used when |
---|
582 | linking images against PerlShr.Exe |
---|
583 | PerlShr_Bld.Opt - A linker options file which specifies various things |
---|
584 | used to build PerlShr.Exe. It should be used when |
---|
585 | rebuilding PerlShr.Exe via MakeMaker-produced |
---|
586 | Descrip.MMS files for static extensions. |
---|
587 | c2ph - Perl program which generates template code to access |
---|
588 | C struct members from Perl. |
---|
589 | h2ph - Perl program which generates template code to access |
---|
590 | #defined constants in a C header file from Perl, |
---|
591 | using the "old-style" interface. (Largely supplanted |
---|
592 | by h2xs.) |
---|
593 | h2xs - Perl program which generates template files for creating |
---|
594 | XSUB extensions, optionally beginning with the #defined |
---|
595 | constants in a C header file. |
---|
596 | [.lib.pod]perldoc - A Perl program which locates and displays documentation |
---|
597 | for Perl and its extensions. |
---|
598 | [.Lib]Config.pm - the Perl extension which saves configuration information |
---|
599 | about Perl and your system. |
---|
600 | [.Lib]DynaLoader.pm - The Perl extension which performs dynamic linking of |
---|
601 | shareable images for extensions. |
---|
602 | Several subdirectories under [.Lib] containing preprocessed files or |
---|
603 | site-specific files. |
---|
604 | There are, of course, a number of other files created for use during the build. |
---|
605 | Once you've got the binaries built, you may wish to `build' the `tidy' or |
---|
606 | `clean' targets to remove extra files. |
---|
607 | |
---|
608 | If you run into problems during the build, you can get help from the VMSPerl |
---|
609 | or perl5-porters mailing lists (see below). When you report the problem, |
---|
610 | please include the following information: |
---|
611 | - The version of Perl you're trying to build. Please include any |
---|
612 | "letter" patchlevel, in addition to the version number. If the |
---|
613 | build successfully created Miniperl.Exe, you can check this by |
---|
614 | saying '$ MCR Sys$Disk:[]Miniperl -v'. Also, please mention |
---|
615 | where you obtained the distribution kit; in particular, note |
---|
616 | whether you were using a basic Perl kit or the VMS test kit |
---|
617 | (see below). |
---|
618 | - The exact command you issued to build Perl. |
---|
619 | - A copy of all error messages which were generated during the build. |
---|
620 | Please include enough of the build log to establish the context of |
---|
621 | the error messages. |
---|
622 | - A summary of your configuration. If the build progressed far enough |
---|
623 | to generate Miniperl.Exe and [.Lib]Config.pm, you can obtain this |
---|
624 | by saying '$ MCR Sys$Disk:[]Miniperl "-V"' (note the "" around -V). |
---|
625 | If not, then you can say '$ MMK/Descrip=[.VMS] printconfig' to |
---|
626 | produce the summary. |
---|
627 | This may sound like a lot of information to send, but it'll often make |
---|
628 | it easier for someone to spot the problem, instead of having to give |
---|
629 | a spectrum of possibilities. |
---|
630 | |
---|
631 | |
---|
632 | |
---|
633 | * Installing Perl once it's built |
---|
634 | |
---|
635 | Once the build is complete, you'll need to do the following: |
---|
636 | - Put PerlShr.Exe in a common directory, and make it world-readable. |
---|
637 | If you place it in a location other than Sys$Share, you'll need to |
---|
638 | define the logical name PerlShr to point to the image. (If you're |
---|
639 | installing on a VMScluster, be sure that each node is using the |
---|
640 | copy of PerlShr you expect [e.g. if you put PerlShr.Exe in Sys$Share, |
---|
641 | do they all share Sys$Share?]). |
---|
642 | - Put Perl.Exe in a common directory, and make it world-executable. |
---|
643 | - Define a foreign command to invoke Perl, using a statement like |
---|
644 | $ Perl == "$dev:[dir]Perl.Exe" |
---|
645 | - Create a world-readable directory tree for Perl library modules, |
---|
646 | scripts, and what-have-you, and define PERL_ROOT as a rooted logical |
---|
647 | name pointing to the top of this tree (i.e. if your Perl files were |
---|
648 | going to live in DKA1:[Util.Perl5...], then you should |
---|
649 | $ Define/Translation=Concealed Perl_Root DKA1:[Util.Perl5.] |
---|
650 | (Be careful to follow the rules for rooted logical names; in particular, |
---|
651 | remember that a rooted logical name cannot have as its device portion |
---|
652 | another rooted logical name - you've got to supply the actual device name |
---|
653 | and directory path to the root directory.) |
---|
654 | - Place the files from the [.lib...] directory tree in the distribution |
---|
655 | package into a [.lib...] directory tree off the root directory described |
---|
656 | above. |
---|
657 | - Most of the Perl documentation lives in the [.pod] subdirectory, and |
---|
658 | is written in a simple markup format which can be easily read. In this |
---|
659 | directory as well are pod2man and pod2html translators to reformat the |
---|
660 | docs for common display engines; a pod2hlp translator is under development. |
---|
661 | These files are copied to [.lib.pod] during the installation. |
---|
662 | - Define a foreign command to execute perldoc, such as |
---|
663 | $ Perldoc == "''Perl' Perl_Root:[lib.pod]Perldoc -t" |
---|
664 | This will allow users to retrieve documentation using Perldoc. For |
---|
665 | more details, say "perldoc perldoc". |
---|
666 | That's it. |
---|
667 | |
---|
668 | If you run into a bug in Perl, please submit a bug report. The PerlBug |
---|
669 | program, found in the [.lib] directory, will walk you through the process |
---|
670 | of assembling the necessary information into a bug report, and sending |
---|
671 | of to the Perl bug reporting address, perlbug@perl.com. |
---|
672 | |
---|
673 | * For more information |
---|
674 | |
---|
675 | If you're interested in more information on Perl in general, you may wish to |
---|
676 | consult the Usenet newsgroups comp.lang.perl.announce and comp.lang.perl.misc. |
---|
677 | The FAQ for these groups provides pointers to other online sources of |
---|
678 | information, as well as books describing Perl in depth. |
---|
679 | |
---|
680 | If you're interested in up-to-date information on Perl development and |
---|
681 | internals, you might want to subscribe to the perl5-porters mailing list. You |
---|
682 | can do this by sending a message to perl5-porters-request@nicoh.com, containing |
---|
683 | the single line |
---|
684 | subscribe perl5-porters |
---|
685 | This is a high-volume list at the moment (>50 messages/day). |
---|
686 | |
---|
687 | If you're interested in ongoing information about the VMS port, you can |
---|
688 | subscribe to the VMSPerl mailing list by sending a request to |
---|
689 | vmsperl-request@genetics.upenn.edu, containing the single line |
---|
690 | subscribe VMSPerl |
---|
691 | as the body of the message. And, as always, we welcome any help or code you'd |
---|
692 | like to offer - you can send mail to bailey@genetics.upenn.edu or directly to |
---|
693 | the VMSPerl list at vmsperl@genetics.upenn.edu. |
---|
694 | |
---|
695 | Finally, if you'd like to try out the latest changes to VMS Perl, you can |
---|
696 | retrieve a test distribution kit by anonymous ftp from genetics.upenn.edu, in |
---|
697 | the file [.perl5]perl5_ppp_yymmddx.zip, where "ppp" is the current Perl |
---|
698 | patchlevel, and "yymmddx" is a sequence number indicating the date that |
---|
699 | particular kit was assembled. In order to make retrieval convenient, this |
---|
700 | kit is also available by the name Perl5_VMSTest.Zip. These test kits contain |
---|
701 | "unofficial" patches from the perl5-porters group, test patches for important |
---|
702 | bugs, and VMS-specific fixes and improvements which have occurred since the |
---|
703 | last Perl release. Most of these changes will be incorporated in the next |
---|
704 | release of Perl, but until Larry Wall's looked at them and said they're OK, |
---|
705 | none of them should be considered official. |
---|
706 | |
---|
707 | Good luck using Perl. Please let us know how it works for you - we can't |
---|
708 | guarantee that we'll be able to fix bugs quickly, but we'll try, and we'd |
---|
709 | certainly like to know they're out there. |
---|
710 | |
---|
711 | |
---|
712 | * Acknowledgements |
---|
713 | |
---|
714 | There are, of course, far too many people involved in the porting and testing |
---|
715 | of Perl to mention everyone who deserves it, so please forgive us if we've |
---|
716 | missed someone. That said, special thanks are due to the following: |
---|
717 | Tim Adye <T.J.Adye@rl.ac.uk> |
---|
718 | for the VMS emulations of getpw*() |
---|
719 | David Denholm <denholm@conmat.phys.soton.ac.uk> |
---|
720 | for extensive testing and provision of pipe and SocketShr code, |
---|
721 | Mark Pizzolato <mark@infocomm.com> |
---|
722 | for the getredirection() code |
---|
723 | Rich Salz <rsalz@bbn.com> |
---|
724 | for readdir() and related routines |
---|
725 | Peter Prymmer <pvhp@lns62.lns.cornell.edu) |
---|
726 | for extensive testing, as well as development work on |
---|
727 | configuration and documentation for VMS Perl, |
---|
728 | the Stanford Synchrotron Radiation Laboratory and the |
---|
729 | Laboratory of Nuclear Studies at Cornell University for |
---|
730 | the the opportunity to test and develop for the AXP, |
---|
731 | and to the entire VMSperl group for useful advice and suggestions. In addition |
---|
732 | the perl5-porters, especially Andy Dougherty <doughera@lafcol.lafayette.edu> |
---|
733 | and Tim Bunce <Tim.Bunce@ig.co.uk>, deserve credit for their creativity and |
---|
734 | willingness to work with the VMS newcomers. Finally, the greatest debt of |
---|
735 | gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which |
---|
736 | have made our sleepless nights possible. |
---|
737 | |
---|
738 | Thanks, |
---|
739 | The VMSperl group |
---|