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