Missing argument.
[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
4f3de37c 11This is a port of Perl version 5 to VOS. Perl is a scripting or
12macro language that is popular on many systems. See L<perlbook>
13for a number of good books on Perl.
14
15These are instructions for building Perl from source. Most people can
16simply download a pre-compiled distribution from the VOS anonymous FTP
17site. If you are running VOS Release 14.2.0 or earlier, download Perl
18from ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html. If you are
19running VOS Release 14.3.0 or later, download Perl from
20ftp://ftp.stratus.com/pub/vos/posix/ga/ga.html. Instructions for
21unbundling the Perl distribution file are at
22ftp://ftp.stratus.com/pub/vos/utility/utility.html.
495c5fdc 23
9a997319 24=head2 Stratus POSIX Support
495c5fdc 25
5b8c1387 26Note that there are two different implementations of POSIX.1
27support on VOS. There is an alpha version of POSIX that is
28available from the Stratus anonymous ftp site
37a78d01 29(ftp://ftp.stratus.com/pub/vos/posix/). There is
8b204b88 30a generally-available version of POSIX that comes with the VOS
31Standard C Compiler or VOS C runtime in VOS Release 14.3.0 or
32higher. This port of perl will compile and bind with either
5b8c1387 33version of POSIX.
34
35Most of the Perl features should work on VOS regardless of which
36version of POSIX that you are using. However, the alpha version
37of POSIX is missing a number of key functions, and therefore any
495c5fdc 38attempt by perl.pm to call the following unimplemented POSIX
39functions will result in an error message and an immediate and
24e8e380 40fatal call to the VOS debugger. They are "dup", "fork", and
8b204b88 41"waitpid". The lack of these functions prevents you from
42starting VOS commands and grabbing their output in perl. The
43workaround is to run the commands outside of perl, then have perl
44process the output file. These functions are all available in
45the generally-available version of POSIX.
24e8e380 46
9a997319 47=head1 INSTALLING PERL IN VOS
48
49=head2 Compiling Perl 5 on VOS
495c5fdc 50
495c5fdc 51Before you can build Perl 5 on VOS, you need to have or acquire the
52following additional items.
53
9a997319 54=over 5
55
56=item 1
57
0d6ca59a 58The VOS Standard C Compiler (or the VOS Standard C
59Cross-Compiler) and the VOS C Runtime. If you are using
60the generally-available version of POSIX support, you may
d1be9408 61instead use the VOS GNU C/C++ Compiler. These are
0d6ca59a 62standard Stratus products.
9a997319 63
64=item 2
65
66Either the VOS OS TCP/IP or STCP product set. If you are
67building with the alpha version of POSIX you need the OS
68TCP/IP product set. If you are building with the
69generally-available version of POSIX you need the STCP
70product set. These are standard Stratus products.
71
72=item 3
73
74Either the alpha or generally-available version of the VOS
75POSIX.1 environment.
76
77The alpha version of POSIX.1 support is available on the
78Stratus FTP site. Login anonymously to ftp.stratus.com and
79get the file /pub/vos/posix/alpha/posix.save.evf.gz in
80binary file-transfer mode. Or use the Uniform Resource
81Locator (URL)
37a78d01 82ftp://ftp.stratus.com/pub/vos/posix/alpha/posix.save.evf.gz from
9a997319 83your web browser. Instructions for unbundling this file
84are at ftp://ftp.stratus.com/pub/vos/utility/utility.html.
85This is not a standard Stratus product.
86
0d6ca59a 87In VOS Release 14.3.0, the generally-available version of
88POSIX.1 support is bundled with the VOS Standard C compiler
89(or Standard C Cross-Compiler). In VOS Release 14.4.0 or
90higher, it is also bundled with the VOS C Runtime. These
91are standard Stratus products.
9a997319 92
93=item 4
94
95You must compile this version of Perl 5 on VOS Release
9614.1.0 or higher because some of the perl source files
97contain more than 32,767 source lines. Due to VOS
98release-compatibility rules, this port of perl may not
99execute on VOS Release 12 or earlier.
100
0d6ca59a 101=item 5
102
8b204b88 103If you are using the generally-available version of VOS POSIX
104support, then you should also acquire the VOS GNU C/C++ Compiler
105and GNU Tools product because it provides many common Unix or
106POSIX commands. When perl is built with this version of POSIX
107support, it assumes that it can find "bash", "sed" and other
108POSIX-compatible commands in the directory
109/system/gnu_library/bin.
0d6ca59a 110
9a997319 111=back
24e8e380 112
113To build perl 5, change to the "vos" subdirectory and type the
114command "compile_perl -processor X", where X is the processor
115type (mc68020, i80860, pa7100, pa8000) that you wish to use.
5b8c1387 116Note that the generally-available version of POSIX.1 support is
117not available for the mc68020 or i80860 processors.
118
0d6ca59a 119Use the "-version alpha" control argument to build perl with
120the alpha version of POSIX support, and use the "-version
121ga" control argument to build it with the
122generally-available version of POSIX. The default is "ga".
123
124Use the "-compiler cc" control argument to build perl with
125the VOS Standard C compiler. Use the "-compiler gcc"
126control argument to build it with the GNU GCC compiler. The
127default is "cc".
128
5b8c1387 129You must have purchased the VOS Standard C Cross Compiler in
130order to compile perl for a processor type that is different
131from the processor type of the module.
132
24e8e380 133Note that code compiled for the pa7100 processor type can
5b8c1387 134execute on the PA7100, PA8000, PA8500 and PA8600 processors, and
135that code compiled for the pa8000 processor type can execute on
136the PA8000, PA8500 and PA8600 processors.
24e8e380 137
9a997319 138=head2 Installing Perl 5 on VOS
24e8e380 139
9a997319 140=over 4
24e8e380 141
9a997319 142=item 1
143
144Create the directory >system>ported>command_library.
145
146=item 2
147
148Copy the appropriate version of the perl program module to
149this directory. For example, with your current directory
150set to the top-level directory of Perl 5, to install the
151executable program module for the Motorola 68K
152architecture, enter:
24e8e380 153
154 !copy_file vos>obj>perl.pm >system>ported>command_library>*
155
9a997319 156(If you wish to use both Perl version 4 and Perl version 5,
157you must give them different names; for example, perl.pm
158and perl5.pm).
159
160=item 3
24e8e380 161
9a997319 162Create the directory >system>ported>perl>lib.
24e8e380 163
9a997319 164=item 4
165
166Copy all of the files and subdirectories from the lib
167subdirectory into this new directory. For example, with
168the current directory set to the top-level directory of the
169perl distribution, enter:
24e8e380 170
5b8c1387 171 !copy_dir lib >system>ported>perl>lib>5.7
24e8e380 172
9a997319 173=item 5
174
175While there are currently no architecture-specific
176extensions or modules distributed with perl, the following
177directories can be used to hold such files:
24e8e380 178
5b8c1387 179 >system>ported>perl>lib>5.7.68k
180 >system>ported>perl>lib>5.7.860
181 >system>ported>perl>lib>5.7.7100
182 >system>ported>perl>lib>5.7.8000
24e8e380 183
9a997319 184=item 6
185
186Site-specific perl extensions and modules can be installed in one of
187two places. Put architecture-independent files into:
24e8e380 188
5b8c1387 189 >system>ported>perl>lib>site>5.7
24e8e380 190
9a997319 191Put architecture-dependent files into one of the following
192directories:
24e8e380 193
5b8c1387 194 >system>ported>perl>lib>site>5.7.68k
195 >system>ported>perl>lib>site>5.7.860
196 >system>ported>perl>lib>site>5.7.7100
197 >system>ported>perl>lib>site>5.7.8000
24e8e380 198
9a997319 199=item 7
200
201You can examine the @INC variable from within a perl program
202to see the order in which Perl searches these directories.
495c5fdc 203
9a997319 204=back
205
206=head1 USING PERL IN VOS
207
a83b6f46 208=head2 Unimplemented Features of Perl on VOS
495c5fdc 209
5b8c1387 210If perl is built with the alpha version of VOS POSIX.1 support
211and if it attempts to call an unimplemented VOS POSIX.1
212function, it will print a fatal error message and enter the VOS
213debugger. This error is not recoverable. See vos_dummies.c for
214a list of the unimplemented POSIX.1 functions. To see what
215functions are unimplemented and what the error message looks
216like, compile and execute "test_vos_dummies.c".
24e8e380 217
a83b6f46 218=head2 Restrictions of Perl on VOS
495c5fdc 219
24e8e380 220This port of Perl version 5 to VOS prefers Unix-style,
221slash-separated pathnames over VOS-style greater-than-separated
222pathnames. VOS-style pathnames should work in most contexts, but
223if you have trouble, replace all greater-than characters by slash
224characters. Because the slash character is used as a pathname
225delimiter, Perl cannot process VOS pathnames containing a slash
226character in a directory or file name; these must be renamed.
495c5fdc 227
24e8e380 228This port of Perl also uses Unix-epoch date values internally.
229As long as you are dealing with ASCII character string
230representations of dates, this should not be an issue. The
231supported epoch is January 1, 1980 to January 17, 2038.
495c5fdc 232
24e8e380 233See the file pod/perlport.pod for more information about the VOS
234port of Perl.
495c5fdc 235
9a997319 236=head1 SUPPORT STATUS
495c5fdc 237
495c5fdc 238I'm offering this port "as is". You can ask me questions, but I
5b8c1387 239can't guarantee I'll be able to answer them. There are some
24e8e380 240excellent books available on the Perl language; consult a book
241seller.
495c5fdc 242
9a997319 243=head1 AUTHOR
244
4f3de37c 245Paul Green (Paul.Green@stratus.com)
9a997319 246
247=head1 LAST UPDATE
248
4f3de37c 249November 29, 2001
9a997319 250
251=cut