Fixing PERL5OPT (was Re: Warnings, strict, and CPAN)
[p5sagit/p5-mst-13.2.git] / README.amiga
1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see perlpod manpage) which is
3 specially designed to be readable as is.
4
5 =head1 NAME
6
7 perlamiga - Perl under Amiga OS
8
9 =head1 SYNOPSIS
10
11 One can read this document in the following formats:
12
13         man perlamiga
14         multiview perlamiga.guide
15
16 to list some (not all may be available simultaneously), or it may
17 be read I<as is>: either as F<README.amiga>, or F<pod/perlamiga.pod>.
18
19 A recent version of perl for the Amiga can be found at the Geek Gadgets
20 section of the Aminet:
21   
22       http://www.aminet.net/~aminet/dirs/dev_gg.html
23
24 =cut
25
26 Contents
27  
28  perlamiga - Perl under Amiga OS
29
30        NAME 
31        SYNOPSIS 
32        DESCRIPTION 
33          -  Prerequisites 
34          -  Starting Perl programs under AmigaOS
35          -  Shortcomings of Perl under AmigaOS
36        INSTALLATION 
37        Accessing documentation 
38          -  Manpages 
39          -  HTML 
40          -  GNU info files 
41          -  LaTeX docs 
42        BUILD 
43          -  Prerequisites 
44          -  Getting the perl source 
45          -  Application of the patches 
46          -  Making 
47          -  Testing 
48          -  Installing the built perl 
49        AUTHOR 
50        SEE ALSO 
51
52 =head1 DESCRIPTION
53
54 =head2 Prerequisites
55
56 =over 6
57
58 =item B<Unix emulation for AmigaOS: ixemul.library>
59
60 You need the Unix emulation for AmigaOS, whose most important part is
61 B<ixemul.library>. For a minimum setup, get the latest versions
62 of the following packages from the Aminet archives (http://www.aminet.net/~aminet/):
63
64         ixemul-bin
65         ixemul-env-bin
66         pdksh-bin
67
68 Note also that this is a minimum setup; you might want to add other
69 packages of B<ADE> (the I<Amiga Developers Environment>).
70
71 =item B<Version of Amiga OS>
72
73 You need at the very least AmigaOS version 2.0. Recommended is version 3.1.
74
75 =back
76
77 =head2 Starting Perl programs under AmigaOS
78
79 Start your Perl program F<foo> with arguments C<arg1 arg2 arg3> the
80 same way as on any other platform, by
81
82         perl foo arg1 arg2 arg3
83
84 If you want to specify perl options C<-my_opts> to the perl itself (as
85 opposed to to your program), use
86
87         perl -my_opts foo arg1 arg2 arg3
88
89 Alternately, you can try to get a replacement for the system's B<Execute>
90 command that honors the #!/usr/bin/perl syntax in scripts and set the s-Bit
91 of your scripts. Then you can invoke your scripts like under UNIX with
92
93         foo arg1 arg2 arg3
94
95 (Note that having *nixish full path to perl F</usr/bin/perl> is not
96 necessary, F<perl> would be enough, but having full path would make it
97 easier to use your script under *nix.)
98
99 =head2 Shortcomings of Perl under AmigaOS
100
101 Perl under AmigaOS lacks some features of perl under UNIX because of
102 deficiencies in the UNIX-emulation, most notably:
103
104 =over 4
105
106 =item * 
107
108 fork()
109
110 =item *
111
112 some features of the UNIX filesystem regarding link count and file dates
113
114 =item *
115
116 inplace operation (the -i switch) without backup file
117
118 =item *
119
120 umask() works, but the correct permissions are only set when the file is
121 finally close()d
122
123 =back
124
125 =head1 INSTALLATION
126
127 Change to the installation directory (most probably ADE:), and
128 extract the binary distribution:
129
130 lha -mraxe x perl-$VERSION-bin.lha
131
132 or
133
134 tar xvzpf perl-$VERSION-bin.tgz
135
136 (Of course you need lha or tar and gunzip for this.)
137
138 For installation of the Unix emulation, read the appropriate docs.
139
140 =head1 Accessing documentation
141
142 =head2 Manpages
143
144 If you have C<man> installed on your system, and you installed perl
145 manpages, use something like this:
146
147         man perlfunc
148         man less
149         man ExtUtils.MakeMaker
150
151 to access documentation for different components of Perl. Start with
152
153         man perl
154
155 Note: You have to modify your man.conf file to search for manpages
156 in the /ade/lib/perl5/man/man3 directory, or the man pages for the
157 perl library will not be found. 
158
159 Note that dot (F<.>) is used as a package separator for documentation
160 for packages, and as usual, sometimes you need to give the section - C<3>
161 above - to avoid shadowing by the I<less(1) manpage>.
162
163
164 =head2 B<HTML>
165
166 If you have some WWW browser available, you can build B<HTML> docs.
167 Cd to directory with F<.pod> files, and do like this
168
169         cd /ade/lib/perl5/pod
170         pod2html
171
172 After this you can direct your browser the file F<perl.html> in this
173 directory, and go ahead with reading docs.
174
175 Alternatively you may be able to get these docs prebuilt from C<CPAN>.
176
177 =head2 B<GNU> C<info> files
178
179 Users of C<Emacs> would appreciate it very much, especially with
180 C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
181 or, alternately, prebuilt info pages.
182
183 =head2 C<LaTeX> docs
184
185 can be constructed using C<pod2latex>.
186
187 =head1 BUILD
188
189 Here we discuss how to build Perl under AmigaOS.
190
191 =head2 Prerequisites
192
193 You need to have the latest B<ixemul> (Unix emulation for Amiga)
194 from Aminet.
195
196 =head2 Getting the perl source
197
198 You can either get the latest perl-for-amiga source from Ninemoons
199 and extract it with:
200
201   tar xvzpf perl-$VERSION-src.tgz
202
203 or get the official source from CPAN:
204
205   http://www.perl.com/CPAN/src/5.0
206
207 Extract it like this
208
209   tar xvzpf perl-$VERSION.tar.gz
210
211 You will see a message about errors while extracting F<Configure>. This
212 is normal and expected. (There is a conflict with a similarly-named file
213 F<configure>, but it causes no harm.)
214
215 =head2 Making
216
217 =over 4
218
219 =item *
220
221 remember to use a healthy sized stack (I used 2000000)
222
223 =item *
224
225 your PATH environment variable must include /bin (e.g. ".:/bin" is good)
226 (or, more precisely, it must include the directory where you have your
227 basic UNIX utilities like test, cat, sed, and so on)
228
229 =item *
230         
231   sh Configure -Dprefix=/ade -Dloclibpth=/ade/lib
232
233 =item *
234
235 fix makedepend
236
237         In the file 'makedepend' there are three spots like this `$cat ...`:
238         a for loop near line 75, an egrep near line 161, and a for loop near
239         line 175.  In all those spots using an editor change the $cat to
240         /bin/cat.
241
242 =item *
243
244 now type make depend
245
246         When the make depend has ended load the gnumakefile into
247         an editor and go to the end of the file.
248
249         Move upwards in the file until you reach av.o: EXTERN.h
250         and delete all lines down to # WARNING: Put....
251
252 =item *
253
254 now go to the x2p directory
255
256         Load the gnumakefile into an editor.
257
258         Go to the end moveup until you reach hash.o: EXTERN.h
259         and delete all lines dowonwards until you reach a line saying
260
261         # WARNING: Put nothing....
262
263 =item *
264
265 Now!
266
267   make
268
269 =back
270
271 =head2 Testing
272
273 Now run
274
275   make test
276
277 Some tests will be skipped because they need the fork() function:
278
279 F<io/pipe.t>, F<op/fork.t>, F<lib/filehand.t>, F<lib/open2.t>, F<lib/open3.t>, 
280 F<lib/io_pipe.t>, F<lib/io_sock.t>
281
282 =head2 Installing the built perl
283
284 Run
285
286   make install
287
288 =head1 AUTHORS
289
290 Norbert Pueschel, pueschel@imsdd.meb.uni-bonn.de
291 Jan-Erik Karlsson, trg@privat.utfors.se
292
293 =head1 SEE ALSO
294
295 perl(1).
296
297 =cut