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