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 a 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 the Psion Series 5, 5mx,
  19 5mx Pro, Psion Revo and on the Ericson M128. I have no report about
  20 the Psion Netbook or the S7. For information about this hardware
  21 please refer to http://www.psion.com.
  22
  23 =head1 INSTALLING PERL ON EPOC
  24
  25 You will need ~4MB free space in order to install and run perl.
  26
  27 Install perl.sis on the EPOC machine (most likely a PSION Series 5,
  28 5mx). If you do not know how to do that, you are on your own.
  29
  30 Perl itself and its standard library are using 2.5 MB disk space. I
  31 left out unicode support modules and modules which will not work with
  32 this version. (For details look into epoc/createpkg.pl). If you like
  33 to use them, you are free to copy them from a current perl release.
  34
  35 Get ESHELL from symbian:
  36 http://developer.epocworld.com/downloads/progs/Eshell.zip
  37
  38 Now you can enter: perl -de 0 in order to run the perl debugger. If
  39 you are leaving perl, you get into the system screen. You have to
  40 switch back manually to ESHELL. When perl is running, you will see
  41 a task with the name STDOUT in the task list.
  42
  43 =head1 USING PERL ON EPOC
  44
  45 =head2 IO Redirection
  46
  47 You can redirect the output with the UNIX bourne shell syntax (this is
  48 built into perl rather then eshell) For instance the following command
  49 line will run the script test.pl with the output redirected to
  50 stdout_file, the errors to stderr_file and input from stdin_file.
  51
  52 perl test.pl >stdout_file <stdin_file 2>stderr_file
  53
  54 Alternatively you can use 2>&1 in order to add the standard error
  55 output to stdout.
  56
  57 =head2 PATH Names
  58
  59 ESHELL looks for executables in ?:/System/Programs. The SIS file
  60 installs perl in this special folder directory. The default drive and
  61 path are the same as folder the executable resides. The EPOC
  62 filesystem is case-preserving, not case-sensitive.
  63
  64 EPOC uses the ?: syntax for establishing a search order: First in C: (RAM),
  65 then on D: (CF Card) and last in Z: (ROM).
  66
  67 The perl @INC search path is now implemented with '?:'. Your perl
  68 executable can now live on a different drive than the perl library or
  69 even your scripts.
  70
  71 ESHELL paths have to be written with backslashes '\', file arguments
  72 to perl with slashes '/'. Remember that I/O redirection is done
  73 internally in perl, so please use slashes for redirects.
  74
  75 perl.exe C:/test.pl >C:/output.txt
  76
  77 You can automatically search for file on all EPOC drives with a ? as
  78 the driver letter. For instance ?:\a.txt searches for C:\a.txt,
  79 D:\b.txt (and Z:\a.txt).
  80
  81 =head2 Editors
  82
  83 A suitable text-editor can be downloaded
  84 from symbian http://developer.epocworld.com/downloads/progs/Editor.zip
  85
  86 =head2 Features
  87
  88 The built-in function EPOC::getcwd returns the current directory.
  89
  90 =head2 Restrictions
  91
  92 Features are left out, because of restrictions of the POSIX support in
  93 EPOC:
  94
  95 =over 4
  96
  97 =item *
  98
  99 backquoting, pipes etc.
 100
 101 =item *
 102
 103 system() does not inherit ressources like: file descriptors,
 104 environment etc.
 105
 106 =item *
 107
 108 signal, kill, alarm. Do not try to use them. This may be
 109 impossible to implement on EPOC.
 110
 111 =item *
 112
 113 select is missing.
 114
 115 =item *
 116
 117 binmode does not exist. (No CR LF to LF translation for text files)
 118
 119 =item *
 120
 121 EPOC does not handle the notion of current drive and current
 122 directory very well (i.e. not at all, but it tries hard to emulate
 123 one) See PATH.
 124
 125 =item *
 126
 127 You need the shell eshell.exe in order to run perl.exe and supply
 128 it with arguments.
 129
 130 =item *
 131
 132 Heap is limited to 4MB.
 133
 134 =back
 135
 136 =head2 Compiling Perl 5 on the EPOC cross compiling environment
 137
 138 Sorry, this is far too short.
 139
 140 =over 4
 141
 142 =item *
 143
 144 You will need the C++ SDK from http://developer.epocworld.com/.
 145
 146 =item *
 147
 148 You will need to set up the cross SDK from
 149 http://members.linuxstart.com/~oflebbe
 150
 151 =item *
 152
 153 You may have to adjust config.sh (cc, cppflags) for your epoc
 154 install location.
 155
 156 =item *
 157
 158 You may have to adjust config.sh for your cross SDK location
 159
 160 =item *
 161
 162 Get the Perl sources from your nearest CPAN site.
 163
 164 =item *
 165
 166 Unpack the sources.
 167
 168 =item *
 169
 170 Build a native perl from this sources...
 171
 172       cp epoc/* .
 173       ./Configure -S
 174       make perl.a
 175       cp miniperl.native miniperl
 176       make perl
 177       make ext/Errno/pm_to_blib
 178       perl link.pl perlmain.o lib/auto/DynaLoader/DynaLoader.a \
 179          lib/auto/Data/Dumper/Dumper.a \
 180          lib/auto/File/Glob/Glob.a lib/auto/IO/IO.a \
 181          lib/auto/Socket/Socket.a \
 182          lib/auto/Fcntl/Fcntl.a lib/auto/Sys/Hostname/Hostname.a \
 183         perl.a `cat ext.libs`
 184       perl createpkg.pl
 185
 186       wine G:/bin/makesis perl.pkg perl.sis
 187
 188 =back
 189
 190 =head1 SUPPORT STATUS
 191
 192 I'm offering this port "as is". You can ask me questions, but I can't
 193 guarantee I'll be able to answer them.
 194
 195 =head1 AUTHOR
 196
 197 Olaf Flebbe <o.flebbe@gmx.de>
 198 http://members.linuxstart.com/~oflebbe/perl/perl5.html
 199
 200 =head1 LAST UPDATE
 201
 202 2000-09-18
 203
 204 =cut