This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Various updates and fixes to some of the SysV IPC ops and their tests
[perl5.git] / README.bs2000
CommitLineData
c2e66d9e 1This document is written in pod format hence there are punctuation
d1be9408 2characters in odd places. Do not worry, you've apparently got the
c2e66d9e
GS
3ASCII->EBCDIC translation worked out correctly. You can read more
4about pod in pod/perlpod.pod or the short summary in the INSTALL file.
5
6=head1 NAME
7
75b25ca1 8perlbs2000 - building and installing Perl for BS2000.
c2e66d9e 9
2b7f2baa 10B<This document needs to be updated, but we don't know what it should say.
8166b4e0 11Please submit comments to L<https://github.com/Perl/perl5/issues>.>
2b7f2baa 12
c2e66d9e
GS
13=head1 SYNOPSIS
14
15This document will help you Configure, build, test and install Perl
16on BS2000 in the POSIX subsystem.
17
18=head1 DESCRIPTION
19
20This is a ported perl for the POSIX subsystem in BS2000 VERSION OSD
453189b6
TD
21V3.1A or later. It may work on other versions, but we started porting
22and testing it with 3.1A and are currently using Version V4.0A.
a1a0e61e
TD
23
24You may need the following GNU programs in order to install perl:
25
a83b6f46 26=head2 gzip on BS2000
a1a0e61e
TD
27
28We used version 1.2.4, which could be installed out of the box with
29one failure during 'make check'.
30
a83b6f46 31=head2 bison on BS2000
a1a0e61e
TD
32
33The yacc coming with BS2000 POSIX didn't work for us. So we had to
34use bison. We had to make a few changes to perl in order to use the
35pure (reentrant) parser of bison. We used version 1.25, but we had to
453189b6
TD
36add a few changes due to EBCDIC. See below for more details
37concerning yacc.
a1a0e61e 38
a83b6f46 39=head2 Unpacking Perl Distribution on BS2000
a1a0e61e
TD
40
41To extract an ASCII tar archive on BS2000 POSIX you need an ASCII
42filesystem (we used the mountpoint /usr/local/ascii for this). Now
c2e66d9e
GS
43you extract the archive in the ASCII filesystem without
44I/O-conversion:
a1a0e61e
TD
45
46cd /usr/local/ascii
47export IO_CONVERSION=NO
48gunzip < /usr/local/src/perl.tar.gz | pax -r
49
50You may ignore the error message for the first element of the archive
51(this doesn't look like a tar archive / skipping to next file...),
c2e66d9e 52it's only the directory which will be created automatically anyway.
a1a0e61e
TD
53
54After extracting the archive you copy the whole directory tree to your
c2e66d9e 55EBCDIC filesystem. B<This time you use I/O-conversion>:
a1a0e61e
TD
56
57cd /usr/local/src
58IO_CONVERSION=YES
59cp -r /usr/local/ascii/perl5.005_02 ./
60
a83b6f46 61=head2 Compiling Perl on BS2000
a1a0e61e 62
453189b6
TD
63There is a "hints" file for BS2000 called hints.posix-bc (because
64posix-bc is the OS name given by `uname`) that specifies the correct
65values for most things. The major problem is (of course) the EBCDIC
66character set. We have german EBCDIC version.
a1a0e61e
TD
67
68Because of our problems with the native yacc we used GNU bison to
93fb2ac3
JH
69generate a pure (=reentrant) parser for perly.y. So our yacc is
70really the following script:
a1a0e61e 71
93fb2ac3
JH
72-----8<-----/usr/local/bin/yacc-----8<-----
73#! /usr/bin/sh
a1a0e61e 74
93fb2ac3
JH
75# Bison as a reentrant yacc:
76
77# save parameters:
78params=""
79while [[ $# -gt 1 ]]; do
80 params="$params $1"
81 shift
82done
83
84# add flag %pure_parser:
85
86tmpfile=/tmp/bison.$$.y
87echo %pure_parser > $tmpfile
88cat $1 >> $tmpfile
89
90# call bison:
91
92echo "/usr/local/bin/bison --yacc $params $1\t\t\t(Pure Parser)"
93/usr/local/bin/bison --yacc $params $tmpfile
94
95# cleanup:
96
97rm -f $tmpfile
98-----8<----------8<-----
99
100We still use the normal yacc for a2p.y though!!! We made a softlink
101called byacc to distinguish between the two versions:
102
103ln -s /usr/bin/yacc /usr/local/bin/byacc
a1a0e61e 104
c2e66d9e
GS
105We build perl using GNU make. We tried the native make once and it
106worked too.
a1a0e61e 107
a83b6f46 108=head2 Testing Perl on BS2000
a1a0e61e 109
c2e66d9e
GS
110We still got a few errors during C<make test>. Some of them are the
111result of using bison. Bison prints I<parser error> instead of I<syntax
112error>, so we may ignore them. The following list shows
a1a0e61e
TD
113our errors, your results may differ:
114
c8e8bf6a
GS
115op/numconvert.......FAILED tests 1409-1440
116op/regexp...........FAILED tests 483, 496
117op/regexp_noamp.....FAILED tests 483, 496
a1a0e61e 118pragma/overload.....FAILED tests 152-153, 170-171
c8e8bf6a
GS
119pragma/warnings.....FAILED tests 14, 82, 129, 155, 192, 205, 207
120lib/bigfloat........FAILED tests 351-352, 355
121lib/bigfltpm........FAILED tests 354-355, 358
122lib/complex.........FAILED tests 267, 487
123lib/dumper..........FAILED tests 43, 45
124Failed 11/231 test scripts, 95.24% okay. 57/10595 subtests failed, 99.46% okay.
a1a0e61e 125
a83b6f46 126=head2 Installing Perl on BS2000
a1a0e61e
TD
127
128We have no nroff on BS2000 POSIX (yet), so we ignored any errors while
129installing the documentation.
130
131
a83b6f46 132=head2 Using Perl in the Posix-Shell of BS2000
a1a0e61e
TD
133
134BS2000 POSIX doesn't support the shebang notation
c2e66d9e 135(C<#!/usr/local/bin/perl>), so you have to use the following lines
a1a0e61e
TD
136instead:
137
138: # use perl
139 eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
188e64dd 140 if 0; # ^ Run only under a shell
c2e66d9e 141
453189b6
TD
142=head2 Using Perl in "native" BS2000
143
144We don't have much experience with this yet, but try the following:
145
146Copy your Perl executable to a BS2000 LLM using bs2cp:
147
148C<bs2cp /usr/local/bin/perl 'bs2:perl(perl,l)'>
149
150Now you can start it with the following (SDF) command:
151
152C</START-PROG FROM-FILE=*MODULE(PERL,PERL),PROG-MODE=*ANY,RUN-MODE=*ADV>
153
154First you get the BS2000 commandline prompt ('*'). Here you may enter
155your parameters, e.g. C<-e 'print "Hello World!\\n";'> (note the
156double backslash!) or C<-w> and the name of your Perl script.
d1be9408 157Filenames starting with C</> are searched in the Posix filesystem,
453189b6
TD
158others are searched in the BS2000 filesystem. You may even use
159wildcards if you put a C<%> in front of your filename (e.g. C<-w
160checkfiles.pl %*.c>). Read your C/C++ manual for additional
161possibilities of the commandline prompt (look for
162PARAMETER-PROMPTING).
163
a83b6f46 164=head2 Floating point anomalies on BS2000
35a77668
PP
165
166There appears to be a bug in the floating point implementation on BS2000 POSIX
167systems such that calling int() on the product of a number and a small
168magnitude number is not the same as calling int() on the quotient of
169that number and a large magnitude number. For example, in the following
170Perl code:
171
172 my $x = 100000.0;
173 my $y = int($x * 1e-5) * 1e5; # '0'
174 my $z = int($x / 1e+5) * 1e5; # '100000'
175 print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000
176
177Although one would expect the quantities $y and $z to be the same and equal
178to 100000 they will differ and instead will be 0 and 100000 respectively.
179
756189a5
JH
180=head2 Using PerlIO and different encodings on ASCII and EBCDIC partitions
181
182Since version 5.8 Perl uses the new PerlIO on BS2000. This enables
183you using different encodings per IO channel. For example you may use
184
185 use Encode;
186 open($f, ">:encoding(ascii)", "test.ascii");
187 print $f "Hello World!\n";
188 open($f, ">:encoding(posix-bc)", "test.ebcdic");
189 print $f "Hello World!\n";
190 open($f, ">:encoding(latin1)", "test.latin1");
191 print $f "Hello World!\n";
192 open($f, ">:encoding(utf8)", "test.utf8");
193 print $f "Hello World!\n";
194
195to get two files containing "Hello World!\n" in ASCII, EBCDIC, ISO
196Latin-1 (in this example identical to ASCII) respective UTF-EBCDIC (in
197this example identical to normal EBCDIC). See the documentation of
198Encode::PerlIO for details.
199
200As the PerlIO layer uses raw IO internally, all this totally ignores
201the type of your filesystem (ASCII or EBCDIC) and the IO_CONVERSION
202environment variable. If you want to get the old behavior, that the
203BS2000 IO functions determine conversion depending on the filesystem
204PerlIO still is your friend. You use IO_CONVERSION as usual and tell
205Perl, that it should use the native IO layer:
206
207 export IO_CONVERSION=YES
208 export PERLIO=stdio
209
210Now your IO would be ASCII on ASCII partitions and EBCDIC on EBCDIC
211partitions. See the documentation of PerlIO (without C<Encode::>!)
f858446f 212for further possibilities.
756189a5 213
c2e66d9e
GS
214=head1 AUTHORS
215
216Thomas Dorner
217
218=head1 SEE ALSO
219
220L<INSTALL>, L<perlport>.
221
222=head2 Mailing list
223
043fec90 224If you are interested in the z/OS (formerly known as OS/390)
3f66d419
JH
225and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
226To subscribe, send an empty message to perl-mvs-subscribe@perl.org.
c2e66d9e 227
3f66d419 228See also:
c2e66d9e 229
fdee78a1 230 https://lists.perl.org/list/perl-mvs.html
3f66d419
JH
231
232There are web archives of the mailing list at:
233
cba88c42 234 https://www.nntp.perl.org/group/perl.mvs/
c2e66d9e
GS
235
236=head1 HISTORY
237
238This document was originally written by Thomas Dorner for the 5.005
239release of Perl.
240
241This document was podified for the 5.6 release of perl 11 July 2000.
242
243=cut