Commit | Line | Data |
---|---|---|
27da23d5 JH |
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 | ||
de2902a6 | 7 | perlsymbian - Perl version 5 on Symbian OS |
27da23d5 JH |
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 | ||
d1dd14d1 | 15 | B<NOTE: this port (as of 0.4.1) does not compile into a Symbian |
27da23d5 JH |
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 | |
25ca88e0 JH |
21 | functionality; it does not implement any further Symbian or Series 60, |
22 | Series 80, or UIQ bindings for Perl. | |
27da23d5 JH |
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 | ||
d1dd14d1 | 31 | (0) You need to have the appropriate Symbian SDK installed. |
27da23d5 | 32 | |
e46aa1dd KW |
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. | |
27da23d5 | 38 | |
e46aa1dd KW |
39 | A prerequisite for any of the SDKs is to install ActivePerl |
40 | from ActiveState, L<http://www.activestate.com/Products/ActivePerl/> | |
27da23d5 | 41 | |
e46aa1dd KW |
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). | |
27da23d5 | 45 | |
e46aa1dd KW |
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. | |
27da23d5 | 51 | |
e46aa1dd KW |
52 | Other SDKs or compilers like Visual.NET, command-line-only |
53 | Visual.NET, Borland, GnuPoc, or sdk2unix have not been tried. | |
27da23d5 | 54 | |
e46aa1dd KW |
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. | |
27da23d5 JH |
58 | |
59 | (1) Get a Perl source code distribution (for example the file | |
e46aa1dd KW |
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. | |
27da23d5 JH |
63 | |
64 | (2) Change to the perl source directory. | |
65 | ||
e46aa1dd | 66 | cd c:\Symbian\perl-5.x.x |
27da23d5 JH |
67 | |
68 | (3) Run the following script using the perl coming with the SDK | |
69 | ||
e46aa1dd | 70 | perl symbian\config.pl |
27da23d5 | 71 | |
e46aa1dd KW |
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. | |
27da23d5 JH |
77 | |
78 | (4) Build the project, either by | |
79 | ||
e46aa1dd | 80 | make all |
27da23d5 | 81 | |
e46aa1dd KW |
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). | |
27da23d5 | 85 | |
e46aa1dd KW |
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. | |
27da23d5 | 90 | |
e46aa1dd KW |
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: | |
27da23d5 | 94 | |
e46aa1dd KW |
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) | |
27da23d5 | 105 | |
e46aa1dd | 106 | (*) Compiles but does not work, unfortunately, a problem with Symbian. |
c042ae3a | 107 | |
e46aa1dd KW |
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. | |
27da23d5 | 111 | |
e46aa1dd KW |
112 | The build scripts assume the 'absolute style' SDK installs under C:, |
113 | the 'subst style' will not work. | |
27da23d5 | 114 | |
e46aa1dd KW |
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. | |
27da23d5 | 118 | |
e46aa1dd KW |
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. | |
27da23d5 | 122 | |
e46aa1dd KW |
123 | The Metrowerks will give a lot of warnings about unused variables and |
124 | empty declarations, you can ignore those. | |
27da23d5 | 125 | |
e46aa1dd KW |
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. | |
27da23d5 | 129 | |
e46aa1dd | 130 | Once the build is completed you need to create the DLL SIS file by |
27da23d5 | 131 | |
e46aa1dd | 132 | make perldll.sis |
27da23d5 | 133 | |
e46aa1dd KW |
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. | |
27da23d5 | 138 | |
e46aa1dd KW |
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. | |
27da23d5 | 142 | |
e46aa1dd KW |
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). | |
27da23d5 | 145 | |
e46aa1dd KW |
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 | |
27da23d5 | 149 | |
e46aa1dd | 150 | make perllib.sis |
27da23d5 | 151 | |
e46aa1dd KW |
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). | |
27da23d5 | 155 | |
e46aa1dd KW |
156 | Some of the standard Perl XS extensions (see L</HISTORY> are |
157 | also available: | |
27da23d5 | 158 | |
e46aa1dd | 159 | make perlext.sis |
27da23d5 | 160 | |
e46aa1dd | 161 | which will create perlXYZext.sis (290 kB -> 770 kB). |
27da23d5 | 162 | |
e46aa1dd KW |
163 | To compile the demonstration application PerlApp you need first to |
164 | install the Perl headers under the SDK. | |
27da23d5 | 165 | |
e46aa1dd KW |
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: | |
27da23d5 | 169 | |
e46aa1dd | 170 | make sdkinstall |
27da23d5 | 171 | |
e46aa1dd KW |
172 | The destination directory is C:\Symbian\perl\X.Y.Z. For more |
173 | details, see F<symbian\PerlBase.pod>. | |
27da23d5 | 174 | |
e46aa1dd KW |
175 | Once the headers have been installed, you can create a SIS for |
176 | the PerlApp: | |
27da23d5 | 177 | |
e46aa1dd | 178 | make perlapp.sis |
27da23d5 | 179 | |
e46aa1dd KW |
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. | |
27da23d5 | 182 | |
e46aa1dd KW |
183 | If you want to package the Perl DLLs (one for WINS, one for ARMI), |
184 | the headers, and the documentation: | |
27da23d5 | 185 | |
e46aa1dd | 186 | make perlsdk.zip |
27da23d5 | 187 | |
e46aa1dd KW |
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. | |
27da23d5 | 191 | |
e46aa1dd | 192 | If you want to package the PerlApp sources: |
27da23d5 | 193 | |
e46aa1dd | 194 | make perlapp.zip |
27da23d5 | 195 | |
e46aa1dd KW |
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. | |
27da23d5 | 200 | |
e46aa1dd | 201 | The make target 'allsis' combines all the above SIS targets. |
27da23d5 | 202 | |
e46aa1dd | 203 | To clean up after compilation you can use either of |
27da23d5 | 204 | |
e46aa1dd KW |
205 | make clean |
206 | make distclean | |
27da23d5 | 207 | |
e46aa1dd | 208 | depending on how clean you want to be. |
27da23d5 JH |
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 | ||
0f25a69f | 218 | it means you need to (re)run the F<symbian\config.pl>. |
27da23d5 JH |
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 | |
f858446f | 246 | and installed) detects a Perl file being activated through the GUI, |
27da23d5 JH |
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 | ||
f26f4a2f JH |
251 | =head2 sisify.pl |
252 | ||
0f25a69f MS |
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/>. | |
f26f4a2f | 259 | |
27da23d5 JH |
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. | |
0f25a69f | 273 | See the file F<symbian/config.sh> and look for 'undef' to find the |
27da23d5 | 274 | unsupported APIs (or from Perl use Config). |
3fa5404d | 275 | |
27da23d5 | 276 | The filesystem of Symbian devices uses DOSish syntax, "drives" |
ed76c0e4 JH |
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. | |
27da23d5 JH |
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 | |
53d44271 | 289 | demo scripts in \Perl\ (C:\Mydocs\Perl\ on Nokia 7710). |
27da23d5 JH |
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 | ||
56466d0e | 304 | Lots. See F<symbian/TODO>. |
27da23d5 JH |
305 | |
306 | =head1 WARNING | |
307 | ||
d1dd14d1 | 308 | As of Perl Symbian port version 0.4.1 any part of Perl's standard |
27da23d5 JH |
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) | |
d1dd14d1 JH |
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. | |
3fa5404d | 322 | |
27da23d5 JH |
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 | ||
4764e399 JH |
336 | Copyright (c) 2006-2007 Jarkko Hietaniemi. |
337 | ||
27da23d5 JH |
338 | =head1 LICENSE |
339 | ||
340 | The Symbian port is licensed under the same terms as Perl itself. | |
341 | ||
342 | =head1 HISTORY | |
343 | ||
f26f4a2f JH |
344 | =over 4 |
345 | ||
346 | =item * | |
347 | ||
348 | 0.1.0: April 2005 | |
349 | ||
27da23d5 JH |
350 | (This will show as "0.01" in the Symbian Installer.) |
351 | ||
e46aa1dd KW |
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 | |
6201c220 | 370 | IPC::SysV NDBM_File Opcode PerlIO::encoding POSIX |
e46aa1dd KW |
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. | |
27da23d5 | 376 | |
f26f4a2f JH |
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 | |
db5886f1 JH |
379 | symbol exports are kept unfrozen and the .def files fully rebuilt |
380 | every time. | |
f26f4a2f JH |
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 | ||
25ca88e0 JH |
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 | ||
db5886f1 JH |
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 | ||
4764e399 JH |
410 | =item * |
411 | ||
53d44271 JH |
412 | 0.4.1: December 2006 |
413 | ||
4764e399 | 414 | - Perl 5.9.5-to-be (patch level 30002) |
53d44271 JH |
415 | - added extensions: Compress/Raw/Zlib, Digest/SHA, |
416 | Hash/Util, Math/BigInt/FastCalc, Text/Soundex, Time/Piece | |
d1dd14d1 | 417 | - port to S90 1.1 by alexander smishlajev |
53d44271 JH |
418 | |
419 | We maintain the binary incompatibility. | |
420 | ||
4764e399 JH |
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 | ||
f26f4a2f | 432 | =back |
27da23d5 JH |
433 | |
434 | =cut |