This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Pod cleanup for F<> and L<>
[perl5.git] / README.amiga
CommitLineData
0a753a76
PP
1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see perlpod manpage) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
c0c066b9 7perlamiga - Perl under Amiga OS
0a753a76 8
07b0e447
JH
9=head1 NOTE
10
11B<Perl 5.8.0 cannot be built in AmigaOS. You can use either the
12maintenance release Perl 5.6.1 or the development release Perl 5.7.2
13in AmigaOS. See L</"PERL 5.8.0 BROKEN IN AMIGAOS"> if you want to help
14fixing this problem.>
15
0a753a76
PP
16=head1 SYNOPSIS
17
18One can read this document in the following formats:
19
20 man perlamiga
21 multiview perlamiga.guide
22
23to list some (not all may be available simultaneously), or it may
24be read I<as is>: either as F<README.amiga>, or F<pod/perlamiga.pod>.
25
c0c066b9
JH
26A recent version of perl for the Amiga can be found at the Geek Gadgets
27section of the Aminet:
b5ab5069 28
0a31a4b2 29 http://www.aminet.net/~aminet/dev/gg
c0c066b9 30
0a753a76
PP
31=cut
32
33Contents
34
35 perlamiga - Perl under Amiga OS
36
37 NAME
38 SYNOPSIS
39 DESCRIPTION
40 - Prerequisites
41 - Starting Perl programs under AmigaOS
b971f6e4 42 - Shortcomings of Perl under AmigaOS
0a753a76
PP
43 INSTALLATION
44 Accessing documentation
45 - Manpages
46 - HTML
47 - GNU info files
48 - LaTeX docs
49 BUILD
b5ab5069 50 - Build Prerequisites
0a753a76
PP
51 - Getting the perl source
52 - Application of the patches
53 - Making
54 - Testing
55 - Installing the built perl
56 AUTHOR
57 SEE ALSO
58
59=head1 DESCRIPTION
60
a83b6f46 61=head2 Prerequisites for Compiling Perl on AmigaOS
0a753a76
PP
62
63=over 6
64
65=item B<Unix emulation for AmigaOS: ixemul.library>
66
67You need the Unix emulation for AmigaOS, whose most important part is
c0c066b9 68B<ixemul.library>. For a minimum setup, get the latest versions
1577cd80 69of the following packages from the Aminet archives
635d4d9b 70( L<http://www.aminet.net/~aminet/> ):
0a753a76 71
c0c066b9
JH
72 ixemul-bin
73 ixemul-env-bin
74 pdksh-bin
0a753a76
PP
75
76Note also that this is a minimum setup; you might want to add other
77packages of B<ADE> (the I<Amiga Developers Environment>).
78
79=item B<Version of Amiga OS>
80
81You need at the very least AmigaOS version 2.0. Recommended is version 3.1.
82
83=back
84
85=head2 Starting Perl programs under AmigaOS
86
87Start your Perl program F<foo> with arguments C<arg1 arg2 arg3> the
88same way as on any other platform, by
89
90 perl foo arg1 arg2 arg3
91
92If you want to specify perl options C<-my_opts> to the perl itself (as
d1be9408 93opposed to your program), use
0a753a76
PP
94
95 perl -my_opts foo arg1 arg2 arg3
96
97Alternately, you can try to get a replacement for the system's B<Execute>
98command that honors the #!/usr/bin/perl syntax in scripts and set the s-Bit
99of your scripts. Then you can invoke your scripts like under UNIX with
100
101 foo arg1 arg2 arg3
102
103(Note that having *nixish full path to perl F</usr/bin/perl> is not
104necessary, F<perl> would be enough, but having full path would make it
105easier to use your script under *nix.)
106
b971f6e4
PP
107=head2 Shortcomings of Perl under AmigaOS
108
109Perl under AmigaOS lacks some features of perl under UNIX because of
110deficiencies in the UNIX-emulation, most notably:
111
174d7f13 112=over 6
b971f6e4 113
0addb26a 114=item *
b971f6e4 115
0addb26a 116fork()
b971f6e4 117
0addb26a 118=item *
b971f6e4 119
0addb26a
RB
120some features of the UNIX filesystem regarding link count and file dates
121
122=item *
123
124inplace operation (the -i switch) without backup file
125
126=item *
127
128umask() works, but the correct permissions are only set when the file is
129finally close()d
0498d68d 130
b971f6e4
PP
131=back
132
0a753a76
PP
133=head1 INSTALLATION
134
135Change to the installation directory (most probably ADE:), and
136extract the binary distribution:
137
f23f9bed 138lha -mraxe x perl-$VERSION-bin.lha
0a753a76
PP
139
140or
141
f23f9bed 142tar xvzpf perl-$VERSION-bin.tgz
0a753a76
PP
143
144(Of course you need lha or tar and gunzip for this.)
145
146For installation of the Unix emulation, read the appropriate docs.
147
148=head1 Accessing documentation
149
a83b6f46 150=head2 Manpages for Perl on AmigaOS
0a753a76
PP
151
152If you have C<man> installed on your system, and you installed perl
153manpages, use something like this:
154
155 man perlfunc
156 man less
157 man ExtUtils.MakeMaker
158
159to access documentation for different components of Perl. Start with
160
161 man perl
162
163Note: You have to modify your man.conf file to search for manpages
164in the /ade/lib/perl5/man/man3 directory, or the man pages for the
165perl library will not be found.
166
167Note that dot (F<.>) is used as a package separator for documentation
168for packages, and as usual, sometimes you need to give the section - C<3>
169above - to avoid shadowing by the I<less(1) manpage>.
170
171
a83b6f46 172=head2 Perl HTML Documentation on AmigaOS
0a753a76
PP
173
174If you have some WWW browser available, you can build B<HTML> docs.
175Cd to directory with F<.pod> files, and do like this
176
177 cd /ade/lib/perl5/pod
178 pod2html
179
180After this you can direct your browser the file F<perl.html> in this
181directory, and go ahead with reading docs.
182
183Alternatively you may be able to get these docs prebuilt from C<CPAN>.
184
a83b6f46 185=head2 Perl GNU Info Files on AmigaOS
0a753a76
PP
186
187Users of C<Emacs> would appreciate it very much, especially with
188C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
189or, alternately, prebuilt info pages.
190
a83b6f46 191=head2 Perl LaTeX Documentation on AmigaOS
0a753a76 192
a83b6f46 193Can be constructed using C<pod2latex>.
0a753a76 194
a83b6f46 195=head1 BUILDING PERL ON AMIGAOS
0a753a76
PP
196
197Here we discuss how to build Perl under AmigaOS.
198
a83b6f46 199=head2 Build Prerequisites for Perl on AmigaOS
0a753a76 200
f23f9bed
SP
201You need to have the latest B<ixemul> (Unix emulation for Amiga)
202from Aminet.
0a753a76 203
a83b6f46 204=head2 Getting the Perl Source for AmigaOS
0a753a76
PP
205
206You can either get the latest perl-for-amiga source from Ninemoons
207and extract it with:
208
f23f9bed 209 tar xvzpf perl-$VERSION-src.tgz
0a753a76
PP
210
211or get the official source from CPAN:
212
468f45d5 213 http://www.cpan.org/src/5.0
0a753a76
PP
214
215Extract it like this
216
c0c066b9 217 tar xvzpf perl-$VERSION.tar.gz
0a753a76
PP
218
219You will see a message about errors while extracting F<Configure>. This
220is normal and expected. (There is a conflict with a similarly-named file
221F<configure>, but it causes no harm.)
222
a83b6f46 223=head2 Making Perl on AmigaOS
b5ab5069
JH
224
225Remember to use a hefty wad of stack (I use 2000000)
0a753a76 226
174d7f13 227 sh configure.gnu --prefix=/gg
54ad72ea 228
b5ab5069 229Now type
c0c066b9 230
b5ab5069 231 make depend
c0c066b9
JH
232
233Now!
0a753a76
PP
234
235 make
236
a83b6f46 237=head2 Testing Perl on AmigaOS
0a753a76
PP
238
239Now run
240
241 make test
242
b971f6e4 243Some tests will be skipped because they need the fork() function:
0a753a76 244
b971f6e4
PP
245F<io/pipe.t>, F<op/fork.t>, F<lib/filehand.t>, F<lib/open2.t>, F<lib/open3.t>,
246F<lib/io_pipe.t>, F<lib/io_sock.t>
0a753a76 247
a83b6f46 248=head2 Installing the built Perl on AmigaOS
0a753a76
PP
249
250Run
251
252 make install
253
07b0e447
JH
254=head1 PERL 5.8.0 BROKEN IN AMIGAOS
255
256As told above, Perl 5.6.1 was still good in AmigaOS, as was 5.7.2.
257After Perl 5.7.2 (change #11423, see the Changes file, and the file
258pod/perlhack.pod for how to get the individual changes) Perl dropped
259its internal support for vfork(), and that was very probably the step
260that broke AmigaOS (since the ixemul library has only vfork).
261The build finally fails when the ext/DynaLoader is being built, and
262PERL ends up as "0" in the produced Makefile, trying to run "0" does
263not quite work. Also, executing miniperl in backticks seems to
264generate nothing: very probably related to the (v)fork problems.
265B<Fixing the breakage requires someone quite familiar with the ixemul
266library, and how one is supposed to run external commands in AmigaOS
267without fork().>
268
c0c066b9 269=head1 AUTHORS
0a753a76
PP
270
271Norbert Pueschel, pueschel@imsdd.meb.uni-bonn.de
c0c066b9 272Jan-Erik Karlsson, trg@privat.utfors.se
0a753a76
PP
273
274=head1 SEE ALSO
275
276perl(1).
277
278=cut