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