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 | |
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 | |
c07a80fd |
381 | Last revised: 19-Jan-1996 by Charles Bailey bailey@genetics.upenn.edu |
a0d0e21e |
382 | |
748a9306 |
383 | The VMS port of Perl is still under development. At this time, the Perl |
a0d0e21e |
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 |
748a9306 |
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! |
a0d0e21e |
393 | |
394 | The current sources and build procedures have been tested on a VAX using VAXC |
c07a80fd |
395 | and DECC, and on an AXP using DECC. If you run into problems with other |
396 | compilers, please let us know. |
a0d0e21e |
397 | |
748a9306 |
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 |
4633a7c4 |
403 | then having the other read the file, instead of the pipe. This is |
404 | fixed in version 4 of DECC. |
748a9306 |
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 |
4633a7c4 |
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. |
a0d0e21e |
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 |
eacfb5f1 |
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 |
a0d0e21e |
421 | on your system. See the topic "Socket support" for more information. |
422 | |
423 | * Socket support |
424 | |
748a9306 |
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 |
a0d0e21e |
427 | IP networking is an optional addition to VMS, there are several different IP |
eacfb5f1 |
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. |
a0d0e21e |
430 | |
748a9306 |
431 | By default, Perl is built without IP socket support. If you define the macro |
c07a80fd |
432 | SOCKET when invoking MMK, however, socket support will be included. As |
748a9306 |
433 | distributed, Perl for VMS includes support for the SOCKETSHR socket library, |
a0d0e21e |
434 | which is layered on MadGoat software's vendor-independent NETLIB interface. |
748a9306 |
435 | This provides support for all socket calls used by Perl except the |
4633a7c4 |
436 | [g|s]etnet*() routines, which are replaced for the moment by stubs which |
748a9306 |
437 | generate a fatal error if a Perl script attempts to call one of these routines. |
eacfb5f1 |
438 | Both SOCKETSHR and NETLIB are available from MadGoat ftp sites, such as |
439 | ftp.spc.edu or ftp.wku.edu. |
440 | |
4633a7c4 |
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: |
a0d0e21e |
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 |
eacfb5f1 |
451 | includes the Socket.H, In.H, Inet.H, NetDb.H, and, if necessary, |
4633a7c4 |
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. |
a0d0e21e |
459 | - Edit the file SockAdapt.C in the [.VMS] subdirectory so that it |
460 | contains routines which substitute for any IP library routines |
748a9306 |
461 | required by Perl which your IP stack does not provide. This may |
a0d0e21e |
462 | require a little trial and error; we'll try to compile a complete |
748a9306 |
463 | list soon of socket routines required by Perl. |
a0d0e21e |
464 | |
4633a7c4 |
465 | |
748a9306 |
466 | * Building Perl under VMS |
a0d0e21e |
467 | |
748a9306 |
468 | Since you're reading this, presumably you've unpacked the Perl distribution |
a0d0e21e |
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 |
748a9306 |
472 | the VMS Makefile to alter directory paths as necessary. (I'd advise using the |
a0d0e21e |
473 | `normal' directory tree, at least for the first time through.) This |
474 | subdirectory contains several files, among which are the following: |
eacfb5f1 |
475 | Config.VMS - A template Config.H set up for VMS. |
748a9306 |
476 | Descrip.MMS - The MMS/MMK dependency file for building Perl |
477 | GenConfig.Pl - A Perl script to generate Config.SH retrospectively |
a0d0e21e |
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. |
748a9306 |
482 | Gen_ShrFls.Pl - A Perl script which generates linker options files and |
a0d0e21e |
483 | MACRO declarations for PerlShr.Exe. |
eacfb5f1 |
484 | Makefile - The make dependency file for building Perl |
748a9306 |
485 | MMS2Make.Pl - A Perl script used to generate Makefile from Descrip.MMS |
eacfb5f1 |
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 |
a0d0e21e |
491 | VMSish.H - C header file containing VMS-specific definitions |
492 | VMS.C - C source code for VMS-specific routines |
eacfb5f1 |
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 |
c07a80fd |
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.) |
a0d0e21e |
501 | |
748a9306 |
502 | Config.VMS and Decrip.MMS/Makefile are set up to build a version of Perl which |
a0d0e21e |
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 |
748a9306 |
506 | files. (Note: Do not use or edit config.h in the main Perl source directory; |
a0d0e21e |
507 | it is superseded by the current Config.VMS during the build.) You may also |
748a9306 |
508 | wish to make site-specific changes to Descrip.MMS or Makefile to reflect local |
a0d0e21e |
509 | conventions for naming of files, etc. |
510 | |
eacfb5f1 |
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. |
a0d0e21e |
523 | |
524 | Examine the information at the beginning of Descrip.MMS for information about |
748a9306 |
525 | specifying alternate C compilers or building a version of Perl with debugging |
a0d0e21e |
526 | support. For instance, if you want to use DECC, you'll need to include the |
c07a80fd |
527 | /macro="decc=1" qualifier to MMK (If you're using make, these options are not |
a0d0e21e |
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 | |
748a9306 |
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 |
a0d0e21e |
536 | $ MMS/Descrip=[.VMS] ! or MMK |
eacfb5f1 |
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 |
748a9306 |
540 | $ Make -f [.VMS]Makefile |
541 | Note that the Makefile doesn't support conditional compilation, is |
a0d0e21e |
542 | set up to use VAXC on a VAX, and does not include socket support. You can |
748a9306 |
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, |
a0d0e21e |
545 | found in the [.VMS] subdirectory, to generate a new Makefile with the options |
2114d1da |
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 |
c07a80fd |
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. |
a0d0e21e |
556 | |
a5f75d66 |
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 | |
a0d0e21e |
567 | |
568 | This will build the following files: |
569 | Miniperl.Exe - a stand-alone version of without any extensions. |
748a9306 |
570 | Miniperl has all the intrinsic capabilities of Perl, |
a0d0e21e |
571 | but cannot make use of the DynaLoader or any |
572 | extensions which use XS code. |
748a9306 |
573 | PerlShr.Exe - a shareable image containing most of Perl's internal |
a0d0e21e |
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. |
748a9306 |
577 | Perl.Exe - the main Perl executable image. It's contains the |
a0d0e21e |
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 |
748a9306 |
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. |
c07a80fd |
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. |
2114d1da |
596 | [.lib.pod]perldoc - A Perl program which locates and displays documentation |
c07a80fd |
597 | for Perl and its extensions. |
748a9306 |
598 | [.Lib]Config.pm - the Perl extension which saves configuration information |
599 | about Perl and your system. |
eacfb5f1 |
600 | [.Lib]DynaLoader.pm - The Perl extension which performs dynamic linking of |
a0d0e21e |
601 | shareable images for extensions. |
eacfb5f1 |
602 | Several subdirectories under [.Lib] containing preprocessed files or |
603 | site-specific files. |
a0d0e21e |
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 | |
c07a80fd |
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 | |
a0d0e21e |
632 | |
748a9306 |
633 | * Installing Perl once it's built |
a0d0e21e |
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 |
2114d1da |
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?]). |
eacfb5f1 |
642 | - Put Perl.Exe in a common directory, and make it world-executable. |
748a9306 |
643 | - Define a foreign command to invoke Perl, using a statement like |
a0d0e21e |
644 | $ Perl == "$dev:[dir]Perl.Exe" |
748a9306 |
645 | - Create a world-readable directory tree for Perl library modules, |
a0d0e21e |
646 | scripts, and what-have-you, and define PERL_ROOT as a rooted logical |
748a9306 |
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.) |
4633a7c4 |
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. |
748a9306 |
657 | - Most of the Perl documentation lives in the [.pod] subdirectory, and |
a0d0e21e |
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. |
c07a80fd |
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". |
eacfb5f1 |
666 | That's it. |
a0d0e21e |
667 | |
c07a80fd |
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. |
a0d0e21e |
672 | |
673 | * For more information |
674 | |
740ce14c |
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. |
a0d0e21e |
679 | |
748a9306 |
680 | If you're interested in up-to-date information on Perl development and |
a0d0e21e |
681 | internals, you might want to subscribe to the perl5-porters mailing list. You |
748a9306 |
682 | can do this by sending a message to perl5-porters-request@nicoh.com, containing |
a0d0e21e |
683 | the single line |
16d20bd9 |
684 | subscribe perl5-porters |
2114d1da |
685 | This is a high-volume list at the moment (>50 messages/day). |
a0d0e21e |
686 | |
4633a7c4 |
687 | If you're interested in ongoing information about the VMS port, you can |
740ce14c |
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 |
a0d0e21e |
692 | like to offer - you can send mail to bailey@genetics.upenn.edu or directly to |
740ce14c |
693 | the VMSPerl list at vmsperl@genetics.upenn.edu. |
a0d0e21e |
694 | |
4633a7c4 |
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 |
eacfb5f1 |
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. |
4633a7c4 |
706 | |
748a9306 |
707 | Good luck using Perl. Please let us know how it works for you - we can't |
a0d0e21e |
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 |
748a9306 |
715 | of Perl to mention everyone who deserves it, so please forgive us if we've |
a0d0e21e |
716 | missed someone. That said, special thanks are due to the following: |
748a9306 |
717 | Tim Adye <T.J.Adye@rl.ac.uk> |
718 | for the VMS emulations of getpw*() |
a0d0e21e |
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 |
740ce14c |
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, |
a0d0e21e |
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 |
740ce14c |
735 | gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which |
a0d0e21e |
736 | have made our sleepless nights possible. |
737 | |
738 | Thanks, |
739 | The VMSperl group |