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