Trim all trailing / from "." in @INC when filling %INC
[perl.git] / README.mint
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