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