Commit | Line | Data |
---|---|---|
9a997319 JH |
1 | If you read this file _as_is_, just ignore the funny characters you |
2 | see. It is written in the POD format (see pod/perlpod.pod) which is | |
3 | specially designed to be readable as is. | |
4 | ||
5 | =head1 NAME | |
6 | ||
7 | README.vos - Perl for Stratus VOS | |
8 | ||
9 | =head1 SYNOPSIS | |
24e8e380 | 10 | |
050dfae0 PG |
11 | This file contains notes for building perl on the Stratus VOS |
12 | operating system. Perl is a scripting or macro language that is | |
13 | popular on many systems. See L<perlbook> for a number of good | |
14 | books on Perl. | |
4f3de37c JH |
15 | |
16 | These are instructions for building Perl from source. Most people can | |
17 | simply download a pre-compiled distribution from the VOS anonymous FTP | |
18 | site. If you are running VOS Release 14.2.0 or earlier, download Perl | |
f224927c | 19 | from ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html If you are |
4f3de37c | 20 | running VOS Release 14.3.0 or later, download Perl from |
f224927c | 21 | ftp://ftp.stratus.com/pub/vos/posix/ga/ga.html Instructions for |
4f3de37c | 22 | unbundling the Perl distribution file are at |
1577cd80 | 23 | ftp://ftp.stratus.com/pub/vos/utility/utility.html |
495c5fdc | 24 | |
050dfae0 PG |
25 | If you are running VOS Release 14.4.1 or later, you can obtain a |
26 | pre-compiled, supported copy of perl by purchasing Release 2.0.1 | |
c17baaa1 | 27 | (or later) of the VOS GNU C++ and GNU Tools product from Stratus |
050dfae0 PG |
28 | Technologies. |
29 | ||
30 | =head2 Multiple methods to build perl for VOS | |
31 | ||
32 | If you elect to build perl from its source code, you have several | |
33 | different ways that you can build perl. The method that you use | |
34 | depends on the version of VOS that you are using and on the | |
c17baaa1 | 35 | architecture of your Stratus hardware platform. |
050dfae0 PG |
36 | |
37 | =over 5 | |
38 | ||
39 | =item 1 | |
40 | ||
41 | If you have a Stratus XA2000 (Motorola 68k-based) platform, you | |
42 | must build perl using the alpha version of VOS POSIX support and | |
43 | using the VOS Standard C Cross-compiler. You must build perl on | |
44 | VOS Release 14.1.0 (or later) on an XA/R or Continuum platform. | |
45 | ||
46 | This version of perl is properly called "miniperl" because it | |
c71882ca | 47 | does not contain the complete perl functionality. |
050dfae0 PG |
48 | |
49 | You must build perl with the compile_perl.cm command macro found | |
50 | in the vos subdirectory. | |
51 | ||
52 | =item 2 | |
53 | ||
54 | If you have a Stratus XA/R (Intel i860-based) platform, you must | |
55 | build perl using the alpha version of VOS POSIX support and using | |
56 | the VOS Standard C compiler or cross-compiler. You must build | |
57 | perl on VOS Release 14.1.0 (or later) on an XA/R or Continuum | |
58 | platform. | |
59 | ||
60 | This version of perl is properly called "miniperl" because it | |
c71882ca | 61 | does not contain the complete perl functionality. |
050dfae0 PG |
62 | |
63 | You must build perl with the compile_perl.cm command macro found | |
64 | in the vos subdirectory. | |
65 | ||
66 | =item 3 | |
67 | ||
c17baaa1 | 68 | If you have a Stratus Continuum (PA-RISC-based) platform that is |
050dfae0 PG |
69 | running a version of VOS earlier than VOS 14.3.0, you must build |
70 | perl using the alpha version of VOS POSIX support and using the | |
71 | VOS Standard C compiler or cross-compiler. You must build perl | |
72 | on VOS Release 14.1.0 (or later) on an XA/R or Continuum | |
73 | platform. | |
74 | ||
75 | This version of perl is properly called "miniperl" because it | |
c71882ca | 76 | does not contain the complete perl functionality. |
050dfae0 PG |
77 | |
78 | You must build perl with the compile_perl.cm command macro found | |
79 | in the vos subdirectory. | |
80 | ||
81 | =item 4 | |
82 | ||
c17baaa1 | 83 | If you have a Stratus Continuum (PA-RISC-based) platform that is |
c71882ca | 84 | running VOS Release 14.3.0 through VOS Release 14.4.1, you must |
050dfae0 PG |
85 | build perl using the generally-available version of VOS POSIX |
86 | support, and using either the VOS Standard C compiler or the VOS | |
87 | GNU C compiler. You must build perl on VOS Release 14.3.0 (or | |
88 | later) on a Continuum platform. | |
89 | ||
90 | This version of perl is properly called "miniperl" because it | |
c71882ca | 91 | does not contain the complete perl functionality. |
050dfae0 PG |
92 | |
93 | You must build perl with the compile_perl.cm command macro found | |
94 | in the vos subdirectory. | |
95 | ||
96 | =item 5 | |
97 | ||
98 | If you have a Stratus Continuum (PA-RISC-based) platform that is | |
c71882ca PG |
99 | running VOS Release 14.5.0 or later, you can either use the |
100 | previous method to build "miniperl" or you can build "full | |
101 | perl", which contains the complete functionality of perl. I | |
102 | strongly recommend that you build full perl. To build full | |
103 | perl, you must use the generally-available version of VOS POSIX | |
104 | support. You must use the VOS GNU C compiler and the VOS GNU | |
c17baaa1 PG |
105 | C/C++ and GNU Tools Release 2.0.1 (or later) product. You must |
106 | build full perl on VOS Release 14.5.0 (or later) on a Continuum | |
107 | platform. | |
c71882ca PG |
108 | |
109 | You must build full perl with the compile_full_perl.cm command | |
110 | macro found in the vos subdirectory. | |
050dfae0 PG |
111 | |
112 | =back | |
113 | ||
9a997319 | 114 | =head2 Stratus POSIX Support |
495c5fdc | 115 | |
5b8c1387 JH |
116 | Note that there are two different implementations of POSIX.1 |
117 | support on VOS. There is an alpha version of POSIX that is | |
118 | available from the Stratus anonymous ftp site | |
f224927c | 119 | ( ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html ). There |
050dfae0 PG |
120 | is a generally-available version of POSIX that comes with VOS |
121 | Release 14.3.0 or higher. This port of POSIX will compile and | |
122 | bind with either version of POSIX. | |
5b8c1387 JH |
123 | |
124 | Most of the Perl features should work on VOS regardless of which | |
125 | version of POSIX that you are using. However, the alpha version | |
126 | of POSIX is missing a number of key functions, and therefore any | |
495c5fdc PG |
127 | attempt by perl.pm to call the following unimplemented POSIX |
128 | functions will result in an error message and an immediate and | |
24e8e380 | 129 | fatal call to the VOS debugger. They are "dup", "fork", and |
8b204b88 JH |
130 | "waitpid". The lack of these functions prevents you from |
131 | starting VOS commands and grabbing their output in perl. The | |
132 | workaround is to run the commands outside of perl, then have perl | |
133 | process the output file. These functions are all available in | |
134 | the generally-available version of POSIX. | |
24e8e380 | 135 | |
9a997319 JH |
136 | =head1 INSTALLING PERL IN VOS |
137 | ||
138 | =head2 Compiling Perl 5 on VOS | |
495c5fdc | 139 | |
495c5fdc PG |
140 | Before you can build Perl 5 on VOS, you need to have or acquire the |
141 | following additional items. | |
142 | ||
9a997319 JH |
143 | =over 5 |
144 | ||
145 | =item 1 | |
146 | ||
0d6ca59a JH |
147 | The VOS Standard C Compiler (or the VOS Standard C |
148 | Cross-Compiler) and the VOS C Runtime. If you are using | |
149 | the generally-available version of POSIX support, you may | |
d1be9408 | 150 | instead use the VOS GNU C/C++ Compiler. These are |
0d6ca59a | 151 | standard Stratus products. |
9a997319 JH |
152 | |
153 | =item 2 | |
154 | ||
155 | Either the VOS OS TCP/IP or STCP product set. If you are | |
156 | building with the alpha version of POSIX you need the OS | |
157 | TCP/IP product set. If you are building with the | |
158 | generally-available version of POSIX you need the STCP | |
159 | product set. These are standard Stratus products. | |
160 | ||
161 | =item 3 | |
162 | ||
163 | Either the alpha or generally-available version of the VOS | |
164 | POSIX.1 environment. | |
165 | ||
166 | The alpha version of POSIX.1 support is available on the | |
167 | Stratus FTP site. Login anonymously to ftp.stratus.com and | |
168 | get the file /pub/vos/posix/alpha/posix.save.evf.gz in | |
169 | binary file-transfer mode. Or use the Uniform Resource | |
170 | Locator (URL) | |
37a78d01 | 171 | ftp://ftp.stratus.com/pub/vos/posix/alpha/posix.save.evf.gz from |
9a997319 | 172 | your web browser. Instructions for unbundling this file |
1577cd80 | 173 | are at ftp://ftp.stratus.com/pub/vos/utility/utility.html |
c17baaa1 | 174 | This is NOT a standard Stratus product. |
9a997319 | 175 | |
0d6ca59a JH |
176 | In VOS Release 14.3.0, the generally-available version of |
177 | POSIX.1 support is bundled with the VOS Standard C compiler | |
178 | (or Standard C Cross-Compiler). In VOS Release 14.4.0 or | |
179 | higher, it is also bundled with the VOS C Runtime. These | |
180 | are standard Stratus products. | |
9a997319 JH |
181 | |
182 | =item 4 | |
183 | ||
184 | You must compile this version of Perl 5 on VOS Release | |
185 | 14.1.0 or higher because some of the perl source files | |
186 | contain more than 32,767 source lines. Due to VOS | |
187 | release-compatibility rules, this port of perl may not | |
188 | execute on VOS Release 12 or earlier. | |
189 | ||
0d6ca59a JH |
190 | =item 5 |
191 | ||
8b204b88 JH |
192 | If you are using the generally-available version of VOS POSIX |
193 | support, then you should also acquire the VOS GNU C/C++ Compiler | |
050dfae0 PG |
194 | and GNU Tools product. When perl is built with this version of |
195 | POSIX support, it assumes that it can find "bash", "sed" and | |
196 | other POSIX-compatible commands in the directory | |
8b204b88 | 197 | /system/gnu_library/bin. |
0d6ca59a | 198 | |
9a997319 | 199 | =back |
24e8e380 | 200 | |
050dfae0 PG |
201 | To build perl using the supplied VOS command macros, change to |
202 | the "vos" subdirectory and type the command "compile_perl | |
203 | -processor X", where X is the processor type (mc68020, i80860, | |
204 | pa7100, pa8000) that you wish to use. Note that the | |
205 | generally-available version of POSIX.1 support is not available | |
206 | for the mc68020 or i80860 processors. | |
5b8c1387 | 207 | |
0d6ca59a JH |
208 | Use the "-version alpha" control argument to build perl with |
209 | the alpha version of POSIX support, and use the "-version | |
210 | ga" control argument to build it with the | |
211 | generally-available version of POSIX. The default is "ga". | |
212 | ||
213 | Use the "-compiler cc" control argument to build perl with | |
214 | the VOS Standard C compiler. Use the "-compiler gcc" | |
215 | control argument to build it with the GNU GCC compiler. The | |
216 | default is "cc". | |
217 | ||
5b8c1387 JH |
218 | You must have purchased the VOS Standard C Cross Compiler in |
219 | order to compile perl for a processor type that is different | |
220 | from the processor type of the module. | |
221 | ||
24e8e380 | 222 | Note that code compiled for the pa7100 processor type can |
5b8c1387 JH |
223 | execute on the PA7100, PA8000, PA8500 and PA8600 processors, and |
224 | that code compiled for the pa8000 processor type can execute on | |
225 | the PA8000, PA8500 and PA8600 processors. | |
24e8e380 | 226 | |
c71882ca PG |
227 | To build full perl using the supplied Configure script and |
228 | makefiles, change to the "vos" subdirectory and type the command | |
229 | "compile_full_perl" or "start_process compile_full_perl". This | |
c17baaa1 | 230 | will configure, build, and test perl. |
9a997319 | 231 | |
050dfae0 | 232 | =head2 Installing Perl 5 on VOS |
9a997319 | 233 | |
050dfae0 | 234 | =over 4 |
24e8e380 | 235 | |
050dfae0 | 236 | =item 1 |
24e8e380 | 237 | |
050dfae0 | 238 | If you have built perl using the Configure script, ensure that |
cc07ed0b | 239 | you have modify permission to C<< >system>ported >> and type |
9a997319 | 240 | |
050dfae0 | 241 | gmake install |
24e8e380 | 242 | |
050dfae0 | 243 | =item 2 |
24e8e380 | 244 | |
050dfae0 | 245 | If you have built perl using any of the other methods, type |
9a997319 | 246 | |
050dfae0 | 247 | install_perl -processor PROCESSOR -name NAME |
24e8e380 | 248 | |
050dfae0 PG |
249 | where PROCESSOR is mc68020, i80860, pa7100, or pa8000, as |
250 | appropriate, and NAME is perl or perl5, according to which name | |
251 | you wish to use. | |
24e8e380 | 252 | |
050dfae0 PG |
253 | This command macro will install perl and all of its related |
254 | files in the proper directories. | |
255 | ||
256 | =item 3 | |
9a997319 JH |
257 | |
258 | While there are currently no architecture-specific | |
259 | extensions or modules distributed with perl, the following | |
260 | directories can be used to hold such files: | |
24e8e380 | 261 | |
050dfae0 PG |
262 | >system>ported>lib>perl5>5.8.0>68k |
263 | >system>ported>lib>perl5>5.8.0>860 | |
264 | >system>ported>lib>perl5>5.8.0>7100 | |
265 | >system>ported>lib>perl5>5.8.0>8000 | |
24e8e380 | 266 | |
050dfae0 | 267 | =item 4 |
9a997319 JH |
268 | |
269 | Site-specific perl extensions and modules can be installed in one of | |
270 | two places. Put architecture-independent files into: | |
24e8e380 | 271 | |
050dfae0 | 272 | >system>ported>lib>perl5>site_perl>5.8.0 |
24e8e380 | 273 | |
050dfae0 PG |
274 | Put site-specific architecture-dependent files into one of the |
275 | following directories: | |
24e8e380 | 276 | |
050dfae0 PG |
277 | >system>ported>lib>perl5>site_perl>5.8.0>68k |
278 | >system>ported>lib>perl5>site_perl>5.8.0>860 | |
279 | >system>ported>lib>perl5>site_perl>5.8.0>7100 | |
280 | >system>ported>lib>perl5>site_perl>5.8.0>8000 | |
24e8e380 | 281 | |
050dfae0 | 282 | =item 5 |
9a997319 JH |
283 | |
284 | You can examine the @INC variable from within a perl program | |
285 | to see the order in which Perl searches these directories. | |
495c5fdc | 286 | |
9a997319 JH |
287 | =back |
288 | ||
289 | =head1 USING PERL IN VOS | |
290 | ||
a83b6f46 | 291 | =head2 Unimplemented Features of Perl on VOS |
495c5fdc | 292 | |
5b8c1387 JH |
293 | If perl is built with the alpha version of VOS POSIX.1 support |
294 | and if it attempts to call an unimplemented VOS POSIX.1 | |
295 | function, it will print a fatal error message and enter the VOS | |
296 | debugger. This error is not recoverable. See vos_dummies.c for | |
297 | a list of the unimplemented POSIX.1 functions. To see what | |
298 | functions are unimplemented and what the error message looks | |
299 | like, compile and execute "test_vos_dummies.c". | |
24e8e380 | 300 | |
a83b6f46 | 301 | =head2 Restrictions of Perl on VOS |
495c5fdc | 302 | |
24e8e380 GS |
303 | This port of Perl version 5 to VOS prefers Unix-style, |
304 | slash-separated pathnames over VOS-style greater-than-separated | |
305 | pathnames. VOS-style pathnames should work in most contexts, but | |
306 | if you have trouble, replace all greater-than characters by slash | |
307 | characters. Because the slash character is used as a pathname | |
308 | delimiter, Perl cannot process VOS pathnames containing a slash | |
309 | character in a directory or file name; these must be renamed. | |
495c5fdc | 310 | |
24e8e380 GS |
311 | This port of Perl also uses Unix-epoch date values internally. |
312 | As long as you are dealing with ASCII character string | |
313 | representations of dates, this should not be an issue. The | |
314 | supported epoch is January 1, 1980 to January 17, 2038. | |
495c5fdc | 315 | |
24e8e380 GS |
316 | See the file pod/perlport.pod for more information about the VOS |
317 | port of Perl. | |
495c5fdc | 318 | |
11d33b1d PG |
319 | =head2 Handling of underflow and overflow |
320 | ||
e6ae7084 JH |
321 | Prior to VOS Release 14.7.0, VOS does not support automatically |
322 | mapping overflowed floating-point values to +infinity, nor | |
323 | automatically mapping underflowed floating-point values to zero, | |
324 | unlike many other platforms. The Perl pack function has been | |
325 | modified to perform such mapping in software on VOS. Performing | |
326 | other floating-point computations that underflow or overflow | |
327 | will probably result in SIGFPE. Don't push your luck. | |
328 | ||
329 | As of VOS Release 14.7.0, the VOS POSIX runtime sets up the | |
330 | PA-RISC hardware floating-point status register so that the | |
331 | overflow and underflow exceptions do not trap, but instead | |
332 | automatically convert the result to infinity or zero, as | |
333 | appropriate. As of this writing, there are still floating-point | |
334 | operations that can trap, for example, subtracting two infinite | |
335 | values. This is recorded as suggestion posix-1022, which is not | |
336 | yet fixed. | |
11d33b1d PG |
337 | |
338 | =head1 TEST STATUS | |
339 | ||
c17baaa1 PG |
340 | When Perl 5.8.3 is built using the native build process on VOS |
341 | Release 14.7.0 and GNU C++/GNU Tools 2.0.2a, all but three | |
e6ae7084 JH |
342 | attempted tests either pass or result in TODO (ignored) |
343 | failures. The tests that fail are: | |
344 | ||
c17baaa1 PG |
345 | t/io/tell.t, test 28 |
346 | t/op/pack.t, test 39 | |
347 | lib/Net/ing/t/450_service.t, test 8 | |
11d33b1d | 348 | |
9a997319 | 349 | =head1 SUPPORT STATUS |
495c5fdc | 350 | |
495c5fdc | 351 | I'm offering this port "as is". You can ask me questions, but I |
5b8c1387 | 352 | can't guarantee I'll be able to answer them. There are some |
24e8e380 GS |
353 | excellent books available on the Perl language; consult a book |
354 | seller. | |
495c5fdc | 355 | |
c17baaa1 PG |
356 | If you want a supported version of perl for VOS, purchase the |
357 | VOS GNU C++ and GNU Tools Release 2.0.1 (or later) product from | |
358 | Stratus Technologies, along with a support contract (or from | |
359 | anyone else who will sell you support). | |
050dfae0 | 360 | |
9a997319 JH |
361 | =head1 AUTHOR |
362 | ||
4f3de37c | 363 | Paul Green (Paul.Green@stratus.com) |
9a997319 JH |
364 | |
365 | =head1 LAST UPDATE | |
366 | ||
c17baaa1 | 367 | January 15, 2004 |
9a997319 JH |
368 | |
369 | =cut |