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