Commit | Line | Data |
b4bc034f |
1 | If you read this file _as_is_, just ignore the equal signs on the left. |
2 | This file is written in the POD format (see [.POD]PERLPOD.POD;1) which is |
3 | specially designed to be readable as is. |
fb73857a |
4 | |
b4bc034f |
5 | =head1 NAME |
6 | |
7 | README.vms - Configuring, building, testing, and installing perl on VMS |
8 | |
9 | =head1 SYNOPSIS |
10 | |
11 | To configure, build, test, and install perl on VMS: |
12 | |
13 | @ Configure |
14 | mms |
15 | mms test |
16 | mms install |
17 | |
18 | mmk may be used in place of mms in the last three steps. |
19 | |
20 | =head1 DESCRIPTION |
21 | |
22 | =head2 Important safety tip |
97abc6ad |
23 | |
ec55d5e4 |
24 | For best results, make sure you read the "Configuring the Perl Build", |
25 | "Building Perl", and "Installing Perl" sections of this document before |
26 | you build or install. Also please note other changes in the current |
27 | release by having a look at L<perldelta/VMS>. |
97abc6ad |
28 | |
b4bc034f |
29 | Also note that, as of Perl version 5.005 and later, an ANSI C compliant |
30 | compiler is required to build Perl. VAX C is *not* ANSI compliant, as it |
31 | died a natural death some time before the standard was set. Therefore |
1bc81404 |
32 | VAX C will not compile Perl 5.005 or later. We are sorry about that. |
3bf5f72b |
33 | |
10019e56 |
34 | There have been no recent reports of builds using Gnu C, but latent |
35 | (and most likely outdated) support for it is still present in various |
36 | parts of the sources. Currently the HP (formerly Compaq, and even |
37 | more formerly DEC) C compiler is the only viable alternative for |
38 | building Perl. |
39 | |
40 | There is minimal support for HP C++ but this support is not complete; |
e7948fac |
41 | if you get it working please write to the vmsperl list (for info see |
42 | L</"Mailing Lists">). |
3bf5f72b |
43 | |
b4bc034f |
44 | |
a83b6f46 |
45 | =head2 Introduction to Perl on VMS |
fb73857a |
46 | |
47 | The VMS port of Perl is as functionally complete as any other Perl port |
48 | (and as complete as the ports on some Unix systems). The Perl binaries |
49 | provide all the Perl system calls that are either available under VMS or |
b4bc034f |
50 | reasonably emulated. There are some incompatibilities in process handling |
51 | (e.g. the fork/exec model for creating subprocesses doesn't do what you |
fb73857a |
52 | might expect under Unix), mainly because VMS and Unix handle processes and |
53 | sub-processes very differently. |
54 | |
b4bc034f |
55 | There are still some unimplemented system functions, and of course we |
fb73857a |
56 | could use modules implementing useful VMS system services, so if you'd like |
b4bc034f |
57 | to lend a hand we'd love to have you. Join the Perl Porting Team Now! |
fb73857a |
58 | |
b4bc034f |
59 | There are issues with various versions of DEC C, so if you're not running a |
60 | relatively modern version, check the "DEC C issues" section later on in this |
fb73857a |
61 | document. |
62 | |
a83b6f46 |
63 | =head2 Other required software for Compiling Perl on VMS |
b4bc034f |
64 | |
65 | In addition to VMS and DCL you will need two things: |
fb73857a |
66 | |
b4bc034f |
67 | =over 4 |
68 | |
69 | =item 1 A C compiler. |
70 | |
10019e56 |
71 | HP (formerly Compaq, more formerly DEC) C for VMS (VAX, Alpha, or Itanium). |
b4bc034f |
72 | |
73 | =item 2 A make tool. |
74 | |
ec55d5e4 |
75 | HP's MMS may work, but MadGoat's free MMS analog MMK (available from |
76 | http://www.kednos.com/kednos/Resources/MMK) has consistently worked |
77 | better. Gnu Make might work, but it's been so long since anyone's tested |
78 | it that we're not sure. MMK is free though, so go ahead and use that. |
b4bc034f |
79 | |
80 | =back |
81 | |
a83b6f46 |
82 | =head2 Additional software that is optional for Perl on VMS |
fb73857a |
83 | |
9f3f8d50 |
84 | You may also want to have on hand: |
b4bc034f |
85 | |
86 | =over 4 |
87 | |
88 | =item 1 GUNZIP/GZIP.EXE for VMS |
89 | |
90 | A de-compressor for *.gz and *.tgz files available from a number |
58979ab1 |
91 | of web/ftp sites and is distributed on the OpenVMS Freeware CD-ROM |
10019e56 |
92 | from HP. |
b4bc034f |
93 | |
10019e56 |
94 | http://www.hp.com/go/openvms/freeware/ |
b4bc034f |
95 | |
96 | =item 2 VMS TAR |
97 | |
98 | For reading and writing unix tape archives (*.tar files). Vmstar is also |
58979ab1 |
99 | available from a number of web/ftp sites and is distributed on the OpenVMS |
10019e56 |
100 | Freeware CD-ROM from HP. |
b4bc034f |
101 | |
10019e56 |
102 | http://www.hp.com/go/openvms/freeware/ |
b4bc034f |
103 | |
d83fac45 |
104 | Recent versions of VMS tar on ODS-5 volumes may extract tape archive |
105 | files with ^. escaped periods in them. See below for further workarounds. |
106 | |
10019e56 |
107 | A port of GNU tar is also available as part of the GNV package: |
108 | |
ec55d5e4 |
109 | http://h71000.www7.hp.com/opensource/gnv.html |
10019e56 |
110 | |
b4bc034f |
111 | =item 3 UNZIP.EXE for VMS |
112 | |
113 | A combination decompressor and archive reader/writer for *.zip files. |
114 | Unzip is available from a number of web/ftp sites. |
115 | |
adc5a9a5 |
116 | http://www.info-zip.org/UnZip.html |
10019e56 |
117 | http://www.hp.com/go/openvms/freeware/ |
eb863851 |
118 | ftp://ftp.hp.com/pub/openvms/ |
119 | ftp://ftp.process.com/vms-freeware/fileserv/ |
b4bc034f |
120 | |
121 | =item 4 MOST |
122 | |
123 | Most is an optional pager that is convenient to use with perldoc (unlike |
124 | TYPE/PAGE, MOST can go forward and backwards in a document and supports |
125 | regular expression searching). Most builds with the slang |
126 | library on VMS. Most and slang are available from: |
127 | |
128 | ftp://space.mit.edu/pub/davis/ |
adc5a9a5 |
129 | ftp://ftp.process.com/vms-freeware/narnia/ |
b4bc034f |
130 | |
1bc81404 |
131 | =item 5 GNU PATCH and DIFFUTILS for VMS |
132 | |
133 | Patches to Perl are usually distributed as GNU unified or contextual diffs. |
134 | Such patches are created by the GNU diff program (part of the diffutils |
135 | distribution) and applied with GNU patch. VMS ports of these utilities are |
136 | available here: |
137 | |
ec55d5e4 |
138 | http://www.antinode.info/dec/sw/diffutils.html |
10019e56 |
139 | http://www.hp.com/go/openvms/freeware/ |
1bc81404 |
140 | |
b4bc034f |
141 | =back |
142 | |
9f3f8d50 |
143 | Please note that UNZIP and GUNZIP are not the same thing (they work with |
b4bc034f |
144 | different formats). Many of the useful files from CPAN (the Comprehensive |
58979ab1 |
145 | Perl Archive Network) are in *.tar.gz or *.tgz format (this includes copies |
146 | of the source code for perl as well as modules and scripts that you may |
147 | wish to add later) hence you probably want to have GUNZIP.EXE and |
148 | VMSTAR.EXE on your VMS machine. |
fb73857a |
149 | |
b4bc034f |
150 | If you want to include socket support, you'll need a TCP/IP stack and either |
151 | DEC C, or socket libraries. See the "Socket Support (optional)" topic |
152 | for more details. |
fb73857a |
153 | |
d83fac45 |
154 | =head1 Unpacking the Perl source code |
155 | |
156 | You may need to set up a foreign symbol for the unpacking utility of choice. |
157 | |
718752a5 |
158 | As of version 5.10.0, Perl will still build and run on ODS-2 volumes, |
159 | including on VAX, but there are a number of modules whose temporary |
160 | files and tests are much happier residing on ODS-5 volumes. For |
161 | example, CPANPLUS will fail most of its tests on an ODS-2 volume because |
162 | it includes files with multiple dots that will have been converted to |
163 | underscores and the tests will have difficulty finding them. So your |
164 | best bet is to unpack the Perl source kit on an ODS-5 volume using |
165 | recent versions of vmstar (e.g. V3.4 or later). Contrary to advice |
166 | provided with previous versions of Perl, do I<not> use the ODS-2 |
167 | compatability qualifier. Instead, use a command like the following: |
168 | |
169 | vmstar /extract/verbose perl-V^.VIII^.III.tar |
d83fac45 |
170 | |
171 | or: |
172 | |
1c1fca66 |
173 | vmstar -xvf perl-5^.11^.0.tar |
d83fac45 |
174 | |
718752a5 |
175 | Then rename the top-level source directory like so: |
d83fac45 |
176 | |
1c1fca66 |
177 | set security/protection=(o:rwed) perl-5^.11^.0.dir |
178 | rename perl-5^.11^.0.dir perl-5_11_0.dir |
d83fac45 |
179 | |
718752a5 |
180 | The reason for this last step is that while filenames with multiple dots |
181 | are generally supported by Perl on VMS, I<directory> names with multiple |
182 | dots are a special case with special problems because the dot is the |
183 | traditional directory delimiter on VMS. Rudimentary support for |
184 | multi-dot directory names is available, but some of the oldest and most |
185 | essential parts of Perl (such as searching for and loading library |
186 | modules) do not yet fully support the ODS-5 caret-escape syntax. |
d83fac45 |
187 | |
b4bc034f |
188 | =head1 Configuring the Perl build |
fb73857a |
189 | |
97abc6ad |
190 | To configure perl (a necessary first step), issue the command |
fb73857a |
191 | |
b4bc034f |
192 | @ Configure |
fb73857a |
193 | |
b4bc034f |
194 | from the top of an unpacked perl source directory. You will be asked a |
195 | series of questions, and the answers to them (along with the capabilities |
196 | of your C compiler and network stack) will determine how perl is custom |
197 | built for your machine. |
fb73857a |
198 | |
b4bc034f |
199 | If you have multiple C compilers installed, you'll have your choice of |
200 | which one to use. Various older versions of DEC C had some caveats, so if |
201 | you're using a version older than 5.2, check the "DEC C Issues" section. |
fb73857a |
202 | |
b4bc034f |
203 | If you have any symbols or logical names in your environment that may |
204 | interfere with the build or regression testing of perl then configure.com |
205 | will try to warn you about them. If a logical name is causing |
7bb57f25 |
206 | you trouble but is in an LNM table that you do not have write access to |
207 | then try defining your own to a harmless equivalence string in a table |
208 | such that it is resolved before the other (e.g. if TMP is defined in the |
b4bc034f |
209 | SYSTEM table then try DEFINE TMP "NL:" or somesuch in your process table) |
210 | otherwise simply deassign the dangerous logical names. The potentially |
211 | troublesome logicals and symbols are: |
7bb57f25 |
212 | |
b3b333bf |
213 | COMP "LOGICAL" |
214 | EXT "LOGICAL" |
215 | FOO "LOGICAL" |
216 | LIB "LOGICAL" |
217 | LIST "LOGICAL" |
218 | MIME "LOGICAL" |
219 | POSIX "LOGICAL" |
220 | SYS "LOGICAL" |
221 | T "LOGICAL" |
222 | THREAD "LOGICAL" |
223 | THREADS "LOGICAL" |
224 | TIME "LOGICAL" |
225 | TMP "LOGICAL" |
226 | UNICODE "LOGICAL" |
227 | UTIL "LOGICAL" |
228 | TEST "SYMBOL" |
fb73857a |
229 | |
97abc6ad |
230 | As a handy shortcut, the command: |
231 | |
b4bc034f |
232 | @ Configure "-des" |
233 | |
234 | (note the quotation marks and case) will choose reasonable defaults |
235 | automatically (it takes DEC C over Gnu C, DEC C sockets over SOCKETSHR |
1bc81404 |
236 | sockets, and either over no sockets). Some options can be given |
237 | explicitly on the command line; the following example specifies a |
238 | non-default location for where Perl will be installed: |
239 | |
240 | @ Configure "-d" "-Dprefix=dka100:[utils.perl5.]" |
241 | |
dab31494 |
242 | Note that the installation location would be by default where you unpacked |
fe05d1a7 |
243 | the source with a "_ROOT." appended. For example if you unpacked the perl |
dab31494 |
244 | source into: |
245 | |
246 | DKA200:[PERL-5_10_2...] |
247 | |
adc5a9a5 |
248 | Then the PERL_SETUP.COM that gets written out by CONFIGURE.COM will |
dab31494 |
249 | try to DEFINE your installation PERL_ROOT to be: |
250 | |
fe05d1a7 |
251 | DKA200:[PERL-5_10_2_ROOT.] |
dab31494 |
252 | |
1bc81404 |
253 | More help with configure.com is available from: |
b4bc034f |
254 | |
255 | @ Configure "-h" |
256 | |
257 | See the "Changing compile-time options (optional)" section below to learn |
258 | even more details about how to influence the outcome of the important |
259 | configuration step. If you find yourself reconfiguring and rebuilding |
260 | then be sure to also follow the advice in the "Cleaning up and starting |
261 | fresh (optional)" and the checklist of items in the "CAVEATS" sections |
262 | below. |
263 | |
a83b6f46 |
264 | =head2 Changing compile-time options (optional) for Perl on VMS |
b4bc034f |
265 | |
266 | Most of the user definable features of Perl are enabled or disabled in |
adc5a9a5 |
267 | configure.com, which processes the hints file config_h.SH. There is |
268 | code in there to Do The Right Thing, but that may end up being the |
269 | wrong thing for you. Make sure you understand what you are doing since |
270 | inappropriate changes to configure.com or config_h.SH can render perl |
271 | unbuildable; odds are that there's nothing in there you'll need to |
272 | change. |
b4bc034f |
273 | |
a83b6f46 |
274 | =head2 Socket Support (optional) for Perl on VMS |
b4bc034f |
275 | |
276 | Perl includes a number of functions for IP sockets, which are available if |
277 | you choose to compile Perl with socket support. Since IP networking is an |
278 | optional addition to VMS, there are several different IP stacks available. |
279 | How well integrated they are into the system depends on the stack, your |
280 | version of VMS, and the version of your C compiler. |
281 | |
17d4810c |
282 | The default solution available is to use the socket routines built into DEC |
b4bc034f |
283 | C. Which routines are available depend on the version of VMS you're |
284 | running, and require proper UCX emulation by your TCP/IP vendor. |
285 | Relatively current versions of Multinet, TCPWare, Pathway, and UCX all |
286 | provide the required libraries--check your manuals or release notes to see |
287 | if your version is new enough. |
288 | |
17d4810c |
289 | The other solution uses the SOCKETSHR library. Before VAX/VMS 5.5-2 it was |
290 | the most portable solution. The SOCKETSHR library has not been maintained |
291 | since VAX/VMS 5.5-2, and it is not known if will even compile with the ANSI |
292 | C that Perl currently requires. It remains an option for historical reasons, |
293 | just in case someone might find it useful. |
294 | |
295 | In combination with either UCX or NetLib, this supported all the major TCP |
296 | stacks (Multinet, Pathways, TCPWare, UCX, and CMU) on all versions of VMS |
297 | Perl ran on up to VAX/VMS 6.2 and Alpha VMS 1.5 with all the compilers on |
298 | both VAX and Alpha. The portion of the socket interface was also consistent |
299 | across versions of VMS and C compilers. |
300 | |
301 | It has a problem with UDP sockets when used with Multinet, though, so you |
302 | should be aware of that. |
303 | |
304 | As of VAX/VMS 5.5-2 and later, CMU is the only TCP/IP program that requires |
305 | socketshr, and the sources have been lost to the most recent CMU bug fixes, |
306 | so CMU is limited to OpenVMS/VAX 6.2 or earlier, which is the last release |
307 | that binaries for the last released patches are known to exist. |
308 | |
309 | There is currently no official web site for downloading either CMU or |
310 | SOCKETSHR; however, copies may be found in the DECUS archives. |
311 | |
b4bc034f |
312 | =head1 Building Perl |
313 | |
314 | The configuration script will print out, at the very end, the MMS or MMK |
315 | command you need to compile perl. Issue it (exactly as printed) to start |
316 | the build. |
97abc6ad |
317 | |
b4bc034f |
318 | Once you issue your MMS or MMK command, sit back and wait. Perl should |
319 | compile and link without a problem. If a problem does occur check the |
320 | "CAVEATS" section of this document. If that does not help send some |
321 | mail to the VMSPERL mailing list. Instructions are in the "Mailing Lists" |
322 | section of this document. |
97abc6ad |
323 | |
b4bc034f |
324 | =head1 Testing Perl |
fb73857a |
325 | |
b4bc034f |
326 | Once Perl has built cleanly you need to test it to make sure things work. |
327 | This step is very important since there are always things that can go wrong |
328 | somehow and yield a dysfunctional Perl for you. |
fb73857a |
329 | |
330 | Testing is very easy, though, as there's a full test suite in the perl |
b4bc034f |
331 | distribution. To run the tests, enter the *exact* MMS line you used to |
fb73857a |
332 | compile Perl and add the word "test" to the end, like this: |
333 | |
b4bc034f |
334 | If the compile command was: |
fb73857a |
335 | |
b4bc034f |
336 | MMS |
fb73857a |
337 | |
b4bc034f |
338 | then the test command ought to be: |
fb73857a |
339 | |
b4bc034f |
340 | MMS test |
fb73857a |
341 | |
b4bc034f |
342 | MMS (or MMK) will run all the tests. This may take some time, as there are |
343 | a lot of tests. If any tests fail, there will be a note made on-screen. |
344 | At the end of all the tests, a summary of the tests, the number passed and |
345 | failed, and the time taken will be displayed. |
fb73857a |
346 | |
96d6186e |
347 | The test driver invoked via MMS TEST has a DCL wrapper ([.VMS]TEST.COM) that |
348 | downgrades privileges to NETMBX, TMPMBX for the duration of the test run, |
349 | and then restores them to their prior state upon completion of testing. |
350 | This is done to ensure that the tests run in a private sandbox and can do no |
351 | harm to your system even in the unlikely event something goes badly wrong in |
352 | one of the test scripts while running the tests from a privileged account. |
353 | A side effect of this safety precaution is that the account used to run the |
354 | test suite must be the owner of the directory tree in which Perl has been |
355 | built; otherwise the manipulations of temporary files and directories |
356 | attempted by some of the tests will fail. |
357 | |
718752a5 |
358 | If any tests fail, it means something is wrong with Perl, or at least |
359 | with the particular module or feature that reported failure. If the test suite |
fb73857a |
360 | hangs (some tests can take upwards of two or three minutes, or more if |
9f3f8d50 |
361 | you're on an especially slow machine, depending on your machine speed, so |
fb73857a |
362 | don't be hasty), then the test *after* the last one displayed failed. Don't |
363 | install Perl unless you're confident that you're OK. Regardless of how |
364 | confident you are, make a bug report to the VMSPerl mailing list. |
365 | |
b4bc034f |
366 | If one or more tests fail, you can get more information on the failure by |
367 | issuing this command sequence: |
fb73857a |
368 | |
b4bc034f |
369 | @ [.VMS]TEST .typ "" "-v" [.subdir]test.T |
fb73857a |
370 | |
371 | where ".typ" is the file type of the Perl images you just built (if you |
372 | didn't do anything special, use .EXE), and "[.subdir]test.T" is the test |
373 | that failed. For example, with a normal Perl build, if the test indicated |
96d6186e |
374 | that t/op/time failed, then you'd do this: |
fb73857a |
375 | |
b4bc034f |
376 | @ [.VMS]TEST .EXE "" "-v" [.OP]TIME.T |
fb73857a |
377 | |
96d6186e |
378 | Note that test names are reported in UNIX syntax and relative to the |
379 | top-level build directory. When supplying them individually to the test |
380 | driver, you can use either UNIX or VMS syntax, but you must give the path |
381 | relative to the [.T] directory and you must also add the .T extension to the |
382 | filename. So, for example if the test lib/Math/Trig fails, you would run: |
383 | |
384 | @ [.VMS]TEST .EXE "" -"v" [-.lib.math]trig.t |
385 | |
fb73857a |
386 | When you send in a bug report for failed tests, please include the output |
387 | from this command, which is run from the main source directory: |
388 | |
b4bc034f |
389 | MCR []MINIPERL "-V" |
390 | |
391 | Note that -"V" really is a capital V in double quotes. This will dump out a |
392 | couple of screens worth of configuration information, and can help us |
393 | diagnose the problem. If (and only if) that did not work then try enclosing |
394 | the output of: |
395 | |
396 | MMS printconfig |
fb73857a |
397 | |
9f3f8d50 |
398 | If (and only if) that did not work then try enclosing the output of: |
399 | |
b4bc034f |
400 | @ [.vms]myconfig |
fb73857a |
401 | |
b4bc034f |
402 | You may also be asked to provide your C compiler version ("CC/VERSION NL:" |
403 | with DEC C, "gcc --version" with GNU CC). To obtain the version of MMS or |
404 | MMK you are running try "MMS/ident" or "MMK /ident". The GNU make version |
405 | can be identified with "make --version". |
406 | |
a83b6f46 |
407 | =head2 Cleaning up and starting fresh (optional) installing Perl on VMS |
fb73857a |
408 | |
409 | If you need to recompile from scratch, you have to make sure you clean up |
b4bc034f |
410 | first. There is a procedure to do it--enter the *exact* MMS line you used |
411 | to compile and add "realclean" at the end, like this: |
fb73857a |
412 | |
b4bc034f |
413 | if the compile command was: |
fb73857a |
414 | |
b4bc034f |
415 | MMS |
fb73857a |
416 | |
b4bc034f |
417 | then the cleanup command ought to be: |
fb73857a |
418 | |
b4bc034f |
419 | MMS realclean |
fb73857a |
420 | |
b4bc034f |
421 | If you do not do this things may behave erratically during the subsequent |
422 | rebuild attempt. They might not, too, so it is best to be sure and do it. |
fb73857a |
423 | |
b4bc034f |
424 | =head1 Installing Perl |
fb73857a |
425 | |
426 | There are several steps you need to take to get Perl installed and |
3a385817 |
427 | running. |
fb73857a |
428 | |
a3ef2c6f |
429 | =over 4 |
b4bc034f |
430 | |
a3ef2c6f |
431 | =item 1 |
fb73857a |
432 | |
a3ef2c6f |
433 | Check your default file protections with |
fb73857a |
434 | |
a3ef2c6f |
435 | SHOW PROTECTION /DEFAULT |
fb73857a |
436 | |
a3ef2c6f |
437 | and adjust if necessary with SET PROTECTION=(code)/DEFAULT. |
fb73857a |
438 | |
a3ef2c6f |
439 | =item 2 |
3a385817 |
440 | |
1bc81404 |
441 | Decide where you want Perl to be installed (unless you have already done so |
442 | by using the "prefix" configuration parameter -- see the example in the |
443 | "Configuring the Perl build" section). |
b4bc034f |
444 | |
1bc81404 |
445 | The DCL script PERL_SETUP.COM that is written by CONFIGURE.COM will help you |
446 | with the definition of the PERL_ROOT and PERLSHR logical names and the PERL |
447 | foreign command symbol. Take a look at PERL_SETUP.COM and modify it if you |
448 | want to. The installation process will execute PERL_SETUP.COM and copy |
449 | files to the directory tree pointed to by the PERL_ROOT logical name defined |
450 | there, so make sure that you have write access to the parent directory of |
451 | what will become the root of your Perl installation. |
fb73857a |
452 | |
a3ef2c6f |
453 | =item 3 |
b4bc034f |
454 | |
a3ef2c6f |
455 | Run the install script via: |
b4bc034f |
456 | |
a3ef2c6f |
457 | MMS install |
b4bc034f |
458 | |
a3ef2c6f |
459 | or |
9f3f8d50 |
460 | |
a3ef2c6f |
461 | MMK install |
b4bc034f |
462 | |
a3ef2c6f |
463 | If for some reason it complains about target INSTALL being up to date, |
464 | throw a /FORCE switch on the MMS or MMK command. |
b4bc034f |
465 | |
a3ef2c6f |
466 | =back |
467 | |
1bc81404 |
468 | Copy PERL_SETUP.COM to a place accessible to your perl users. |
469 | |
a3ef2c6f |
470 | For example: |
fb73857a |
471 | |
a3ef2c6f |
472 | COPY PERL_SETUP.COM SYS$LIBRARY: |
b4bc034f |
473 | |
a3ef2c6f |
474 | If you want to have everyone on the system have access to perl |
475 | then add a line that reads |
fb73857a |
476 | |
a3ef2c6f |
477 | $ @sys$library:perl_setup |
491527d0 |
478 | |
a3ef2c6f |
479 | to SYS$MANAGER:SYLOGIN.COM. |
85988417 |
480 | |
a3ef2c6f |
481 | Two alternatives to the foreign symbol would be to install PERL into |
482 | DCLTABLES.EXE (Check out the section "Installing Perl into DCLTABLES |
483 | (optional)" for more information), or put the image in a |
484 | directory that's in your DCL$PATH (if you're using VMS V6.2 or higher). |
85988417 |
485 | |
a3ef2c6f |
486 | An alternative to having PERL_SETUP.COM define the PERLSHR logical name |
487 | is to simply copy it into the system shareable library directory with: |
488 | |
489 | copy perl_root:[000000]perlshr.exe sys$share: |
85988417 |
490 | |
a3ef2c6f |
491 | See also the "INSTALLing images (optional)" section. |
491527d0 |
492 | |
a83b6f46 |
493 | =head2 Installing Perl into DCLTABLES (optional) on VMS |
fb73857a |
494 | |
9ef4b0a6 |
495 | Execute the following command file to define PERL as a DCL command. |
b4bc034f |
496 | You'll need CMKRNL privilege to install the new dcltables.exe. |
fb73857a |
497 | |
7bb57f25 |
498 | $ create perl.cld |
499 | ! |
500 | ! modify to reflect location of your perl.exe |
501 | ! |
502 | define verb perl |
503 | image perl_root:[000000]perl.exe |
504 | cliflags (foreign) |
505 | $! |
506 | $ set command perl /table=sys$common:[syslib]dcltables.exe - |
507 | /output=sys$common:[syslib]dcltables.exe |
508 | $ install replace sys$common:[syslib]dcltables.exe |
509 | $ exit |
fb73857a |
510 | |
a83b6f46 |
511 | =head2 INSTALLing Perl images (optional) on VMS |
9f3f8d50 |
512 | |
513 | On systems that are using perl quite a bit, and particularly those with |
514 | minimal RAM, you can boost the performance of perl by INSTALLing it as |
adc5a9a5 |
515 | a known image. PERLSHR.EXE is typically larger than 3000 blocks |
9f3f8d50 |
516 | and that is a reasonably large amount of IO to load each time perl is |
517 | invoked. |
518 | |
519 | INSTALL ADD PERLSHR/SHARE |
b4bc034f |
520 | INSTALL ADD PERL/HEADER |
9f3f8d50 |
521 | |
522 | should be enough for PERLSHR.EXE (/share implies /header and /open), |
523 | while /HEADER should do for PERL.EXE (perl.exe is not a shared image). |
524 | |
b4bc034f |
525 | If your code 'use's modules, check to see if there is a shareable image for |
526 | them, too. In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File, |
e7948fac |
527 | DCLsym, and Stdio, and other extensions all have shared images that can be |
528 | installed /SHARE. |
9f3f8d50 |
529 | |
b4bc034f |
530 | How much of a win depends on your memory situation, but if you are firing |
9f3f8d50 |
531 | off perl with any regularity (like more than once every 20 seconds or so) |
b4bc034f |
532 | it is probably beneficial to INSTALL at least portions of perl. |
9f3f8d50 |
533 | |
534 | While there is code in perl to remove privileges as it runs you are advised |
535 | to NOT INSTALL PERL.EXE with PRIVs! |
fb73857a |
536 | |
dab31494 |
537 | =head2 Running h2ph to create perl header files (optional) on VMS |
538 | |
10019e56 |
539 | If using HP C, ensure that you have extracted loose versions of your |
540 | compiler's header or *.H files. Be sure to check the contents of: |
dab31494 |
541 | |
542 | SYS$LIBRARY:DECC$RTLDEF.TLB |
543 | SYS$LIBRARY:SYS$LIB_C.TLB |
544 | SYS$LIBRARY:SYS$STARLET_C.TLB |
545 | |
546 | etcetera. |
547 | |
548 | If using GNU cc then also check your GNU_CC:[000000...] tree for the locations |
549 | of the GNU cc headers. |
550 | |
b4bc034f |
551 | =head1 Reporting Bugs |
fb73857a |
552 | |
553 | If you come across what you think might be a bug in Perl, please report |
554 | it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through |
555 | the process of creating a bug report. This script includes details of your |
556 | installation, and is very handy. Completed bug reports should go to |
9f3f8d50 |
557 | perlbug@perl.com. |
fb73857a |
558 | |
b4bc034f |
559 | =head1 CAVEATS |
fb73857a |
560 | |
561 | Probably the single biggest gotcha in compiling Perl is giving the wrong |
b4bc034f |
562 | switches to MMS/MMK when you build. Use *exactly* what the configure.com |
563 | script prints! |
564 | |
565 | The next big gotcha is directory depth. Perl can create directories four, |
566 | five, or even six levels deep during the build, so you don't have to be |
dab31494 |
567 | too deep to start to hit the RMS 8 level limit (for ODS 2 volumes which were |
ec55d5e4 |
568 | common on versions of VMS prior to V7.2 and even with V7.3 on the VAX). |
dab31494 |
569 | It is best to do: |
b4bc034f |
570 | |
571 | DEFINE/TRANS=(CONC,TERM) PERLSRC "disk:[dir.dir.dir.perldir.]" |
572 | SET DEFAULT PERLSRC:[000000] |
573 | |
574 | before building in cases where you have to unpack the distribution so deep |
575 | (note the trailing period in the definition of PERLSRC). Perl modules |
576 | from CPAN can be just as bad (or worse), so watch out for them, too. Perl's |
577 | configuration script will warn if it thinks you are too deep (at least on |
578 | a VAX or on Alpha versions of VMS prior to 7.2). But MakeMaker will not |
579 | warn you if you start out building a module too deep in a directory. |
580 | |
d83fac45 |
581 | As noted above ODS-5 escape sequences such as ^. can break the perl |
582 | build. Solutions include renaming files and directories as needed or |
583 | being careful to use the -o switch or /ODS2 qualifier with latter |
584 | versions of the vmstar utility when unpacking perl or CPAN modules |
585 | on ODS-5 volumes. |
586 | |
b4bc034f |
587 | Be sure that the process that you use to build perl has a PGFLQ greater |
588 | than 100000. Be sure to have a correct local time zone to UTC offset |
589 | defined (in seconds) in the logical name SYS$TIMEZONE_DIFFERENTIAL before |
590 | running the regression test suite. The SYS$MANAGER:UTC$CONFIGURE_TDF.COM |
591 | procedure will help you set that logical for your system but may require |
592 | system privileges. For example, a location 5 hours west of UTC (such as |
593 | the US East coast while not on daylight savings time) would have: |
594 | |
595 | DEFINE SYS$TIMEZONE_DIFFERENTIAL "-18000" |
596 | |
597 | A final thing that causes trouble is leftover pieces from a failed |
598 | build. If things go wrong make sure you do a "(MMK|MMS|make) realclean" |
fb73857a |
599 | before you rebuild. |
600 | |
a83b6f46 |
601 | =head2 DEC C issues with Perl on VMS |
fb73857a |
602 | |
b4bc034f |
603 | Note to DEC C users: Some early versions (pre-5.2, some pre-4. If you're DEC |
c54e8273 |
604 | C 5.x or higher, with current patches if any, you're fine) of the DECCRTL |
fb73857a |
605 | contained a few bugs which affect Perl performance: |
b4bc034f |
606 | |
607 | =over 4 |
608 | |
609 | =item - pipes |
610 | |
611 | Newlines are lost on I/O through pipes, causing lines to run together. |
612 | This shows up as RMS RTB errors when reading from a pipe. You can |
613 | work around this by having one process write data to a file, and |
614 | then having the other read the file, instead of the pipe. This is |
615 | fixed in version 4 of DEC C. |
616 | |
617 | =item - modf() |
618 | |
619 | The modf() routine returns a non-integral value for some values above |
620 | INT_MAX; the Perl "int" operator will return a non-integral value in |
621 | these cases. This is fixed in version 4 of DEC C. |
622 | |
623 | =item - ALPACRT ECO |
624 | |
625 | On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine |
626 | changes the process default device and directory permanently, even |
627 | though the call specified that the change should not persist after |
628 | Perl exited. This is fixed by DEC CSC patch ALPACRT04_061 or later. |
629 | See also: |
630 | |
eb863851 |
631 | http://www.itrc.hp.com/ |
b4bc034f |
632 | |
633 | =back |
634 | |
635 | Please note that in later versions "DEC C" may also be known as |
636 | "Compaq C". |
637 | |
a83b6f46 |
638 | =head2 GNU issues with Perl on VMS |
b4bc034f |
639 | |
640 | It has been a while since the GNU utilities such as GCC or GNU make |
641 | were used to build perl on VMS. Hence they may require a great deal |
642 | of source code modification to work again. |
643 | |
b4bc034f |
644 | http://www.progis.de/ |
b4bc034f |
645 | |
e7948fac |
646 | =head2 Floating Point Considerations |
647 | |
648 | Prior to 5.8.0, Perl simply accepted the default floating point options of the |
649 | C compiler, namely representing doubles with D_FLOAT on VAX and G_FLOAT on |
650 | Alpha. Single precision floating point values are represented in F_FLOAT |
651 | format when either D_FLOAT or G_FLOAT is in use for doubles. Beginning with |
652 | 5.8.0, Alpha builds now use IEEE floating point formats by default, which in |
653 | VMS parlance are S_FLOAT for singles and T_FLOAT for doubles. IEEE is not |
654 | available on VAX, so F_FLOAT and D_FLOAT remain the defaults for singles and |
655 | doubles respectively. The available non-default options are G_FLOAT on VAX |
656 | and D_FLOAT or G_FLOAT on Alpha. |
657 | |
658 | The use of IEEE on Alpha introduces NaN, infinity, and denormalization |
659 | capabilities not available with D_FLOAT and G_FLOAT. When using one of those |
660 | non-IEEE formats, silent underflow and overflow are emulated in the conversion |
661 | of strings to numbers, but it is preferable to get the real thing by using |
662 | IEEE where possible. |
663 | |
664 | Regardless of what floating point format you consider preferable, be aware |
665 | that the choice may have an impact on compatibility with external libraries, |
666 | such as database interfaces, and with existing data, such as data created with |
667 | the C<pack> function and written to disk, or data stored via the Storable |
668 | extension. For example, a C<pack("d", $foo)")> will create a D_FLOAT, |
669 | G_FLOAT, or T_FLOAT depending on what your Perl was configured with. When |
670 | written to disk, the value can only be retrieved later by a Perl configured |
671 | with the same floating point option that was in effect when it was created. |
672 | |
673 | To obtain a non-IEEE build on Alpha, simply answer no to the "Use IEEE math?" |
674 | question during the configuration. To obtain an option different from the C |
675 | compiler default on either VAX or Alpha, put in the option that you want in |
676 | answer to the "Any additional cc flags?" question. For example, to obtain a |
677 | G_FLOAT build on VAX, put in C</FLOAT=G_FLOAT>. |
678 | |
49fd6f17 |
679 | =head2 Multinet issues with Perl on VMS |
680 | |
681 | Prior to the release of Perl 5.8.0 it was noted that the regression |
682 | test for lib/Net/hostent (in file [.lib.Net]hostent.t) will fail owing |
683 | to problems with the hostent structure returned by C calls to either |
684 | gethostbyname() or gethostbyaddr() using DEC or Compaq C with a |
685 | Multinet TCP/IP stack. The problem was noted in Multinet 4.3A |
686 | using either Compaq C 6.5 or DEC C 6.0, and with Multinet 4.2A |
687 | using DEC C 5.2, but could easily affect other versions of Multinet. |
c2a352b2 |
688 | Process Software Inc. has acknowledged a bug in the Multinet version |
689 | of UCX$IPC_SHR and has provided an ECO for it. The ECO is called |
690 | UCX_LIBRARY_EMULATION-010_A044 and is available from: |
49fd6f17 |
691 | |
692 | http://www.multinet.process.com/eco.html |
693 | |
c2a352b2 |
694 | As of this writing, the ECO is only available for Multinet versions |
695 | 4.3A and later. You may determine the version of Multinet that you |
696 | are running using the command: |
49fd6f17 |
697 | |
698 | multinet show /version |
699 | |
700 | from the DCL command prompt. |
701 | |
c2a352b2 |
702 | If the ECO is unavailable for your version of Multinet and you are |
703 | unable to upgrade, you might try using Perl programming constructs |
704 | such as: |
49fd6f17 |
705 | |
706 | $address = substr($gethostbyname_addr,0,4); |
707 | |
708 | to temporarily work around the problem, or if you are brave |
709 | and do not mind the possibility of breaking IPv6 addresses, |
710 | you might modify the pp_sys.c file to add an ad-hoc correction |
711 | like so: |
712 | |
713 | |
714 | --- pp_sys.c;1 Thu May 30 14:42:17 2002 |
715 | +++ pp_sys.c Thu May 30 12:54:02 2002 |
716 | @@ -4684,6 +4684,10 @@ |
717 | } |
718 | #endif |
719 | |
720 | + if (hent) { |
721 | + hent->h_length = 4; |
722 | + } |
723 | + |
724 | if (GIMME != G_ARRAY) { |
725 | PUSHs(sv = sv_newmortal()); |
726 | if (hent) { |
727 | |
728 | then re-compile and re-test your perl. After the installation |
729 | of the Multinet ECO you ought to back out any such changes though. |
730 | |
b4bc034f |
731 | =head1 Mailing Lists |
732 | |
733 | There are several mailing lists available to the Perl porter. For VMS |
fb73857a |
734 | specific issues (including both Perl questions and installation problems) |
b4bc034f |
735 | there is the VMSPERL mailing list. It is usually a low-volume (10-12 |
fb73857a |
736 | messages a week) mailing list. |
737 | |
1bc81404 |
738 | To subscribe, send a mail message to VMSPERL-SUBSCRIBE@PERL.ORG. The VMSPERL |
739 | mailing list address is VMSPERL@PERL.ORG. Any mail sent there gets echoed |
740 | to all subscribers of the list. There is a searchable archive of the list |
741 | on the web at: |
b4bc034f |
742 | |
743 | http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/ |
a83b6f46 |
744 | |
1bc81404 |
745 | To unsubscribe from VMSPERL send a message to VMSPERL-UNSUBSCRIBE@PERL.ORG. |
746 | Be sure to do so from the subscribed account that you are canceling. |
b4bc034f |
747 | |
a83b6f46 |
748 | =head2 Web sites for Perl on VMS |
b4bc034f |
749 | |
750 | Vmsperl pages on the web include: |
751 | |
752 | http://www.sidhe.org/vmsperl/index.html |
468f45d5 |
753 | http://www.cpan.org/modules/by-module/VMS/ |
60d9c7be |
754 | http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/ |
adc5a9a5 |
755 | http://www-ang.kfunigraz.ac.at/~binder/perl.html |
60d9c7be |
756 | http://lists.perl.org/showlist.cgi?name=vmsperl |
757 | http://archive.develooper.com/vmsperl@perl.org/ |
10019e56 |
758 | http://h71000.www7.hp.com/openvms/products/ips/apache/csws_modperl.html |
fb73857a |
759 | |
b4bc034f |
760 | =head1 SEE ALSO |
761 | |
762 | Perl information for users and programmers about the port of perl to VMS is |
3bc8f799 |
763 | available from the [.POD]PERLVMS.POD file that gets installed as L<perlvms>. |
b4bc034f |
764 | For administrators the perlvms document also includes a detailed discussion |
765 | of extending vmsperl with CPAN modules after Perl has been installed. |
766 | |
767 | =head1 AUTHORS |
768 | |
ec55d5e4 |
769 | Originally by Charles Bailey bailey@newman.upenn.edu. See the git repository |
770 | for history. |
b4bc034f |
771 | |
772 | =head1 ACKNOWLEDGEMENTS |
fb73857a |
773 | |
774 | A real big thanks needs to go to Charles Bailey |
b4bc034f |
775 | bailey@newman.upenn.edu, who is ultimately responsible for Perl 5.004 |
fb73857a |
776 | running on VMS. Without him, nothing the rest of us have done would be at |
777 | all important. |
778 | |
779 | There are, of course, far too many people involved in the porting and testing |
780 | of Perl to mention everyone who deserves it, so please forgive us if we've |
781 | missed someone. That said, special thanks are due to the following: |
b4bc034f |
782 | |
783 | Tim Adye T.J.Adye@rl.ac.uk |
fb73857a |
784 | for the VMS emulations of getpw*() |
b4bc034f |
785 | David Denholm denholm@conmat.phys.soton.ac.uk |
fb73857a |
786 | for extensive testing and provision of pipe and SocketShr code, |
b4bc034f |
787 | Mark Pizzolato mark@infocomm.com |
fb73857a |
788 | for the getredirection() code |
b4bc034f |
789 | Rich Salz rsalz@bbn.com |
fb73857a |
790 | for readdir() and related routines |
b4bc034f |
791 | Peter Prymmer pvhp@best.com |
fb73857a |
792 | for extensive testing, as well as development work on |
793 | configuration and documentation for VMS Perl, |
b4bc034f |
794 | Dan Sugalski dan@sidhe.org |
fb73857a |
795 | for extensive contributions to recent version support, |
796 | development of VMS-specific extensions, and dissemination |
797 | of information about VMS Perl, |
798 | the Stanford Synchrotron Radiation Laboratory and the |
799 | Laboratory of Nuclear Studies at Cornell University for |
9f3f8d50 |
800 | the opportunity to test and develop for the AXP, |
a3ef2c6f |
801 | John Hasstedt John.Hasstedt@sunysb.edu |
802 | for VAX VMS V7.2 support |
ec55d5e4 |
803 | John Malmberg wb8tyw@qsl.net |
804 | for ODS-5 filename handling and other modernizations |
b4bc034f |
805 | |
fb73857a |
806 | and to the entire VMSperl group for useful advice and suggestions. In |
807 | addition the perl5-porters deserve credit for their creativity and |
808 | willingness to work with the VMS newcomers. Finally, the greatest debt of |
b4bc034f |
809 | gratitude is due to Larry Wall larry@wall.org, for having the ideas which |
fb73857a |
810 | have made our sleepless nights possible. |
811 | |
812 | Thanks, |
813 | The VMSperl group |
b4bc034f |
814 | |
815 | =cut |
816 | |