Test case for #10433/#10424.
[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 is a port of Perl version 5, revision 7, to VOS.  Perl is a
12 scripting or macro language that is popular on many systems.  See your
13 local 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
21 is a generally-available version of POSIX that comes with the
22 VOS Standard C compiler and C runtime in VOS Release 14.3.0 or
23 higher.  This port of POSIX 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 pretty much prevents you
33 from starting VOS commands and grabbing their output in perl.
34 The workaround is to run the commands outside of perl, then have
35 perl process the output file.  These functions are all available
36 in 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 and Runtime, or the VOS Standard C
50 Cross-Compiler.  This is a standard Stratus product.
51
52 =item 2
53
54 Either the VOS OS TCP/IP or STCP product set.  If you are
55 building with the alpha version of POSIX you need the OS
56 TCP/IP product set.  If you are building with the
57 generally-available version of POSIX you need the STCP
58 product set.  These are standard Stratus products.
59
60 =item 3
61
62 Either the alpha or generally-available version of the VOS
63 POSIX.1 environment.
64
65 The alpha version of POSIX.1 support is available on the
66 Stratus FTP site.  Login anonymously to ftp.stratus.com and
67 get the file /pub/vos/posix/alpha/posix.save.evf.gz in
68 binary file-transfer mode.  Or use the Uniform Resource
69 Locator (URL)
70 ftp://ftp.stratus.com/pub/vos/alpha/posix.save.evf.gz from
71 your web browser.  Instructions for unbundling this file
72 are at ftp://ftp.stratus.com/pub/vos/utility/utility.html.
73 This is not a standard Stratus product.
74
75 The generally-available version of POSIX.1 support is
76 bundled with the VOS Standard C compiler and Runtime (or
77 Cross-Compiler) in VOS Release 14.3.0 or higher.  This is a
78 standard Stratus product.
79
80 =item 4
81
82 You must compile this version of Perl 5 on VOS Release
83 14.1.0 or higher because some of the perl source files
84 contain more than 32,767 source lines.  Due to VOS
85 release-compatibility rules, this port of perl may not
86 execute on VOS Release 12 or earlier.
87
88 =back
89
90 To build perl 5, change to the "vos" subdirectory and type the
91 command "compile_perl -processor X", where X is the processor
92 type (mc68020, i80860, pa7100, pa8000) that you wish to use.
93 Note that the generally-available version of POSIX.1 support is
94 not available for the mc68020 or i80860 processors.
95
96 You must have purchased the VOS Standard C Cross Compiler in
97 order to compile perl for a processor type that is different
98 from the processor type of the module.
99
100 Note that code compiled for the pa7100 processor type can
101 execute on the PA7100, PA8000, PA8500 and PA8600 processors, and
102 that code compiled for the pa8000 processor type can execute on
103 the PA8000, PA8500 and PA8600 processors.
104
105 =head2 Installing Perl 5 on VOS
106
107 =over 4
108
109 =item 1
110
111 Create the directory >system>ported>command_library.
112
113 =item 2
114
115 Copy the appropriate version of the perl program module to
116 this directory.  For example, with your current directory
117 set to the top-level directory of Perl 5, to install the
118 executable program module for the Motorola 68K
119 architecture, enter:
120
121           !copy_file vos>obj>perl.pm >system>ported>command_library>*
122
123 (If you wish to use both Perl version 4 and Perl version 5,
124 you must give them different names; for example, perl.pm
125 and perl5.pm).
126
127 =item 3
128
129 Create the directory >system>ported>perl>lib.
130
131 =item 4
132
133 Copy all of the files and subdirectories from the lib
134 subdirectory into this new directory.  For example, with
135 the current directory set to the top-level directory of the
136 perl distribution, enter:
137
138           !copy_dir lib >system>ported>perl>lib>5.7
139
140 =item 5
141
142 While there are currently no architecture-specific
143 extensions or modules distributed with perl, the following
144 directories can be used to hold such files:
145
146           >system>ported>perl>lib>5.7.68k
147           >system>ported>perl>lib>5.7.860
148           >system>ported>perl>lib>5.7.7100
149           >system>ported>perl>lib>5.7.8000
150
151 =item 6
152
153 Site-specific perl extensions and modules can be installed in one of
154 two places.  Put architecture-independent files into:
155
156           >system>ported>perl>lib>site>5.7
157
158 Put architecture-dependent files into one of the following
159 directories:
160
161           >system>ported>perl>lib>site>5.7.68k
162           >system>ported>perl>lib>site>5.7.860
163           >system>ported>perl>lib>site>5.7.7100
164           >system>ported>perl>lib>site>5.7.8000
165
166 =item 7
167
168 You can examine the @INC variable from within a perl program
169 to see the order in which Perl searches these directories.
170
171 =back
172
173 =head1 USING PERL IN VOS
174
175 =head2 Unimplemented Features
176
177 If perl is built with the alpha version of VOS POSIX.1 support
178 and if it attempts to call an unimplemented VOS POSIX.1
179 function, it will print a fatal error message and enter the VOS
180 debugger.  This error is not recoverable.  See vos_dummies.c for
181 a list of the unimplemented POSIX.1 functions.  To see what
182 functions are unimplemented and what the error message looks
183 like, compile and execute "test_vos_dummies.c".
184
185 =head2 Restrictions
186
187 This port of Perl version 5 to VOS prefers Unix-style,
188 slash-separated pathnames over VOS-style greater-than-separated
189 pathnames.  VOS-style pathnames should work in most contexts, but
190 if you have trouble, replace all greater-than characters by slash
191 characters.  Because the slash character is used as a pathname
192 delimiter, Perl cannot process VOS pathnames containing a slash
193 character in a directory or file name; these must be renamed.
194
195 This port of Perl also uses Unix-epoch date values internally.
196 As long as you are dealing with ASCII character string
197 representations of dates, this should not be an issue.  The
198 supported epoch is January 1, 1980 to January 17, 2038.
199
200 See the file pod/perlport.pod for more information about the VOS
201 port of Perl.
202
203 =head1 SUPPORT STATUS
204
205 I'm offering this port "as is".  You can ask me questions, but I
206 can't guarantee I'll be able to answer them.  There are some
207 excellent books available on the Perl language; consult a book
208 seller.
209
210 =head1 AUTHOR
211
212 Paul Green (Paul_Green@stratus.com)
213
214 =head1 LAST UPDATE
215
216 October 24, 2000
217
218 =cut