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.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
1e044cb5 7perlamiga - Perl under AmigaOS 4.1
0a753a76 8
07b0e447
JH
9=head1 NOTE
10
1e044cb5
AB
11This is a port of Perl 5.22.1, it is a fresh port and not in any way
12compatible with my previous ports of Perl 5.8 and 5.16.3. This means
13you will need to reinstall / rebuild any third party modules you have
14installed.
07b0e447 15
1e044cb5 16newlib.library version 53.28 or greater is required.
0a753a76 17
1e044cb5 18=head1 SYNOPSIS
0a753a76 19
1e044cb5 20Once perl is installed you can read this document in the following way
0a753a76 21
1e044cb5 22 sh -c "perldoc perlamiga"
b5ab5069 23
1e044cb5 24or you may read I<as is>: either as F<README.amiga>, or F<pod/perlamiga.pod>.
c0c066b9 25
0a753a76
PP
26=cut
27
1e044cb5
AB
28 NAME
29 SYNOPSIS
30 DESCRIPTION
31 - Prerequisites
0a753a76 32 - Starting Perl programs under AmigaOS
b971f6e4 33 - Shortcomings of Perl under AmigaOS
1e044cb5
AB
34 INSTALLATION
35 CHANGES
0a753a76
PP
36
37=head1 DESCRIPTION
38
1e044cb5 39=head2 Prerequisites for running Perl 5.22.1 under AmigaOS 4.1
0a753a76
PP
40
41=over 6
42
1e044cb5 43=item B<AmigaOS 4.1 update 6 with all updates applied as of 9th October 2013>
0a753a76 44
1e044cb5 45The most important of which is:
0a753a76 46
1e044cb5 47=item B<newlib.library version 53.28 or greater>
0a753a76 48
1e044cb5 49=item B<AmigaOS SDK>
0a753a76 50
1e044cb5
AB
51Perl installs into the SDK directory structure and expects many of the
52build tools present in the SDK to be available. So for the best results
53install the SDK first.
0a753a76 54
1e044cb5 55=item B<abc-shell>
0a753a76 56
1e044cb5
AB
57If you do not have the SDK installed you must at least have abc-shell
58installed or some other suitable sh port. This is required to run
59external commands and should be available as 'sh' in your path.
0a753a76 60
1e044cb5 61=back
0a753a76 62
1e044cb5 63=head2 Starting Perl programs under AmigaOS 4.1
0a753a76 64
1e044cb5
AB
65Perl may be run from the AmigaOS shell but for best results should be
66run under abc-shell. (abc-shell handles file globbing, pattern
67expansion, and sets up environment variables in the UN*Xy way that
68Perl expects.)
0a753a76 69
1e044cb5 70For example:
0a753a76 71
1e044cb5
AB
72 New Shell process 10
73 10.AmigaOS4:> sh
74 /AmigaOS4>perl path:to/myprog arg1 arrg2 arg3
0a753a76 75
1e044cb5
AB
76Abc-shell can also launch programs via the #! syntax at the start of
77the program file, it's best use the form #!SDK:Local/C/perl so that
78the AmigaOS shell may also find perl in the same way. AmigaOS requires
79the script bit to be set for this to work
0a753a76 80
1e044cb5
AB
81 10.AmigaOS4:> sh
82 /AmigaOS4>myprog arg1 arrg2 arg3
b971f6e4 83
1e044cb5 84=head2 Limitations of Perl under AmigaOS 4.1
b971f6e4 85
174d7f13 86=over 6
b971f6e4 87
1e044cb5
AB
88=item B<Nested Piped programs can crash when run from older abc-shells>
89
90abc-shell version 53.2 has a bug that can cause crashes in the
91subprocesses used to run piped programs, if a later version is
92available you should install it instead.
b971f6e4 93
1e044cb5 94=item B<Incorrect or unexpected command line unescaping>
b971f6e4 95
1e044cb5
AB
96newlib.library 53.30 and earlier incorrectly unescape slashed escape
97sequences e.g. \" \n \t etc requiring unusual extra escaping.
b971f6e4 98
1e044cb5 99=item B<Starting subprocesses via open has limitations>
0addb26a 100
1e044cb5 101 open FH, "command |"
0addb26a 102
1e044cb5
AB
103Subprocesses started with open use a minimal popen() routine and
104therefore they do not return pids usable with waitpid etc.
0addb26a 105
1e044cb5 106=item If you find any other limitations or bugs then let me know.
0addb26a 107
1e044cb5
AB
108Please report bugs in this version of perl to andy@broad.ology.org.uk
109in the first instance.
0498d68d 110
b971f6e4
PP
111=back
112
0a753a76
PP
113=head1 INSTALLATION
114
1e044cb5 115This guide assumes you have obtained a prebuilt archive from os4depot.net.
0a753a76 116
1e044cb5 117Unpack the main archive to a temporary location (RAM: is fine).
0a753a76 118
1e044cb5 119Execute the provided install script from shell or via its icon.
0a753a76 120
1e044cb5 121You B<must not> attempt to install by hand.
0a753a76 122
1e044cb5 123Once installed you may delete the temporary archive.
0a753a76 124
1e044cb5
AB
125This approach will preserve links in the installation without creating
126duplicate binaries.
0a753a76 127
1e044cb5
AB
128If you have the earlier ports perl 5.16 or 5.8 installed you may like
129to rename your perl executable to perl516 or perl58 or something
130similar before the installation of 5.22.1, this will allow you to use
131both versions at the same time.
0a753a76 132
1e044cb5 133=head1 Amiga Specific Modules
0a753a76 134
1e044cb5 135=head2 Amiga::ARexx
0a753a76 136
1e044cb5
AB
137The Amiga::ARexx module allows you to easily create a perl based ARexx
138host or to send ARexx commands to other programs.
0a753a76 139
1e044cb5 140Try C<perldoc Amiga::ARexx> for more info.
0a753a76 141
1e044cb5 142=head2 Amiga::Exec
0a753a76 143
1e044cb5 144The Amiga::Exec module introduces support for Wait().
0a753a76 145
1e044cb5 146Try C<perldoc Amiga::Exec> for more info.
0a753a76 147
1e044cb5 148=head1 BUILDING
0a753a76 149
1e044cb5
AB
150To build perl under AmigaOS from the patched sources you will need to
151have a recent version of the SDK. Version 53.29 is recommended,
152earlier versions will probably work too.
0a753a76 153
1e044cb5
AB
154With the help of Jarkko Hietaniemi the Configure system has been tweaked to
155run under abc-shell so the recommend build process is as follows.
0a753a76 156
1e044cb5
AB
157 stack 2000000
158 sh Configure -de
159 gmake
0a753a76 160
1e044cb5 161This will build the default setup that installs under SDK:local/newlib/lib/
0a753a76 162
1e044cb5 163=head1 CHANGES
0a753a76 164
1e044cb5 165=over 6
0a753a76 166
1e044cb5 167=item B<August 2015>
0a753a76 168
1e044cb5 169=over 2
0a753a76 170
1e044cb5 171=item Port to Perl 5.22
0a753a76 172
1e044cb5 173=item Add handling of NIL: to afstat()
b5ab5069 174
1e044cb5 175=item Fix inheritance of environment variables by subprocesses.
0a753a76 176
1e044cb5 177=item Fix exec, and exit in "forked" subprocesses.
54ad72ea 178
1e044cb5 179=item Fix issue with newlib's unlink, which could cause infinite loops.
c0c066b9 180
1cd70adf
AB
181=item Add flock() emulation using IDOS->LockRecord thanks to Tony Cook
182for the suggestion.
183
ef2467ad
AB
184=item Fix issue where kill was using the wrong kind of process ID
185
1e044cb5 186=back
c0c066b9 187
1e044cb5 188=item B<27th November 2013>
0a753a76 189
1e044cb5 190=over 2
0a753a76 191
1e044cb5
AB
192=item Create new installation system based on installperl links
193and Amiga protection bits now set correctly.
0a753a76 194
1e044cb5 195=item Pod now defaults to text.
0a753a76 196
1e044cb5
AB
197=item File::Spec should now recognise an Amiga style absolute path as well
198as an Unix style one. Relative paths must always be Unix style.
0a753a76 199
1e044cb5 200=back
0a753a76 201
1e044cb5 202=item B<20th November 2013>
0a753a76 203
1e044cb5 204=over 2
0a753a76 205
1e044cb5 206=item Configured to use SDK:Local/C/perl to start standard scripts
0a753a76 207
1e044cb5 208=item Added Amiga::Exec module with support for Wait() and AmigaOS signal numbers.
0a753a76 209
1e044cb5 210=back
07b0e447 211
1e044cb5 212=item B<10th October 13>
07b0e447 213
1e044cb5 214First release of port to 5.16.3.
0a753a76 215
1e044cb5 216=back
0a753a76
PP
217
218=head1 SEE ALSO
219
1e044cb5
AB
220You like this port? See L<http://www.broad.ology.org.uk/amiga/>
221for how you can help.
0a753a76
PP
222
223=cut