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