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