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