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 6
 105
 106 =item fork()
 107
 108 =item some features of the UNIX filesystem regarding link count and file dates
 109
 110 =item inplace operation (the -i switch) without backup file
 111
 112 =item umask() works, but the correct permissions are only set when the file is
 113       finally close()d
 114
 115 =back
 116
 117 =head1 INSTALLATION
 118
 119 Change to the installation directory (most probably ADE:), and
 120 extract the binary distribution:
 121
 122 lha -mraxe x perl-$VERSION-bin.lha
 123
 124 or
 125
 126 tar xvzpf perl-$VERSION-bin.tgz
 127
 128 (Of course you need lha or tar and gunzip for this.)
 129
 130 For installation of the Unix emulation, read the appropriate docs.
 131
 132 =head1 Accessing documentation
 133
 134 =head2 Manpages
 135
 136 If you have C<man> installed on your system, and you installed perl
 137 manpages, use something like this:
 138
 139         man perlfunc
 140         man less
 141         man ExtUtils.MakeMaker
 142
 143 to access documentation for different components of Perl. Start with
 144
 145         man perl
 146
 147 Note: You have to modify your man.conf file to search for manpages
 148 in the /ade/lib/perl5/man/man3 directory, or the man pages for the
 149 perl library will not be found.
 150
 151 Note that dot (F<.>) is used as a package separator for documentation
 152 for packages, and as usual, sometimes you need to give the section - C<3>
 153 above - to avoid shadowing by the I<less(1) manpage>.
 154
 155
 156 =head2 B<HTML>
 157
 158 If you have some WWW browser available, you can build B<HTML> docs.
 159 Cd to directory with F<.pod> files, and do like this
 160
 161         cd /ade/lib/perl5/pod
 162         pod2html
 163
 164 After this you can direct your browser the file F<perl.html> in this
 165 directory, and go ahead with reading docs.
 166
 167 Alternatively you may be able to get these docs prebuilt from C<CPAN>.
 168
 169 =head2 B<GNU> C<info> files
 170
 171 Users of C<Emacs> would appreciate it very much, especially with
 172 C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
 173 or, alternately, prebuilt info pages.
 174
 175 =head2 C<LaTeX> docs
 176
 177 can be constructed using C<pod2latex>.
 178
 179 =head1 BUILD
 180
 181 Here we discuss how to build Perl under AmigaOS.
 182
 183 =head2 Prerequisites
 184
 185 You need to have the latest B<ixemul> (Unix emulation for Amiga)
 186 from Aminet.
 187
 188 =head2 Getting the perl source
 189
 190 You can either get the latest perl-for-amiga source from Ninemoons
 191 and extract it with:
 192
 193   tar xvzpf perl-$VERSION-src.tgz
 194
 195 or get the official source from CPAN:
 196
 197   http://www.perl.com/CPAN/src/5.0
 198
 199 Extract it like this
 200
 201   tar xvzpf perl-$VERSION.tar.gz
 202
 203 You will see a message about errors while extracting F<Configure>. This
 204 is normal and expected. (There is a conflict with a similarly-named file
 205 F<configure>, but it causes no harm.)
 206
 207 =head2 Making
 208
 209 =over 4
 210
 211 =item *
 212
 213 remember to use a healthy sized stack (I used 2000000)
 214
 215 =item *
 216
 217 your PATH environment variable must include /bin (e.g. ".:/bin" is good)
 218 (or, more precisely, it must include the directory where you have your
 219 basic UNIX utilities like test, cat, sed, and so on)
 220
 221 =item *
 222
 223   sh Configure -Dprefix=/ade -Dloclibpth=/ade/lib
 224
 225 =item *
 226
 227 fix makedepend
 228
 229         In the file 'makedepend' there are three spots like this `$cat ...`:
 230         a for loop near line 75, an egrep near line 161, and a for loop near
 231         line 175.  In all those spots using an editor change the $cat to
 232         /bin/cat.
 233
 234 =item *
 235
 236 now type make depend
 237
 238         When the make depend has ended load the gnumakefile into
 239         an editor and go to the end of the file.
 240
 241         Move upwards in the file until you reach av.o: EXTERN.h
 242         and delete all lines down to # WARNING: Put....
 243
 244 =item *
 245
 246 now go to the x2p directory
 247
 248         Load the gnumakefile into an editor.
 249
 250         Go to the end moveup until you reach hash.o: EXTERN.h
 251         and delete all lines dowonwards until you reach a line saying
 252
 253         # WARNING: Put nothing....
 254
 255 =item *
 256
 257 Now!
 258
 259   make
 260
 261 =back
 262
 263 =head2 Testing
 264
 265 Now run
 266
 267   make test
 268
 269 Some tests will be skipped because they need the fork() function:
 270
 271 F<io/pipe.t>, F<op/fork.t>, F<lib/filehand.t>, F<lib/open2.t>, F<lib/open3.t>,
 272 F<lib/io_pipe.t>, F<lib/io_sock.t>
 273
 274 =head2 Installing the built perl
 275
 276 Run
 277
 278   make install
 279
 280 =head1 AUTHORS
 281
 282 Norbert Pueschel, pueschel@imsdd.meb.uni-bonn.de
 283 Jan-Erik Karlsson, trg@privat.utfors.se
 284
 285 =head1 SEE ALSO
 286
 287 perl(1).
 288
 289 =cut