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