Socket::my_inet_aton() tweak
[p5sagit/p5-mst-13.2.git] / README.epoc
1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see pod/perlpod.pod) which is
3 specially designed to be readable as is.
4
5 =head1 NAME
6
7 README.epoc - Perl for EPOC
8
9 =head1 SYNOPSIS
10
11 Perl 5 README file for the EPOC operating system.
12
13 =head1 INTRODUCTION
14
15 EPOC is an OS for palmtops and mobile phones. For more informations look at:
16 http://www.symbian.com/
17
18 This is a port of perl to EPOC. It runs on ER5 machines: Psion 5mx,
19 5mx Pro, Psion Revo and on the Ericson M128. I have no report about
20 the Psion Netbook or the S7. It runs on ER3 Hardware (Series 5
21 classic), too. For more information about this hardware please refer
22 to http://www.psion.com.
23
24 Vendors which like to have support for their devices are free to send
25 me a sample. 
26
27 =head1 INSTALLING PERL ON EPOC
28
29 You can download a ready-to-install version from
30 http://www.science-computing.de/o.flebbe/perl. You may find other
31 versions with some CPAN modules included at this location.
32
33 You will need at least ~4MB free space in order to install and run
34 perl.
35
36 Install perl.sis on the EPOC machine. If you do not know how to do
37 that, consult your PsiWin documentation.
38
39 Perl itself and its standard library is using 2.5 MB disk space.
40 Unicode support and some other modules are left out. (For details,
41 please look into epoc/createpkg.pl). If you like to use these modules,
42 you are free to copy them from a current perl release.
43
44 =head1 STARTING PERL ON EPOC
45
46 For ER5 machines, you can get the software Perlstart
47 http://www.science-computing.de/o.flebbe/perl. It contains file
48 recognizers for files with the extension .pl and .pm. With it you can
49 start perl with a double click on the camel icon. Be sure to configure
50 the perl installation drive first. You can even provide a script with
51 a special commandline, if needed.
52
53 Alternatively you can get ESHELL from symbian: 
54 http://developer.epocworld.com/downloads/progs/Eshell.zip
55
56 Running ESHELL you can enter: perl -de 0 in order to run the perl
57 debugger. If you are leaving perl, you get into the system screen. You
58 have to switch back manually to ESHELL. When perl is running, you will
59 see a task with the name STDOUT in the task list. 
60
61 If you have an ER3 machine (i.e. a PSION 5), you may have to supply the
62 full path to the perl executable C:\system\programs\perl.exe.
63
64 If you need to set the current directory of perl, please use the
65 command line switch '-x'. See L<perlrun> for details.
66
67 =head1 STOPPING PERL ON EPOC
68
69 You can stop a running perl process in the task list by closing the
70 application `STDOUT'. You cannot stop a running perl process if it has
71 not written anything to stdout or stderr! Be very cautious with I/O
72 redirection. You will have to reboot the PDA!
73
74 =head1 USING PERL ON EPOC
75
76 =head2 I/O Redirection on Epoc
77
78 You can redirect the output with the UNIX bourne shell syntax (this is
79 built into perl rather then eshell) For instance the following command
80 line will run the script test.pl with the output redirected to
81 stdout_file, the errors to stderr_file and input from stdin_file.
82
83 perl test.pl >stdout_file <stdin_file 2>stderr_file
84
85 Alternatively you can use 2>&1 in order to add the standard error
86 output to stdout.
87
88 =head2 PATH Names on Epoc
89
90 ESHELL looks for executables in ?:/System/Programs. The SIS file
91 installs perl in this special folder directory. The default drive and
92 path are the same as folder the executable resides. The EPOC
93 filesystem is case-preserving, not case-sensitive.
94
95 The EPOC estdlib uses the ?: syntax for establishing a search order:
96 First in C: (RAM), then on D: (CF Card, if present) and last in Z:
97 (ROM). For instance ?:\a.txt searches for C:\a.txt, D:\a.txt (and
98 Z:\a.txt)
99
100 The perl @INC search path is implemented with '?:'. Your perl
101 executable can live on a different drive than the perl library or even
102 your scripts.
103
104 ESHELL paths have to be written with backslashes '\', file arguments
105 to perl with slashes '/'. Remember that I/O redirection is done
106 internally in perl, so please use slashes for redirects.
107
108 perl.exe C:/test.pl >C:/output.txt
109
110 =head2 Editors on Epoc
111
112 A suitable text editor can be downloaded from symbian
113  http://developer.epocworld.com/downloads/progs/Editor.zip
114
115 =head2 Features of Perl on Epoc
116
117 The built-in function EPOC::getcwd returns the current directory.
118
119 =head2 Restrictions of Perl on Epoc
120
121 Features are left out, because of restrictions of the POSIX support in
122 EPOC:
123
124 =over 4
125
126 =item *
127
128 backquoting, pipes etc.
129
130 =item *
131
132 system() does not inherit resources like: file descriptors,
133 environment etc.
134
135 =item *
136
137 signal, kill, alarm. Do not try to use them. This may be
138 impossible to implement on EPOC.
139
140 =item *
141
142 select is missing.
143
144 =item *
145
146 binmode does not exist. (No CR LF to LF translation for text files)
147
148 =item *
149
150 EPOC does not handle the notion of current drive and current
151 directory very well (i.e. not at all, but it tries hard to emulate
152 one) See PATH.
153
154 =item *
155
156 Heap is limited to 4MB.
157
158 =item *
159
160 Dynamic loading is not implemented.
161
162 =back
163
164 =head2 Compiling Perl 5 on the EPOC cross compiling environment
165
166 Sorry, this is far too short.
167
168 =over 4
169
170 =item *
171
172 You will need the C++ SDK from http://developer.epocworld.com/. 
173
174 =item *
175
176 You will need to set up the cross SDK from 
177 http://www.science-computing.de/o.flebbe/sdk
178
179 =item *
180
181 You may have to adjust config.sh (cc, cppflags) to reflect your epoc 
182 and SDK location.
183
184 =item *
185
186 Get the Perl sources from your nearest CPAN site.
187
188 =item *
189
190 Unpack the sources. 
191
192 =item *
193
194 Build a native perl from this sources... Make sure to save the
195 miniperl executable as miniperl.native.
196
197 Start again from scratch
198
199       cp epoc/* .
200       ./Configure -S
201       make 
202       cp miniperl.native miniperl
203       make
204       make ext/Errno/pm_to_blib 
205       perl link.pl perlmain.o lib/auto/DynaLoader/DynaLoader.a \
206          lib/auto/Data/Dumper/Dumper.a \
207          lib/auto/File/Glob/Glob.a lib/auto/IO/IO.a \
208          lib/auto/Socket/Socket.a \
209          lib/auto/Fcntl/Fcntl.a lib/auto/Sys/Hostname/Hostname.a \
210         perl.a `cat ext.libs`
211       perl createpkg.pl 
212
213       wine G:/bin/makesis perl.pkg perl.sis
214
215 =back
216
217 =head1 SUPPORT STATUS OF PERL ON EPOC
218
219 I'm offering this port "as is". You can ask me questions, but I can't
220 guarantee I'll be able to answer them.
221
222 =head1 AUTHOR
223
224 Olaf Flebbe <o.flebbe@science-computing.de>
225 http://www.science-computing.de/o.flebbe/perl/
226
227 =head1 LAST UPDATE
228
229 2001-02-26
230
231 =cut