| 1 | If you read this file _as_is_, just ignore the funny characters you see. |
| 2 | It is written in the POD format (see pod/perlpod.pod) which is specially |
| 3 | designed to be readable as is. |
| 4 | |
| 5 | =head1 NAME |
| 6 | |
| 7 | README.symbian - Perl version 5 on Symbian OS |
| 8 | |
| 9 | =head1 DESCRIPTION |
| 10 | |
| 11 | This document describes various features of the Symbian operating |
| 12 | system that will affect how Perl version 5 (hereafter just Perl) |
| 13 | is compiled and/or runs. |
| 14 | |
| 15 | B<NOTE: this port (as of 0.1.0) does not compile into a Symbian |
| 16 | OS GUI application, but instead it results in a Symbian DLL.> |
| 17 | The DLL includes a C++ class called CPerlBase, which one can then |
| 18 | (derive from and) use to embed Perl into applications, see F<symbian/README>. |
| 19 | |
| 20 | The base port of Perl to Symbian only implements the basic POSIX-like |
| 21 | functionality; it does not implement any further Symbian or Series 60 |
| 22 | bindings for Perl. |
| 23 | |
| 24 | It is also possible to generate Symbian executables for "miniperl" |
| 25 | and "perl", but since there is no standard command line interface |
| 26 | for Symbian (nor full keyboards in the devices), these are useful |
| 27 | mainly as demonstrations. |
| 28 | |
| 29 | =head2 Compiling Perl on Symbian |
| 30 | |
| 31 | (0) You need to have the Symbian SDK installed. |
| 32 | |
| 33 | These instructions have been tested under various Nokia Series 60 |
| 34 | Symbian SDKs (1.2 to 2.6). You can get the SDKs from |
| 35 | Forum Nokia (http://www.forum.nokia.com/). |
| 36 | |
| 37 | A prerequisite for any of the SDKs is to install ActivePerl |
| 38 | from ActiveState, http://www.activestate.com/Products/ActivePerl/ |
| 39 | |
| 40 | Having the SDK installed also means that you need to have either |
| 41 | the Metrowerks CodeWarrior installed (2.8 and 3.0 were used in testing) |
| 42 | or the Microsoft Visual C++ 6.0 installed (SP3 minimum, SP5 recommended). |
| 43 | |
| 44 | Note that for example the Serie s60 2.0 VC SDK installation talks |
| 45 | about ActivePerl build 518, which does no more (as of mid-2004) exist |
| 46 | at the ActiveState website. The ActivePerl 5.8.4 build 810 was |
| 47 | used successfully for compiling Perl on Symbian. The 5.6.x ActivePerls |
| 48 | do not work. |
| 49 | |
| 50 | Other SDKs or compilers like Visual.NET, command-line-only |
| 51 | Visual.NET, Borland, GnuPoc, or sdk2unix have not been tried. |
| 52 | |
| 53 | These instructions almost certainly won't work with older Symbian |
| 54 | releases or other SDKs. Patches to get this port running in other |
| 55 | releases, SDKs, compilers, platforms, or devices are naturally welcome. |
| 56 | |
| 57 | (1) Get a Perl source code distribution (for example the file |
| 58 | perl-5.9.2.tar.gz is fine) from http://www.cpan.org/src/ |
| 59 | and unpack it in your the C:/Symbian directory of your Windows |
| 60 | system. |
| 61 | |
| 62 | (2) Change to the perl source directory. |
| 63 | |
| 64 | cd c:\Symbian\perl-5.x.x |
| 65 | |
| 66 | (3) Run the following script using the perl coming with the SDK |
| 67 | |
| 68 | perl symbian\config.pl |
| 69 | |
| 70 | You must use the cmd.exe, the Cygwin shell will not work |
| 71 | (the PATH must include the SDK tools, including a Perl, |
| 72 | which should be the case under cmd.exe) |
| 73 | |
| 74 | (4) Build the project, either by |
| 75 | |
| 76 | make all |
| 77 | |
| 78 | in cmd.exe or by using either the Metrowerks CodeWarrior |
| 79 | or the Visual C++ 6.0. |
| 80 | |
| 81 | If you use the VC IDE, you will have to run F<symbian\config.pl> |
| 82 | first using the cmd.exe, and then run 'make win.mf vc6.mf' to generate |
| 83 | the VC6 makefiles and workspaces. |
| 84 | |
| 85 | The following Series 60 SDK and compiler configurations and Nokia |
| 86 | phones that were tested (+ = compiled and PerlApp run, - = not), |
| 87 | both for Perl 5.8.x and 5.9.x: |
| 88 | |
| 89 | SDK | VC | CW | |
| 90 | ----+----+----+--- |
| 91 | 1.2 | + | + | 3650 (*) |
| 92 | 2.0 | + | + | 6600 |
| 93 | 2.1 | - | + | 6670 |
| 94 | 2.6 | + | + | 6630 |
| 95 | |
| 96 | If you are using the 'make' directly, it is the GNU make from the SDKs, |
| 97 | and it will invoke the right make commands for the Windows emulator |
| 98 | build and the Arm target builds ('thumb' by default) as necessary. |
| 99 | (*) Compiles but does not work, unfortunately. |
| 100 | |
| 101 | The build scripts assume the 'absolute style' SDK installs under C:, |
| 102 | the 'subst style' will not work. |
| 103 | |
| 104 | If using the VC IDE, to build use for example the File->Open Workspace-> |
| 105 | C:\Symbian\8.as\S60_2nd_FP2\epoc32\build\symbian\perl\perl\wins\perl.dsw |
| 106 | The emulator binaries will appear in the same directory. |
| 107 | |
| 108 | If using the VC IDE, you will a lot of warnings in the beginning of |
| 109 | the build because a lot of headers mentioned by the source cannot |
| 110 | be found, but this is not serious since those headers are not used. |
| 111 | |
| 112 | The Metrowerks will give a lot of warnings about unused variables and |
| 113 | empty declarations, you can ignore those. |
| 114 | |
| 115 | When the Windows and Arm DLLs are built do not be scared by a very long |
| 116 | messages whizzing by: it is the "export freeze" phase where the whole |
| 117 | (rather large) API of Perl is listed. |
| 118 | |
| 119 | Once the build is completed you need to create the DLL SIS file by |
| 120 | |
| 121 | make perldll.sis |
| 122 | |
| 123 | which will create the file perlXYZ.sis (the XYZ being the Perl version) |
| 124 | which you can then install into your Symbian device: an easy way |
| 125 | to do this is to send them via Bluetooth or infrared and just open |
| 126 | the messages. |
| 127 | |
| 128 | Since the total size of all Perl SIS files once installed is |
| 129 | over 1.9 MB, it is recommended to do the installation into a |
| 130 | memory card (drive E:) instead of the C: drive. |
| 131 | |
| 132 | The size of the perlXYZ.SIS is about 370 kB but once it is in the |
| 133 | device it is about one 750 kB (according to the application manager). |
| 134 | |
| 135 | The perlXYZ.sis includes only the Perl DLL: to create an additional |
| 136 | SIS file which includes some of the standard (pure) Perl libraries, |
| 137 | issue the command |
| 138 | |
| 139 | make perllib.sis |
| 140 | |
| 141 | Some of the standard Perl libraries are included, but not all: |
| 142 | see L</HISTORY> or F<symbian\install.cfg> for more details |
| 143 | (250 kB -> 700 kB). |
| 144 | |
| 145 | Some of the standard Perl XS extensions (see L</HISTORY> are |
| 146 | also available: |
| 147 | |
| 148 | make perlext.sis |
| 149 | |
| 150 | which will create perlXYZext.sis (210 kB -> 470 kB). |
| 151 | |
| 152 | To compile the demonstration application PerlApp you need first to |
| 153 | install the Perl headers under the SDK. |
| 154 | |
| 155 | To install the Perl headers and the class CPerlBase documentation |
| 156 | so that you no more need the Perl sources around to compile Perl |
| 157 | applications using the SDK: |
| 158 | |
| 159 | make sdkinstall |
| 160 | |
| 161 | The destination directory is C:\Symbian\perl\X.Y.Z. For more |
| 162 | details, see F<symbian\PerlBase.pod>. |
| 163 | |
| 164 | Once the headers have been installed, you can create a SIS for |
| 165 | the PerlApp: |
| 166 | |
| 167 | make perlapp.sis |
| 168 | |
| 169 | The perlapp.sis (11 kB -> 16 kB) will be built in the symbian |
| 170 | subdirectory, but a copy will also be made to the main directory. |
| 171 | |
| 172 | If you want to package the Perl DLLs (one for WINS, one for ARMI), |
| 173 | the headers, and the documentation: |
| 174 | |
| 175 | make perlsdk.zip |
| 176 | |
| 177 | which will create perlXYZsdk.zip that can be used in another |
| 178 | Windows system with the SDK, without having to compile Perl in |
| 179 | that system. |
| 180 | |
| 181 | If you want to package the PerlApp sources: |
| 182 | |
| 183 | make perlapp.zip |
| 184 | |
| 185 | If you want to package the perl.exe and miniperl.exe, you |
| 186 | can use the perlexe.sis and miniperlexe.sis make targets. |
| 187 | You also probably want the perllib.sis for the libraries |
| 188 | and maybe even the perlapp.sis for the recognizer. |
| 189 | |
| 190 | The make target 'allsis' combines all the above SIS targets. |
| 191 | |
| 192 | To clean up after compilation you can use either of |
| 193 | |
| 194 | make clean |
| 195 | make distclean |
| 196 | |
| 197 | depending on how clean you want to be. |
| 198 | |
| 199 | =head2 Compilation problems |
| 200 | |
| 201 | If you see right after "make" this |
| 202 | |
| 203 | cat makefile.sh >makefile |
| 204 | 'cat' is not recognized as an internal or external command, |
| 205 | operable program or batch file. |
| 206 | |
| 207 | it means you need to (re)run the symbian\config.pl. |
| 208 | |
| 209 | If you get the error |
| 210 | |
| 211 | 'perl' is not recognized as an internal or external command, |
| 212 | operable program or batch file. |
| 213 | |
| 214 | you may need to reinstall the ActivePerl. |
| 215 | |
| 216 | If you see this |
| 217 | |
| 218 | ren makedef.pl nomakedef.pl |
| 219 | The system cannot find the file specified. |
| 220 | C:\Symbian\...\make.exe: [rename_makedef] Error 1 (ignored) |
| 221 | |
| 222 | please ignore it since it is nothing serious (the build process of |
| 223 | renames the Perl makedef.pl as nomakedef.pl to avoid confusing it |
| 224 | with a makedef.pl of the SDK). |
| 225 | |
| 226 | =head2 PerlApp |
| 227 | |
| 228 | The PerlApp application demonstrates how to embed Perl interpreters |
| 229 | to a Symbian application. The "Time" menu item runs the following |
| 230 | Perl code: C<print "Running in ", $^O, "\n", scalar localtime>, |
| 231 | the "Oneliner" allows one to type in Perl code, and the "Run" |
| 232 | opens a file chooser for selecting a Perl file to run. |
| 233 | |
| 234 | The PerlApp also is started when the "Perl recognizer" (also included |
| 235 | and installed) detects a Perl file being activated througg the GUI, |
| 236 | and offers either to install it under \Perl (if the Perl file is in |
| 237 | the inbox of the messaging application) or to run it (if the Perl file |
| 238 | is under \Perl). |
| 239 | |
| 240 | =head2 Using Perl in Symbian |
| 241 | |
| 242 | First of all note that you have full access to the Symbian device |
| 243 | when using Perl: you can do a lot of damage to your device (like |
| 244 | removing system files) unless you are careful. Please do take |
| 245 | backups before doing anything. |
| 246 | |
| 247 | The Perl port has been done for the most part using the Symbian |
| 248 | standard POSIX-ish STDLIB library. It is a reasonably complete |
| 249 | library, but certain corners of such emulation libraries that tend |
| 250 | to be left unimplemented on non-UNIX platforms have been left |
| 251 | unimplemented also this time: fork(), signals(), user/group ids, |
| 252 | select() working for sockets, non-blocking sockets, and so forth. |
| 253 | See the file symbian/config.sh and look for 'undef' to find the |
| 254 | unsupported APIs (or from Perl use Config). |
| 255 | |
| 256 | The filesystem of Symbian devices uses DOSish syntax, "drives" |
| 257 | separated from paths by a colon, and backslashes for the path. |
| 258 | The exact assignment of the drives probably varies between platforms, |
| 259 | but you might for example see C: as the flash main memory, D: as the |
| 260 | RAM drive, E: as the memory card (MMC), Z: as the ROM. As far the |
| 261 | devices go the NUL: is the bit bucket, the COMx: are the serial lines, |
| 262 | IRCOMx: are the IR ports, TMP: might be C:\System\Temp. Remember to |
| 263 | double those backslashes in doublequoted strings. |
| 264 | |
| 265 | The Perl DLL is installed in \System\Libs\. The Perl libraries and |
| 266 | extension DLLs are installed in \System\Libs\Perl\X.Y.Z\. The PerlApp |
| 267 | is installed in \System\Apps\, and the SIS also installs a couple of |
| 268 | demo scripts in \Perl\. |
| 269 | |
| 270 | Note that the Symbian filesystem is very picky: it strongly prefers |
| 271 | the \ instead of the /. |
| 272 | |
| 273 | When doing XS / Symbian C++ programming include first the Symbian |
| 274 | headers, then any standard C/POSIX headers, then Perl headers, and finally |
| 275 | any application headers. |
| 276 | |
| 277 | New() and Copy() are unfortunately used by both Symbian and Perl code |
| 278 | so you'll have to play cpp games if you need them. PerlBase.h undefines |
| 279 | the Perl definitions and redefines them as PerlNew() and PerlCopy(). |
| 280 | |
| 281 | =head1 TO DO |
| 282 | |
| 283 | Lots. See F<symbian\TODO>. |
| 284 | |
| 285 | =head1 WARNING |
| 286 | |
| 287 | As of Perl Symbian port version 0.1.0 any part of Perl's standard |
| 288 | regression test suite has not been run on a real Symbian device using |
| 289 | the ported Perl, so innumerable bugs may lie in wait. Therefore there |
| 290 | is absolutely no warranty. |
| 291 | |
| 292 | =head1 NOTE |
| 293 | |
| 294 | When creating and extending application programming interfaces (APIs) |
| 295 | for Symbian or Series 60 it is suggested that trademarks, registered |
| 296 | trademarks, or trade names are not used in the API names. Instead, |
| 297 | developers should consider basing the API naming in the existing (C++) |
| 298 | public component and API naming, modified as appropriate by the rules |
| 299 | of the programming language the new APIs are for. |
| 300 | |
| 301 | Nokia is a registered trademark of Nokia Corporation. Nokia's product |
| 302 | names are trademarks or registered trademarks of Nokia. Other product |
| 303 | and company names mentioned herein may be trademarks or trade names of |
| 304 | their respective owners. |
| 305 | |
| 306 | =head1 AUTHOR |
| 307 | |
| 308 | Jarkko Hietaniemi |
| 309 | |
| 310 | =head1 COPYRIGHT |
| 311 | |
| 312 | Copyright (c) 2004-2005 Nokia. All rights reserved. |
| 313 | |
| 314 | =head1 LICENSE |
| 315 | |
| 316 | The Symbian port is licensed under the same terms as Perl itself. |
| 317 | |
| 318 | =head1 HISTORY |
| 319 | |
| 320 | Perl Symbian Port version 0.1.0: April 2005 |
| 321 | (This will show as "0.01" in the Symbian Installer.) |
| 322 | |
| 323 | - The console window is a very simple console indeed: one can |
| 324 | get the newline with "000" and the "C" button is a backspace. |
| 325 | Do not expect a terminal capable of vt100 or ANSI sequences. |
| 326 | The console is also "ASCII", you cannot input e.g. any accented |
| 327 | letters. Because of obvious physical constraints the console is |
| 328 | also very small: (in Nokia 6600) 22 columns, 17 rows. |
| 329 | - The following libraries are available: |
| 330 | AnyDBM_File AutoLoader base Carp Config Cwd constant |
| 331 | DynaLoader Exporter File::Spec integer lib strict Symbol |
| 332 | vars warnings XSLoader |
| 333 | - The following extensions are available: |
| 334 | attrs Cwd Data::Dumper Devel::Peek Digest::MD5 DynaLoader |
| 335 | Fcntl File::Glob Filter::Util::Call IO List::Util MIME::Base64 |
| 336 | PerlIO::scalar PerlIO::via SDBM_File Socket Storable Time::HiRes |
| 337 | - The following extensions are missing for various technical reasons: |
| 338 | B ByteLoader Devel::DProf Devel::PPPort Encode GDBM_File |
| 339 | I18N::Langinfo IPC::SysV NDBM_File Opcode PerlIO::encoding POSIX |
| 340 | re Safe Sys::Hostname Sys::Syslog |
| 341 | threads threads::shared Unicode::Normalize |
| 342 | - Using MakeMaker or the Module::* to build and install modules |
| 343 | is not supported. A future solution might use the native |
| 344 | SIS packaging format (see symbian\TODO). |
| 345 | - Building XS other than the ones in the core is not supported. |
| 346 | |
| 347 | Since this is 0.1.0, any future releases are almost guaranteed to be |
| 348 | binary incompatible. As a sign of this the Symbian symbol exports are |
| 349 | kept unfrozen and the .def files rebuilt every time. |
| 350 | |
| 351 | =cut |
| 352 | |