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 | ||
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 |