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