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