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