binmode(FH); to act like binmode(FH,":bytes") as well as
[p5sagit/p5-mst-13.2.git] / README.vos
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
10
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.
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
19 from ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html  If you are
20 running VOS Release 14.3.0 or later, download Perl from
21 ftp://ftp.stratus.com/pub/vos/posix/ga/ga.html  Instructions for
22 unbundling the Perl distribution file are at
23 ftp://ftp.stratus.com/pub/vos/utility/utility.html
24
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
27 of the VOS GNU C++ and GNU Tools product from Stratus
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
35 architecture of you Stratus hardware platform.
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
47 does not contain the complete perl functionality.
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
61 does not contain the complete perl functionality.
62
63 You must build perl with the compile_perl.cm command macro found
64 in the vos subdirectory.
65
66 =item 3
67
68 If you have a Stratus Continuum (PARISC-based) platform that is
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
76 does not contain the complete perl functionality.
77
78 You must build perl with the compile_perl.cm command macro found
79 in the vos subdirectory.
80
81 =item 4
82
83 If you have a Stratus Continuum (PARISC-based) platform that is
84 running VOS Release 14.3.0 through VOS Release 14.4.1, you must
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
91 does not contain the complete perl functionality.
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
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
105 C/C++ and GNU Tools Release 2.0.1 product.  You must build full
106 perl on VOS Release 14.5.0 (or later) on a Continuum platform.
107
108 You must build full perl with the compile_full_perl.cm command
109 macro found in the vos subdirectory.
110
111 =back
112
113 =head2 Stratus POSIX Support
114
115 Note that there are two different implementations of POSIX.1
116 support on VOS.  There is an alpha version of POSIX that is
117 available from the Stratus anonymous ftp site
118 ( ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html ).  There
119 is a generally-available version of POSIX that comes with VOS
120 Release 14.3.0 or higher.  This port of POSIX will compile and
121 bind with either version of POSIX.
122
123 Most of the Perl features should work on VOS regardless of which
124 version of POSIX that you are using.  However, the alpha version
125 of POSIX is missing a number of key functions, and therefore any
126 attempt by perl.pm to call the following unimplemented POSIX
127 functions will result in an error message and an immediate and
128 fatal call to the VOS debugger.  They are "dup", "fork", and
129 "waitpid".  The lack of these functions prevents you from
130 starting VOS commands and grabbing their output in perl.  The
131 workaround is to run the commands outside of perl, then have perl
132 process the output file.  These functions are all available in
133 the generally-available version of POSIX.
134
135 =head1 INSTALLING PERL IN VOS
136
137 =head2 Compiling Perl 5 on VOS
138
139 Before you can build Perl 5 on VOS, you need to have or acquire the
140 following additional items.
141
142 =over 5
143
144 =item 1
145
146 The VOS Standard C Compiler (or the VOS Standard C
147 Cross-Compiler) and the VOS C Runtime.  If you are using
148 the generally-available version of POSIX support, you may
149 instead use the VOS GNU C/C++ Compiler.  These are
150 standard Stratus products.
151
152 =item 2
153
154 Either the VOS OS TCP/IP or STCP product set.  If you are
155 building with the alpha version of POSIX you need the OS
156 TCP/IP product set.  If you are building with the
157 generally-available version of POSIX you need the STCP
158 product set.  These are standard Stratus products.
159
160 =item 3
161
162 Either the alpha or generally-available version of the VOS
163 POSIX.1 environment.
164
165 The alpha version of POSIX.1 support is available on the
166 Stratus FTP site.  Login anonymously to ftp.stratus.com and
167 get the file /pub/vos/posix/alpha/posix.save.evf.gz in
168 binary file-transfer mode.  Or use the Uniform Resource
169 Locator (URL)
170 ftp://ftp.stratus.com/pub/vos/posix/alpha/posix.save.evf.gz from
171 your web browser.  Instructions for unbundling this file
172 are at ftp://ftp.stratus.com/pub/vos/utility/utility.html
173 This is not a standard Stratus product.
174
175 In VOS Release 14.3.0, the generally-available version of
176 POSIX.1 support is bundled with the VOS Standard C compiler
177 (or Standard C Cross-Compiler).  In VOS Release 14.4.0 or
178 higher, it is also bundled with the VOS C Runtime.  These
179 are standard Stratus products.
180
181 =item 4
182
183 You must compile this version of Perl 5 on VOS Release
184 14.1.0 or higher because some of the perl source files
185 contain more than 32,767 source lines.  Due to VOS
186 release-compatibility rules, this port of perl may not
187 execute on VOS Release 12 or earlier.
188
189 =item 5
190
191 If you are using the generally-available version of VOS POSIX
192 support, then you should also acquire the VOS GNU C/C++ Compiler
193 and GNU Tools product.  When perl is built with this version of
194 POSIX support, it assumes that it can find "bash", "sed" and
195 other POSIX-compatible commands in the directory
196 /system/gnu_library/bin.
197
198 =back
199
200 To build perl using the supplied VOS command macros, change to
201 the "vos" subdirectory and type the command "compile_perl
202 -processor X", where X is the processor type (mc68020, i80860,
203 pa7100, pa8000) that you wish to use.  Note that the
204 generally-available version of POSIX.1 support is not available
205 for the mc68020 or i80860 processors.
206
207 Use the "-version alpha" control argument to build perl with
208 the alpha version of POSIX support, and use the "-version
209 ga" control argument to build it with the
210 generally-available version of POSIX.  The default is "ga".
211
212 Use the "-compiler cc" control argument to build perl with
213 the VOS Standard C compiler.  Use the "-compiler gcc"
214 control argument to build it with the GNU GCC compiler.  The
215 default is "cc".
216
217 You must have purchased the VOS Standard C Cross Compiler in
218 order to compile perl for a processor type that is different
219 from the processor type of the module.
220
221 Note that code compiled for the pa7100 processor type can
222 execute on the PA7100, PA8000, PA8500 and PA8600 processors, and
223 that code compiled for the pa8000 processor type can execute on
224 the PA8000, PA8500 and PA8600 processors.
225
226 To build full perl using the supplied Configure script and
227 makefiles, change to the "vos" subdirectory and type the command
228 "compile_full_perl" or "start_process compile_full_perl".  This
229 will configure, build, and test perl.  All of the test cases
230 that are executed should pass.
231
232 =head2 Installing Perl 5 on VOS
233
234 =over 4
235
236 =item 1
237
238 If you have built perl using the Configure script, ensure that
239 you have modify permission to C<< >system>ported >> and type
240
241      gmake install
242
243 =item 2
244
245 If you have built perl using any of the other methods, type
246
247      install_perl -processor PROCESSOR -name NAME
248
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.
252
253 This command macro will install perl and all of its related
254 files in the proper directories.
255
256 =item 3
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:
261
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
266
267 =item 4
268
269 Site-specific perl extensions and modules can be installed in one of
270 two places.  Put architecture-independent files into:
271
272      >system>ported>lib>perl5>site_perl>5.8.0
273
274 Put site-specific architecture-dependent files into one of the
275 following directories:
276
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
281
282 =item 5
283
284 You can examine the @INC variable from within a perl program
285 to see the order in which Perl searches these directories.
286
287 =back
288
289 =head1 USING PERL IN VOS
290
291 =head2 Unimplemented Features of Perl on VOS
292
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".
300
301 =head2 Restrictions of Perl on VOS
302
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.
310
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.
315
316 See the file pod/perlport.pod for more information about the VOS
317 port of Perl.
318
319 =head2 Handling of underflow and overflow
320
321 VOS does not support automatically mapping overflowed
322 floating-point values to +infinity, nor automatically mapping
323 underflowed floating-point values to -infinity, unlike many
324 other platforms.  The Perl pack function has been modified to
325 perform such mapping in software on VOS.  Performing other
326 floating-point computations that underflow or overflow will
327 probably result in SIGFPE.  Don't push your luck.
328
329 =head1 TEST STATUS
330
331 When Perl is built using the native build process on VOS Release
332 14.5.0 and GNU C++/GNU Tools 2.0.1, all attempted tests either
333 pass or result in TODO (ignored) failures.
334
335 =head1 SUPPORT STATUS
336
337 I'm offering this port "as is".  You can ask me questions, but I
338 can't guarantee I'll be able to answer them.  There are some
339 excellent books available on the Perl language; consult a book
340 seller.
341
342 If you want a supported version of perl for VOS, purchase the VOS
343 GNU C++ and GNU Tools Release 2.0.1 product from Stratus
344 Technologies, along with a support contract (or from anyone else
345 who will sell you support).
346
347 =head1 AUTHOR
348
349 Paul Green (Paul.Green@stratus.com)
350
351 =head1 LAST UPDATE
352
353 May 13, 2002
354
355 =cut