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