Commit | Line | Data |
146174a9 |
1 | Last revised 27-October-1999 by Craig Berry <craig.berry@metamor.com> |
2 | Revised 01-March-1999 by Dan Sugalski <dan@sidhe.org> |
fb73857a |
3 | Originally by Charles Bailey <bailey@newman.upenn.edu> |
4 | |
97abc6ad |
5 | * Important safety tip |
6 | |
3a385817 |
7 | The build and install procedures have changed significantly from the 5.004 |
8 | releases! Make sure you read the "Building Perl" and "Installing Perl" |
146174a9 |
9 | sections of this document before you build or install. |
97abc6ad |
10 | |
3bf5f72b |
11 | Also note that, as of 5.005, an ANSI C compliant compiler is required to |
12 | build Perl. Vax C is *not* ANSI compliant, as it died a natural death some |
13 | time before the standard was set. Therefore Vax C will not compile perl |
14 | 5.005. Sorry about that. |
15 | |
16 | If you're stuck without Dec C (the Vax C license should be good for Dec C, |
17 | but the media charges might prohibit an upgrade), consider getting Gnu C |
18 | instead. |
19 | |
fb73857a |
20 | * Intro |
21 | |
22 | The VMS port of Perl is as functionally complete as any other Perl port |
23 | (and as complete as the ports on some Unix systems). The Perl binaries |
24 | provide all the Perl system calls that are either available under VMS or |
25 | reasonably emulated. There are some incompatibilites in process handling |
26 | (e.g the fork/exec model for creating subprocesses doesn't do what you |
27 | might expect under Unix), mainly because VMS and Unix handle processes and |
28 | sub-processes very differently. |
29 | |
30 | There are still some unimplemented system functions, and of coursse we |
31 | could use modules implementing useful VMS system services, so if you'd like |
32 | to lend a hand we'd love to have you. Join the Perl Porting Team Now! |
33 | |
34 | The current sources and build procedures have been tested on a VAX using |
9f3f8d50 |
35 | Dec C, and on an AXP using Dec C. If you run into problems with |
fb73857a |
36 | other compilers, please let us know. |
37 | |
38 | There are issues with varions versions of Dec C, so if you're not running a |
39 | relatively modern version, check the Dec C issues section later on in this |
40 | document. |
41 | |
42 | * Other required software |
43 | |
44 | In addition to VMS, you'll need: |
9f3f8d50 |
45 | 1) A C compiler. Dec C or gcc for AXP or the VAX. |
fb73857a |
46 | 2) A make tool. Dec's MMS (v2.6 or later), or MadGoat's free MMS |
47 | analog MMK (available from ftp.madgoat.com/madgoat) both work |
48 | just fine. Gnu Make might work, but it's been so long since |
49 | anyone's tested it that we're not sure. MMK's free, though, so |
50 | go ahead and use that. |
51 | |
9f3f8d50 |
52 | You may also want to have on hand: |
53 | 1) UNZIP.EXE for VMS available from a number of web/ftp sites. |
54 | http://www.cdrom.com/pub/infozip/UnZip.html |
55 | http://www.openvms.digital.com/cd/INFO-ZIP/ |
56 | ftp://ftp.digital.com/pub/VMS/ |
57 | ftp://ftp.openvms.digital.com/ |
58 | ftp://ftp.madgoat.com/madgoat/ |
59 | ftp://ftp.wku.edu/vms/ |
60 | 2) GUNZIP/GZIP.EXE for VMS available from a number of web/ftp sites. |
61 | http://www.fsf.org/order/ftp.html |
62 | ftp://ftp.uu.net/archive/systems/gnu/diffutils*.tar.gz |
63 | ftp://gatekeeper.dec.com/pub/GNU/diffutils*.tar.gz |
64 | ftp://ftp.gnu.org/pub/gnu/diffutils*.tar.gz |
65 | http://www.openvms.digital.com/cd/GZIP/ |
66 | ftp://ftp.digital.com/pub/VMS/ |
67 | 3) VMS TAR also available from a number of web/ftp sites. |
68 | ftp://ftp.lp.se/vms/ |
69 | http://www.openvms.digital.com/cd/VMSTAR/ |
70 | ftp://ftp.digital.com/pub/VMS/ |
71 | Please note that UNZIP and GUNZIP are not the same thing (they work with |
72 | different formats). Most of the useful files from CPAN (the Comprehensive |
73 | Perl Archive Network) are in .tar.gz format (this includes copies of the |
74 | source code for perl as well as modules and scripts that you may wish to |
75 | add later) hence you probably want to have GUNZIP.EXE and VMSTAR.EXE on |
76 | your VMS machine. |
fb73857a |
77 | |
78 | If you want to include socket support, you'll need a TCP stack and either |
79 | Dec C, or socket libraries. See the Socket Support topic for more details. |
80 | |
97abc6ad |
81 | * Building Perl |
fb73857a |
82 | |
97abc6ad |
83 | Building perl has two steps, configuration and compilation. |
fb73857a |
84 | |
97abc6ad |
85 | To configure perl (a necessary first step), issue the command |
fb73857a |
86 | |
146174a9 |
87 | @CONFIGURE |
fb73857a |
88 | |
97abc6ad |
89 | from the top of an unpacked perl directory. You'll be asked a series of |
90 | questions, and the answers to them (along with the capabilities of your C |
91 | compiler and network stack) will determine how perl's built. |
fb73857a |
92 | |
97abc6ad |
93 | If you've got multiple C compilers installed, you'll have your choice of |
3bf5f72b |
94 | which one to use. Various older versions of Dec C had some gotchas, so if |
95 | you're using a version older than 5.2, check the Dec C Issues section. |
fb73857a |
96 | |
97abc6ad |
97 | The configuration script will print out, at the very end, the MMS or MMK |
98 | command you need to compile perl. Issue it (exactly as printed) to start |
146174a9 |
99 | the build. If you have any symbols or logical names in your environment |
100 | that may interfere with the build or regression testing of perl then |
101 | configure.com will try to warn you about them. If a logical name is causing |
102 | you trouble but is in an LNM table that you do not have write access to |
103 | then try defining your own to a harmless equivalence string in a table |
104 | such that it is resolved before the other (e.g. if TMP is defined in the |
105 | SYSTEM table then try DEFINE TMP "NL:" or somesuch) otherwise simply deasign |
106 | the dangerous logical names. The potentially troublesome logicals and |
107 | symbols are: |
108 | |
109 | TMP "LOGICAL" |
110 | LIB "LOGICAL" |
111 | T "LOGICAL" |
112 | FOO "LOGICAL" |
113 | EXT "LOGICAL" |
114 | TEST "SYMBOL" |
fb73857a |
115 | |
116 | Once you issue your MMS command, sit back and wait. Perl should build and |
117 | link without a problem. If it doesn't, check the Gotchas to watch out for |
118 | section. If that doesn't help, send some mail to the VMSPERL mailing list. |
119 | Instructions are in the Mailing Lists section. |
120 | |
97abc6ad |
121 | As a handy shortcut, the command: |
122 | |
146174a9 |
123 | @CONFIGURE "-des" |
97abc6ad |
124 | |
9f3f8d50 |
125 | (note the quotation marks and case) will choose reasonable defaults. (It |
126 | takes Dec C over Gnu C, Dec C sockets over SOCKETSHR sockets, and either |
127 | over no sockets) |
97abc6ad |
128 | |
fb73857a |
129 | * Testing Perl |
130 | |
131 | Once Perl has built cleanly, you need to test it to make sure things work. |
132 | This step is very important--there are always things that can go wrong |
133 | somehow and get you a dysfunctional Perl. |
134 | |
135 | Testing is very easy, though, as there's a full test suite in the perl |
136 | distribution. To run the tests, enter the *exact* MMS line you used to |
137 | compile Perl and add the word "test" to the end, like this: |
138 | |
139 | Compile Command: |
140 | |
7d4ba924 |
141 | $MMS |
fb73857a |
142 | |
143 | Test Command: |
144 | |
7d4ba924 |
145 | $MMS test |
fb73857a |
146 | |
147 | MMS will run all the tests. This may take some time, as there are a lot of |
148 | tests. If any tests fail, there will be a note made on-screen. At the end |
149 | of all the tests, a summary of the tests, the number passed and failed, and |
150 | the time taken will be displayed. |
151 | |
152 | If any tests fail, it means something's wrong with Perl. If the test suite |
153 | hangs (some tests can take upwards of two or three minutes, or more if |
9f3f8d50 |
154 | you're on an especially slow machine, depending on your machine speed, so |
fb73857a |
155 | don't be hasty), then the test *after* the last one displayed failed. Don't |
156 | install Perl unless you're confident that you're OK. Regardless of how |
157 | confident you are, make a bug report to the VMSPerl mailing list. |
158 | |
159 | If one or more tests fail, you can get more info on the failure by issuing |
160 | this command sequence: |
161 | |
146174a9 |
162 | $ @[.VMS]TEST .typ "" "-v" [.subdir]test.T |
fb73857a |
163 | |
164 | where ".typ" is the file type of the Perl images you just built (if you |
165 | didn't do anything special, use .EXE), and "[.subdir]test.T" is the test |
166 | that failed. For example, with a normal Perl build, if the test indicated |
167 | that [.op]time failed, then you'd do this: |
168 | |
146174a9 |
169 | $ @[.VMS]TEST .EXE "" "-v" [.OP]TIME.T |
fb73857a |
170 | |
171 | When you send in a bug report for failed tests, please include the output |
172 | from this command, which is run from the main source directory: |
173 | |
174 | MCR []MINIPERL "-V" |
175 | |
176 | Note that "-V" really is a capital V in double quotes. This will dump out a |
177 | couple of screens worth of config info, and can help us diagnose the problem. |
9f3f8d50 |
178 | If (and only if) that did not work then try enclosing the output of: |
179 | |
180 | @[.vms]myconfig |
fb73857a |
181 | |
182 | * Cleaning up and starting fresh |
183 | |
184 | If you need to recompile from scratch, you have to make sure you clean up |
185 | first. There's a procedure to do it--enter the *exact* MMS line you used to |
186 | compile and add "realclean" at the end, like this: |
187 | |
188 | Compile Command: |
189 | |
7d4ba924 |
190 | $MMS |
fb73857a |
191 | |
192 | Cleanup Command: |
193 | |
7d4ba924 |
194 | $MMS realclean |
fb73857a |
195 | |
196 | If you don't do this, things may behave erratically. They might not, too, |
197 | so it's best to be sure and do it. |
198 | |
199 | * Installing Perl |
200 | |
201 | There are several steps you need to take to get Perl installed and |
3a385817 |
202 | running. |
fb73857a |
203 | |
204 | 1) Create a directory somewhere and define the concealed logical PERL_ROOT |
205 | to point to it. For example, DEFINE/TRANS=(CONC,TERM) PERL_ROOT dka200:[perl.] |
206 | |
3a385817 |
207 | 2) Run the install script via: |
fb73857a |
208 | |
3a385817 |
209 | MMS install |
fb73857a |
210 | |
3a385817 |
211 | or |
fb73857a |
212 | |
3a385817 |
213 | MMK install |
214 | |
215 | If for some reason it complains about target INSTALL being up to date, |
216 | throw a /FORCE switch on the MMS or MMK command. |
217 | |
9f3f8d50 |
218 | The script [.VMS]PERL_SETUP.COM that is written by CONFIGURE.COM |
219 | will take care of most of the following: |
220 | |
3a385817 |
221 | 3) Either define the symbol PERL somewhere, such as |
fb73857a |
222 | SYS$MANAGER:SYLOGIN.COM, to be "PERL :== $PERL_ROOT:[000000]PERL.EXE", or |
3a385817 |
223 | install Perl into DCLTABLES.EXE (Check out the section "Installing Perl |
fb73857a |
224 | into DCLTABLES" for more info), or put the image in a directory that's in |
225 | your DCL$PATH (if you're using VMS 6.2 or higher). |
226 | |
9f3f8d50 |
227 | 4) Either define the logical name PERLSHR somewhere |
228 | (such as in PERL_SETUP.COM) like so: |
229 | DEFINE/NOLOG PERLSHR PERL_ROOT:[000000]PERLSHR.EXE |
230 | or copy perl_root:[000000]perlshr.exe sys$share:. |
231 | |
232 | 5) Optionally define the command PERLDOC as |
bd3fa61c |
233 | PERLDOC == "$PERL_ROOT:[000000]PERL PERL_ROOT:[LIB.POD]PERLDOC.COM -t" |
491527d0 |
234 | Note that if you wish to use most as a pager please see |
9f3f8d50 |
235 | ftp://space.mit.edu/pub/davis/ for both most and slang (or perhaps |
236 | ftp://ftp.wku.edu/vms/narnia/most.zip ). |
fb73857a |
237 | |
9f3f8d50 |
238 | 6) Optionally define the command PERLBUG (the Perl bug report generator) as |
bd3fa61c |
239 | PERLBUG == "$PERL_ROOT:[000000]PERL PERL_ROOT:[LIB]PERLBUG.COM" |
fb73857a |
240 | |
9f3f8d50 |
241 | 7) Optionally define the command POD2MAN (Converts POD files to nroff |
491527d0 |
242 | source suitable for converting to man pages. Also quiets complaints during |
243 | module builds) as |
244 | |
245 | DEFINE/NOLOG POD2MAN PERL_ROOT:[LIB.POD]POD2MAN.COM |
bd3fa61c |
246 | POD2MAN == "$PERL_ROOT:[000000]PERL POD2MAN" |
85988417 |
247 | |
9f3f8d50 |
248 | 8) Optionally define the command POD2TEXT (Converts POD files to text, |
85988417 |
249 | which is required for perldoc -f to work properly) as |
250 | |
251 | DEFINE/NOLOG POD2TEXT PERL_ROOT:[LIB.POD]POD2TEXT.COM |
bd3fa61c |
252 | POD2TEXT == "$PERL_ROOT:[000000]PERL POD2TEXT" |
85988417 |
253 | |
254 | In all these cases, if you've got PERL defined as a foreign command, you |
255 | can replace $PERL_ROOT:[000000]PERL with ''perl'. If you've installed perl |
256 | into DCLTABLES, replace it with just perl. |
491527d0 |
257 | |
fb73857a |
258 | * Installing Perl into DCLTABLES |
259 | |
9ef4b0a6 |
260 | Execute the following command file to define PERL as a DCL command. |
261 | You'll need CMKRNL priv to install the new dcltables.exe. |
fb73857a |
262 | |
146174a9 |
263 | $ create perl.cld |
264 | ! |
265 | ! modify to reflect location of your perl.exe |
266 | ! |
267 | define verb perl |
268 | image perl_root:[000000]perl.exe |
269 | cliflags (foreign) |
270 | $! |
271 | $ set command perl /table=sys$common:[syslib]dcltables.exe - |
272 | /output=sys$common:[syslib]dcltables.exe |
273 | $ install replace sys$common:[syslib]dcltables.exe |
274 | $ exit |
fb73857a |
275 | |
276 | * Changing compile-time things |
277 | |
278 | Most of the user-definable features of Perl are enabled or disabled in |
279 | [.VMS]CONFIG.VMS. There's code in there to Do The Right Thing, but that may |
280 | end up being the wrong thing for you. Make sure you understand what you're |
281 | doing, since changes here can get you a busted perl. |
282 | |
283 | Odds are that there's nothing here to change, unless you're on a version of |
284 | VMS later than 6.2 and Dec C later than 5.6. Even if you are, the correct |
285 | values will still be chosen, most likely. Poking around here should be |
286 | unnecessary. |
287 | |
288 | The one exception is the various *DIR install locations. Changing those |
289 | requires changes in genconfig.pl as well. Be really careful if you need to |
9f3f8d50 |
290 | change these, as they can cause some fairly subtle problems. |
291 | |
292 | * INSTALLing images |
293 | |
294 | On systems that are using perl quite a bit, and particularly those with |
295 | minimal RAM, you can boost the performance of perl by INSTALLing it as |
146174a9 |
296 | a known image. PERLSHR.EXE is typically larger than 2000 blocks |
9f3f8d50 |
297 | and that is a reasonably large amount of IO to load each time perl is |
298 | invoked. |
299 | |
300 | INSTALL ADD PERLSHR/SHARE |
301 | |
302 | should be enough for PERLSHR.EXE (/share implies /header and /open), |
303 | while /HEADER should do for PERL.EXE (perl.exe is not a shared image). |
304 | |
305 | If your code 'use's modules, check to see if there's an executable for |
306 | them, too. In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File, |
307 | DCLsym, and Stdio all have shared images that can be installed /SHARE. |
308 | |
309 | How much of a win depends on your memory situation, but if you're firing |
310 | off perl with any regularity (like more than once every 20 seconds or so) |
311 | it's probably a win. |
312 | |
313 | While there is code in perl to remove privileges as it runs you are advised |
314 | to NOT INSTALL PERL.EXE with PRIVs! |
fb73857a |
315 | |
316 | * Extra things in the Perl distribution |
317 | |
318 | In addition to the standard stuff that gets installed, there are two |
319 | optional extensions, DCLSYM and STDIO, that are handy. Instructions for |
320 | these two modules are in [.VMS.EXT.DCLSYM] and [.VMS.EXT.STDIO], |
9f3f8d50 |
321 | respectively. They are built automatically for versions of perl >= 5.005. |
fb73857a |
322 | |
323 | * Socket Support |
324 | |
325 | Perl includes a number of functions for IP sockets, which are available if |
9f3f8d50 |
326 | you choose to compile Perl with socket support (see the section Compiling |
327 | Perl for more info on selecting a socket stack). Since IP networking is an |
fb73857a |
328 | optional addition to VMS, there are several different IP stacks |
329 | available. How well integrated they are into the system depends on the |
330 | stack, your version of VMS, and the version of your C compiler. |
331 | |
332 | The most portable solution uses the SOCKETSHR library. In combination with |
333 | either UCX or NetLib, this supports all the major TCP stacks (Multinet, |
334 | Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with |
335 | all the compilers on both VAX and Alpha. The socket interface is also |
336 | consistent across versions of VMS and C compilers. It has a problem with |
337 | UDP sockets when used with Multinet, though, so you should be aware of |
338 | that. |
339 | |
340 | The other solution available is to use the socket routines built into Dec |
341 | C. Which routines are available depend on the version of VMS you're |
342 | running, and require proper UCX emulation by your TCP/IP vendor. |
343 | Relatively current versions of Multinet, TCPWare, Pathway, and UCX all |
344 | provide the required libraries--check your manuals or release notes to see |
345 | if your version is new enough. |
346 | |
347 | * Reporting Bugs |
348 | |
349 | If you come across what you think might be a bug in Perl, please report |
350 | it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through |
351 | the process of creating a bug report. This script includes details of your |
352 | installation, and is very handy. Completed bug reports should go to |
9f3f8d50 |
353 | perlbug@perl.com. |
fb73857a |
354 | |
355 | * Gotchas to watch out for |
356 | |
357 | Probably the single biggest gotcha in compiling Perl is giving the wrong |
97abc6ad |
358 | switches to MMS/MMK when you build. Use *exactly* what the configure script |
359 | prints! |
fb73857a |
360 | |
361 | The next big gotcha is directory depth. Perl can create directories four |
362 | and five levels deep during the build, so you don't have to be too deep to |
363 | start to hit the RMS 8 level point. It's best to do a |
364 | $DEFINE/TRANS=(CONC,TERM) PERLSRC disk:[dir.dir.dir.perldir.]" (note the |
365 | trailing period) and $SET DEFAULT PERLSRC:[000000] before building. Perl |
97abc6ad |
366 | modules can be just as bad (or worse), so watch out for them, too. The |
9f3f8d50 |
367 | configuration script will warn if it thinks you're too deep (at least on |
368 | versions of VMS prior to 7.2). |
fb73857a |
369 | |
370 | Finally, the third thing that bites people is leftover pieces from a failed |
371 | build. If things go wrong, make sure you do a "(MMK|MMS|make) realclean" |
372 | before you rebuild. |
373 | |
374 | * Dec C issues |
375 | |
376 | Note to DECC users: Some early versions (pre-5.2, some pre-4. If you're Dec |
146174a9 |
377 | C 5.x or higher, with current patches if any, you're fine) of the DECCRTL |
fb73857a |
378 | contained a few bugs which affect Perl performance: |
379 | - Newlines are lost on I/O through pipes, causing lines to run together. |
380 | This shows up as RMS RTB errors when reading from a pipe. You can |
381 | work around this by having one process write data to a file, and |
382 | then having the other read the file, instead of the pipe. This is |
383 | fixed in version 4 of DECC. |
384 | - The modf() routine returns a non-integral value for some values above |
385 | INT_MAX; the Perl "int" operator will return a non-integral value in |
386 | these cases. This is fixed in version 4 of DECC. |
387 | - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine |
388 | changes the process default device and directory permanently, even |
389 | though the call specified that the change should not persist after |
390 | Perl exited. This is fixed by DEC CSC patch AXPACRT04_061. |
391 | |
392 | * Mailing Lists |
393 | |
394 | There are several mailing lists available to the Perl porter. For VMS |
395 | specific issues (including both Perl questions and installation problems) |
396 | there is the VMSPERL mailing list. It's usually a low-volume (10-12 |
397 | messages a week) mailing list. |
398 | |
146174a9 |
399 | The subscription address is MAJORDOMO@PERL.ORG. Send a mail message with just |
400 | the words SUBSCRIBE VMSPERL in the body of the message. |
401 | |
402 | The VMSPERL mailing list address is VMSPERL@PERL.ORG. Any mail sent there |
403 | gets echoed to all subscribers of the list. There is a searchable archive of |
404 | the list at <http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/>. |
405 | |
9f3f8d50 |
406 | To unsubscribe from VMSPERL send the message UNSUBSCRIBE VMSPERL to |
146174a9 |
407 | MAJORDOMO@PERL.ORG. Be sure to do so from the subscribed account that |
408 | you are cancelling. |
fb73857a |
409 | |
410 | * Acknowledgements |
411 | |
412 | A real big thanks needs to go to Charles Bailey |
413 | <bailey@newman.upenn.edu>, who is ultimately responsible for Perl 5.004 |
414 | running on VMS. Without him, nothing the rest of us have done would be at |
415 | all important. |
416 | |
417 | There are, of course, far too many people involved in the porting and testing |
418 | of Perl to mention everyone who deserves it, so please forgive us if we've |
419 | missed someone. That said, special thanks are due to the following: |
420 | Tim Adye <T.J.Adye@rl.ac.uk> |
421 | for the VMS emulations of getpw*() |
422 | David Denholm <denholm@conmat.phys.soton.ac.uk> |
423 | for extensive testing and provision of pipe and SocketShr code, |
424 | Mark Pizzolato <mark@infocomm.com> |
425 | for the getredirection() code |
426 | Rich Salz <rsalz@bbn.com> |
427 | for readdir() and related routines |
146174a9 |
428 | Peter Prymmer <pvhp@forte.com> |
fb73857a |
429 | for extensive testing, as well as development work on |
430 | configuration and documentation for VMS Perl, |
146174a9 |
431 | Dan Sugalski <dan@sidhe.org> |
fb73857a |
432 | for extensive contributions to recent version support, |
433 | development of VMS-specific extensions, and dissemination |
434 | of information about VMS Perl, |
435 | the Stanford Synchrotron Radiation Laboratory and the |
436 | Laboratory of Nuclear Studies at Cornell University for |
9f3f8d50 |
437 | the opportunity to test and develop for the AXP, |
fb73857a |
438 | and to the entire VMSperl group for useful advice and suggestions. In |
439 | addition the perl5-porters deserve credit for their creativity and |
440 | willingness to work with the VMS newcomers. Finally, the greatest debt of |
441 | gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which |
442 | have made our sleepless nights possible. |
443 | |
444 | Thanks, |
445 | The VMSperl group |