| 1 | If you read this file _as_is_, just ignore the funny characters you see. |
| 2 | It is written in the POD format (see pod/perlpod.pod) which is specially |
| 3 | designed to be readable as is. |
| 4 | |
| 5 | =head1 NAME |
| 6 | |
| 7 | README.mint - Perl version 5 on Atari MiNT |
| 8 | |
| 9 | =head1 DESCRIPTION |
| 10 | |
| 11 | There is a binary version of perl available from the FreeMiNT project |
| 12 | http://freemint.de/ You may wish to use this instead of trying to |
| 13 | compile yourself. |
| 14 | |
| 15 | B<The following advice is from perl 5.004_02 and is probably rather |
| 16 | out of date.> |
| 17 | |
| 18 | If you want to build perl yourself on MiNT (or maybe on an Atari without |
| 19 | MiNT) you may want to accept some advice from somebody who already did it... |
| 20 | |
| 21 | There was a perl port for Atari ST done by ++jrb bammi@cadence.com. |
| 22 | This port tried very hard to build on non-MiNT-systems. For the |
| 23 | sake of efficiency I've left this way. Yet, I haven't removed bammi's |
| 24 | patches but left them intact. Unfortunately some of the files that |
| 25 | bammi contributed to the perl distribution seem to have vanished? |
| 26 | |
| 27 | So, how can you distinguish my patches from bammi's patches? All of |
| 28 | bammi's stuff is embedded in "#ifdef atarist" preprocessor macros. |
| 29 | My MiNT port uses "#ifdef __MINT__" instead (and unconditionally |
| 30 | undefines "atarist". If you want to continue on bammi's port, all |
| 31 | you have to do is to swap the "-D" and "-U" switches for "__MINT__" |
| 32 | and "atarist" in the variable ccflags. |
| 33 | |
| 34 | However, I think that my version will still run on non-MiNT-systems |
| 35 | provided that the user has a Eunuchs-like environment (i.e. the |
| 36 | standard envariables like $PATH, $HOME, ... are set, there is a |
| 37 | POSIX compliant shell in /bin/sh, and...) |
| 38 | |
| 39 | =head1 Known problems with Perl on MiNT |
| 40 | |
| 41 | The problems you may encounter when building perl on your machine |
| 42 | are most probably due to deficiencies in MiNT resp. the Atari |
| 43 | platform in general. |
| 44 | |
| 45 | First of all, if you have less than 8 MB of RAM you shouldn't |
| 46 | even try to build Perl yourself. Better grab a binary pre-compiled |
| 47 | version somewhere. Even if you have more memory you should take |
| 48 | some care. Try to run in a fresh environment (without memory |
| 49 | fragmented too much) with as few daemons, accessories, xcontrol |
| 50 | modules etc. as possible. If you run some AES you should |
| 51 | consider to start a console based environment instead. |
| 52 | |
| 53 | A problem has been reported with sed. Sed is used to create |
| 54 | some configuration files based on the answers you have given |
| 55 | to the Configure script. Unfortunately the Perl Configure script |
| 56 | shows sed on MiNT its limits. I have sed 2.05 with a stacksize |
| 57 | of 64k and I have encountered no problems. If sed crashes |
| 58 | during your configuration process you should first try to |
| 59 | augment sed's stacksize: |
| 60 | |
| 61 | fixstk 64k /usr/bin/sed |
| 62 | |
| 63 | (or similar). If it still doesn't help you may have a look |
| 64 | which other versions of sed are installed on your system. |
| 65 | If you have a KGMD 1.0 installation you will find three |
| 66 | in /usr/bin. Have a look there. |
| 67 | |
| 68 | Perl has some "mammut" C files. If gcc reports "internal |
| 69 | compiler error: program cc1 got fatal signal 10" this is very |
| 70 | likely due to a stack overflow in program cc1. Find cc1 |
| 71 | and fix its stack. I have made good experiences with |
| 72 | |
| 73 | fixstk 2 cc1 |
| 74 | |
| 75 | This doesn't establish a stack of 2 Bytes only as you might |
| 76 | think. It really reserves one half of the available memory |
| 77 | for cc1's stack. A setting of 1 would reserve the entire |
| 78 | memory for cc1, 3 would reserve three fourths. You will have |
| 79 | to find out the value that suits to your system yourself. |
| 80 | |
| 81 | To find out the location of the program "cc1" simply type |
| 82 | `gcc --print-prog-name cc1' at your shell prompt. |
| 83 | |
| 84 | Now run make (maybe "make -k"). If you get a fatal signal 10 |
| 85 | increase cc1's stacksize, if you run out of memory you should |
| 86 | either decrease the stacksize or follow some more hints: |
| 87 | |
| 88 | Perl's building process is very handy on machines with a lot |
| 89 | of virtual memory but may result in a disaster if you are short |
| 90 | of memory. If gcc fails to compile many source files you should |
| 91 | reduce the optimization. Grep for "optimize" in the file |
| 92 | config.sh and change the flags. |
| 93 | |
| 94 | If only several huge files cause problems (actually it is not a |
| 95 | matter of the file size resp. the amount of code but depends on |
| 96 | the size of the individual functions) it is useful to bypass |
| 97 | the make program and compile these files directly from the |
| 98 | command line. For example if you got something like the |
| 99 | following from make: |
| 100 | |
| 101 | CCCMD = gcc -DPERL_CORE .... |
| 102 | ... |
| 103 | ...: virtual memory exhausted |
| 104 | |
| 105 | you should hack into the shell: |
| 106 | |
| 107 | gcc -DPERL_CORE ... toke.c |
| 108 | |
| 109 | Please note that you have to add the name of the source file |
| 110 | (here toke.c) at the end. |
| 111 | |
| 112 | If none of this helps, you're helpless. Wait for a binary |
| 113 | release. If you have succeeded you may encounter another problem |
| 114 | at the linking process. If gcc complains that it can't find |
| 115 | some libraries within the perl distribution you probably have |
| 116 | an old linker. If it complains for example about "file not |
| 117 | found for xxx.olb" you should cd into the directory in |
| 118 | question and |
| 119 | |
| 120 | ln -s libxxx.a xxx.olb |
| 121 | |
| 122 | This will fix the problem. |
| 123 | |
| 124 | This version (5.00402) of perl has passed most of the tests on my system: |
| 125 | |
| 126 | Failed Test Status Wstat Total Fail Failed List of failed |
| 127 | ------------------------------------------------------------------------------ |
| 128 | io/pipe.t 10 2 20.00% 7, 9 |
| 129 | io/tell.t 13 1 7.69% 12 |
| 130 | lib/complex.t 762 13 1.71% 84-85, 248-251, 257, 272-273, |
| 131 | 371, 380, 419-420 |
| 132 | lib/io_pipe.t 10 1 10.00% 9 |
| 133 | lib/io_tell.t 13 1 7.69% 12 |
| 134 | op/magic.t 30 2 6.67% 29-30 |
| 135 | Failed 6/152 test scripts, 96.05% okay. 20/4359 subtests failed, 99.54% okay. |
| 136 | |
| 137 | Pipes always cause problems with MiNT, it's actually a surprise that |
| 138 | most of the tests did work. I've got no idea why the "tell" test failed, |
| 139 | this shouldn't mean too big a problem however. |
| 140 | |
| 141 | Most of the failures of lib/complex seem to be harmless, actually errors |
| 142 | far right to the decimal point... Two failures seem to be serious: |
| 143 | The sign of the results is reversed. I would say that this is due |
| 144 | to minor bugs in the portable math lib that I compiled perl with. |
| 145 | |
| 146 | I haven't bothered very much to find the reason for the failures |
| 147 | with op/magic.t and op/stat.t. Maybe you'll find it out. |
| 148 | |
| 149 | ########################################################################## |
| 150 | |
| 151 | Another possible problem may arise from the implementation of the "pwd" |
| 152 | command. It happened to add a carriage return and newline to its output |
| 153 | no matter what the setting of $UNIXMODE is. This is quite annoying since many |
| 154 | library modules for perl take the output of pwd, chop off the |
| 155 | trailing newline character and then expect to see a valid path in |
| 156 | that. But the carriage return (last but second character!) isn't |
| 157 | chopped off. You can either try to patch all library modules (at |
| 158 | the price of performance for the extra transformation) or you can |
| 159 | use my version of pwd that doesn't suffer from this deficiency. |
| 160 | |
| 161 | The fixed implementation is in the mint subdirectory. Running |
| 162 | "Configure" will attempt to build and install it if necessary |
| 163 | (hints/mint.sh will do this work) but you can build and install it |
| 164 | explicitly by: |
| 165 | |
| 166 | cd mint |
| 167 | make install |
| 168 | |
| 169 | This is the fastest solution. |
| 170 | |
| 171 | Just in case you want to go the hard way: perl won't even build with a |
| 172 | broken pwd! You will have to fix the library modules |
| 173 | (ext/POSIX/POSIX.pm, lib/Cwd.pm, lib/pwd.pl) at last after building |
| 174 | miniperl. |
| 175 | |
| 176 | A major nuisance of current MiNTLib versions is the implementation |
| 177 | of system() which is far from being POSIX compliant. A real system() |
| 178 | should fork and then exec /bin/sh with its argument as a command |
| 179 | line to the shell. The MiNTLib system() however doesn't expect |
| 180 | that every user has a POSIX shell in /bin/sh. It tries to work |
| 181 | around the problem by forking and exec'ing the first token in its argument |
| 182 | string. To get a little bit of compliance to POSIX system() it |
| 183 | tries to handle at least redirection ("<" or ">") on its own |
| 184 | behalf. |
| 185 | |
| 186 | This isn't a good idea since many programs expect that they can |
| 187 | pass a command line to system() that exploits all features of a |
| 188 | POSIX shell. If you use the MiNTLib version of system() with |
| 189 | perl the Perl function system() will suffer from the same deficiencies. |
| 190 | |
| 191 | You will find a fixed version of system() in the mint subdirectory. |
| 192 | You can easily insert this version into your system libc: |
| 193 | |
| 194 | cd mint |
| 195 | make system.o |
| 196 | ar r /usr/lib/libc.a |
| 197 | ranlib /usr/lib/libc.a |
| 198 | |
| 199 | If you are suspicious you should either back up your libc before |
| 200 | or extract the original system.o from your libc with |
| 201 | "ar x /usr/lib/libc.a system.o". You can then backup the system.o |
| 202 | module somewhere before you succeed. |
| 203 | |
| 204 | Anything missing? Yep, I've almost forgotten... |
| 205 | No file in this distribution without a fine saying. Take this one: |
| 206 | |
| 207 | "From a thief you should learn: (1) to work at night; |
| 208 | (2) if one cannot gain what one wants in one night to |
| 209 | try again the next night; (3) to love one's coworkers |
| 210 | just as thieves love each other; (4) to be willing to |
| 211 | risk one's life even for a little thing; (5) not to |
| 212 | attach too much value to things even though one has |
| 213 | risked one's life for them - just as a thief will resell |
| 214 | a stolen article for a fraction of its real value; |
| 215 | (6) to withstand all kinds of beatings and tortures |
| 216 | but to remain what you are; and (7) to believe your |
| 217 | work is worthwhile and not be willing to change it." |
| 218 | |
| 219 | -- Rabbi Dov Baer, Maggid of Mezeritch |
| 220 | |
| 221 | OK, this was my motto while working on Perl for MiNT, especially rule (1)... |
| 222 | |
| 223 | Have fun with Perl! |
| 224 | |
| 225 | =head1 AUTHOR |
| 226 | |
| 227 | Guido Flohr |
| 228 | |
| 229 | mailto:guido@FreeMiNT.de |