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