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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
403 | then having the other read the file, instead of the pipe. This is |
404 | fixed in version 4 of DECC. | |
748a9306 LW |
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 LW |
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 LW |
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 LW |
421 | on your system. See the topic "Socket support" for more information. |
422 | ||
423 | * Socket support | |
424 | ||
748a9306 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
476 | Descrip.MMS - The MMS/MMK dependency file for building Perl |
477 | GenConfig.Pl - A Perl script to generate Config.SH retrospectively | |
a0d0e21e LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 AD |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
717 | Tim Adye <T.J.Adye@rl.ac.uk> |
718 | for the VMS emulations of getpw*() | |
a0d0e21e LW |
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 LW |
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 LW |
736 | have made our sleepless nights possible. |
737 | ||
738 | Thanks, | |
739 | The VMSperl group |