diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlsymbian.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlsymbian.pod | 432 |
1 files changed, 0 insertions, 432 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod b/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod deleted file mode 100644 index 2572631c12a..00000000000 --- a/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod +++ /dev/null @@ -1,432 +0,0 @@ -If you read this file _as_is_, just ignore the funny characters you see. -It is written in the POD format (see pod/perlpod.pod) which is specially -designed to be readable as is. - -=head1 NAME - -perlsymbian - Perl version 5 on Symbian OS - -=head1 DESCRIPTION - -This document describes various features of the Symbian operating -system that will affect how Perl version 5 (hereafter just Perl) -is compiled and/or runs. - -B<NOTE: this port (as of 0.4.1) does not compile into a Symbian -OS GUI application, but instead it results in a Symbian DLL.> -The DLL includes a C++ class called CPerlBase, which one can then -(derive from and) use to embed Perl into applications, see F<symbian/README>. - -The base port of Perl to Symbian only implements the basic POSIX-like -functionality; it does not implement any further Symbian or Series 60, -Series 80, or UIQ bindings for Perl. - -It is also possible to generate Symbian executables for "miniperl" -and "perl", but since there is no standard command line interface -for Symbian (nor full keyboards in the devices), these are useful -mainly as demonstrations. - -=head2 Compiling Perl on Symbian - -(0) You need to have the appropriate Symbian SDK installed. - - These instructions have been tested under various Nokia Series 60 - Symbian SDKs (1.2 to 2.6, 2.8 should also work, 1.2 compiles but - does not work), Series 80 2.0, and Nokia 7710 (Series 90) SDK. - You can get the SDKs from Forum Nokia (L<http://www.forum.nokia.com/>). - A very rough port ("it compiles") to UIQ 2.1 has also been made. - - A prerequisite for any of the SDKs is to install ActivePerl - from ActiveState, L<http://www.activestate.com/Products/ActivePerl/> - - Having the SDK installed also means that you need to have either - the Metrowerks CodeWarrior installed (2.8 and 3.0 were used in testing) - or the Microsoft Visual C++ 6.0 installed (SP3 minimum, SP5 recommended). - - Note that for example the Series 60 2.0 VC SDK installation talks - about ActivePerl build 518, which does no more (as of mid-2005) exist - at the ActiveState website. The ActivePerl 5.8.4 build 810 was - used successfully for compiling Perl on Symbian. The 5.6.x ActivePerls - do not work. - - Other SDKs or compilers like Visual.NET, command-line-only - Visual.NET, Borland, GnuPoc, or sdk2unix have not been tried. - - These instructions almost certainly won't work with older Symbian - releases or other SDKs. Patches to get this port running in other - releases, SDKs, compilers, platforms, or devices are naturally welcome. - -(1) Get a Perl source code distribution (for example the file - perl-5.9.2.tar.gz is fine) from L<http://www.cpan.org/src/> - and unpack it in your the C:/Symbian directory of your Windows - system. - -(2) Change to the perl source directory. - - cd c:\Symbian\perl-5.x.x - -(3) Run the following script using the perl coming with the SDK - - perl symbian\config.pl - - You must use the cmd.exe, the Cygwin shell will not work. - The PATH must include the SDK tools, including a Perl, - which should be the case under cmd.exe. If you do not - have that, see the end of symbian\sdk.pl for notes of - how your environment should be set up for Symbian compiles. - -(4) Build the project, either by - - make all - - in cmd.exe or by using either the Metrowerks CodeWarrior - or the Visual C++ 6.0, or the Visual Studio 8 (the Visual C++ - 2005 Express Edition works fine). - - If you use the VC IDE, you will have to run F<symbian\config.pl> - first using the cmd.exe, and then run 'make win.mf vc6.mf' to generate - the VC6 makefiles and workspaces. "make vc6" will compile for the VC6, - and "make cw" for the CodeWarrior. - - The following SDK and compiler configurations and Nokia phones were - tested at some point in time (+ = compiled and PerlApp run, - = not), - both for Perl 5.8.x and 5.9.x: - - SDK | VC | CW | - --------+----+----+--- - S60 1.2 | + | + | 3650 (*) - S60 2.0 | + | + | 6600 - S60 2.1 | - | + | 6670 - S60 2.6 | + | + | 6630 - S60 2.8 | + | + | (not tested in a device) - S80 2.6 | - | + | 9300 - S90 1.1 | + | - | 7710 - UIQ 2.1 | - | + | (not tested in a device) - - (*) Compiles but does not work, unfortunately, a problem with Symbian. - - If you are using the 'make' directly, it is the GNU make from the SDKs, - and it will invoke the right make commands for the Windows emulator - build and the Arm target builds ('thumb' by default) as necessary. - - The build scripts assume the 'absolute style' SDK installs under C:, - the 'subst style' will not work. - - If using the VC IDE, to build use for example the File->Open Workspace-> - C:\Symbian\8.0a\S60_2nd_FP2\epoc32\build\symbian\perl\perl\wins\perl.dsw - The emulator binaries will appear in the same directory. - - If using the VC IDE, you will a lot of warnings in the beginning of - the build because a lot of headers mentioned by the source cannot - be found, but this is not serious since those headers are not used. - - The Metrowerks will give a lot of warnings about unused variables and - empty declarations, you can ignore those. - - When the Windows and Arm DLLs are built do not be scared by a very long - messages whizzing by: it is the "export freeze" phase where the whole - (rather large) API of Perl is listed. - - Once the build is completed you need to create the DLL SIS file by - - make perldll.sis - - which will create the file perlXYZ.sis (the XYZ being the Perl version) - which you can then install into your Symbian device: an easy way - to do this is to send them via Bluetooth or infrared and just open - the messages. - - Since the total size of all Perl SIS files once installed is - over 2 MB, it is recommended to do the installation into a - memory card (drive E:) instead of the C: drive. - - The size of the perlXYZ.SIS is about 370 kB but once it is in the - device it is about one 750 kB (according to the application manager). - - The perlXYZ.sis includes only the Perl DLL: to create an additional - SIS file which includes some of the standard (pure) Perl libraries, - issue the command - - make perllib.sis - - Some of the standard Perl libraries are included, but not all: - see L</HISTORY> or F<symbian\install.cfg> for more details - (250 kB -> 700 kB). - - Some of the standard Perl XS extensions (see L</HISTORY> are - also available: - - make perlext.sis - - which will create perlXYZext.sis (290 kB -> 770 kB). - - To compile the demonstration application PerlApp you need first to - install the Perl headers under the SDK. - - To install the Perl headers and the class CPerlBase documentation - so that you no more need the Perl sources around to compile Perl - applications using the SDK: - - make sdkinstall - - The destination directory is C:\Symbian\perl\X.Y.Z. For more - details, see F<symbian\PerlBase.pod>. - - Once the headers have been installed, you can create a SIS for - the PerlApp: - - make perlapp.sis - - The perlapp.sis (11 kB -> 16 kB) will be built in the symbian - subdirectory, but a copy will also be made to the main directory. - - If you want to package the Perl DLLs (one for WINS, one for ARMI), - the headers, and the documentation: - - make perlsdk.zip - - which will create perlXYZsdk.zip that can be used in another - Windows system with the SDK, without having to compile Perl in - that system. - - If you want to package the PerlApp sources: - - make perlapp.zip - - If you want to package the perl.exe and miniperl.exe, you - can use the perlexe.sis and miniperlexe.sis make targets. - You also probably want the perllib.sis for the libraries - and maybe even the perlapp.sis for the recognizer. - - The make target 'allsis' combines all the above SIS targets. - - To clean up after compilation you can use either of - - make clean - make distclean - - depending on how clean you want to be. - -=head2 Compilation problems - -If you see right after "make" this - - cat makefile.sh >makefile - 'cat' is not recognized as an internal or external command, - operable program or batch file. - -it means you need to (re)run the F<symbian\config.pl>. - -If you get the error - - 'perl' is not recognized as an internal or external command, - operable program or batch file. - -you may need to reinstall the ActivePerl. - -If you see this - - ren makedef.pl nomakedef.pl - The system cannot find the file specified. - C:\Symbian\...\make.exe: [rename_makedef] Error 1 (ignored) - -please ignore it since it is nothing serious (the build process of -renames the Perl makedef.pl as nomakedef.pl to avoid confusing it -with a makedef.pl of the SDK). - -=head2 PerlApp - -The PerlApp application demonstrates how to embed Perl interpreters -to a Symbian application. The "Time" menu item runs the following -Perl code: C<print "Running in ", $^O, "\n", scalar localtime>, -the "Oneliner" allows one to type in Perl code, and the "Run" -opens a file chooser for selecting a Perl file to run. - -The PerlApp also is started when the "Perl recognizer" (also included -and installed) detects a Perl file being activated through the GUI, -and offers either to install it under \Perl (if the Perl file is in -the inbox of the messaging application) or to run it (if the Perl file -is under \Perl). - -=head2 sisify.pl - -In the symbian subdirectory there is F<sisify.pl> utility which can be used -to package Perl scripts and/or Perl library directories into SIS files, -which can be installed to the device. To run the sisify.pl utility, -you will need to have the 'makesis' and 'uidcrc' utilities already -installed. If you don't have the Win32 SDKs, you may try for example -L<http://gnupoc.sourceforge.net/> or L<http://symbianos.org/~andreh/>. - -=head2 Using Perl in Symbian - -First of all note that you have full access to the Symbian device -when using Perl: you can do a lot of damage to your device (like -removing system files) unless you are careful. Please do take -backups before doing anything. - -The Perl port has been done for the most part using the Symbian -standard POSIX-ish STDLIB library. It is a reasonably complete -library, but certain corners of such emulation libraries that tend -to be left unimplemented on non-UNIX platforms have been left -unimplemented also this time: fork(), signals(), user/group ids, -select() working for sockets, non-blocking sockets, and so forth. -See the file F<symbian/config.sh> and look for 'undef' to find the -unsupported APIs (or from Perl use Config). - -The filesystem of Symbian devices uses DOSish syntax, "drives" -separated from paths by a colon, and backslashes for the path. The -exact assignment of the drives probably varies between platforms, but -for example in Series 60 you might see C: as the (flash) main memory, -D: as the RAM drive, E: as the memory card (MMC), Z: as the ROM. In -Series 80 D: is the memory card. As far the devices go the NUL: is -the bit bucket, the COMx: are the serial lines, IRCOMx: are the IR -ports, TMP: might be C:\System\Temp. Remember to double those -backslashes in doublequoted strings. - -The Perl DLL is installed in \System\Libs\. The Perl libraries and -extension DLLs are installed in \System\Libs\Perl\X.Y.Z\. The PerlApp -is installed in \System\Apps\, and the SIS also installs a couple of -demo scripts in \Perl\ (C:\Mydocs\Perl\ on Nokia 7710). - -Note that the Symbian filesystem is very picky: it strongly prefers -the \ instead of the /. - -When doing XS / Symbian C++ programming include first the Symbian -headers, then any standard C/POSIX headers, then Perl headers, and finally -any application headers. - -New() and Copy() are unfortunately used by both Symbian and Perl code -so you'll have to play cpp games if you need them. PerlBase.h undefines -the Perl definitions and redefines them as PerlNew() and PerlCopy(). - -=head1 TO DO - -Lots. See F<symbian/TODO>. - -=head1 WARNING - -As of Perl Symbian port version 0.4.1 any part of Perl's standard -regression test suite has not been run on a real Symbian device using -the ported Perl, so innumerable bugs may lie in wait. Therefore there -is absolutely no warranty. - -=head1 NOTE - -When creating and extending application programming interfaces (APIs) -for Symbian or Series 60 or Series 80 or Series 90 it is suggested -that trademarks, registered trademarks, or trade names are not used in -the API names. Instead, developers should consider basing the API -naming in the existing (C++, or maybe Java) public component and API -naming, modified as appropriate by the rules of the programming -language the new APIs are for. - -Nokia is a registered trademark of Nokia Corporation. Nokia's product -names are trademarks or registered trademarks of Nokia. Other product -and company names mentioned herein may be trademarks or trade names of -their respective owners. - -=head1 AUTHOR - -Jarkko Hietaniemi - -=head1 COPYRIGHT - -Copyright (c) 2004-2005 Nokia. All rights reserved. - -Copyright (c) 2006-2007 Jarkko Hietaniemi. - -=head1 LICENSE - -The Symbian port is licensed under the same terms as Perl itself. - -=head1 HISTORY - -=over 4 - -=item * - -0.1.0: April 2005 - -(This will show as "0.01" in the Symbian Installer.) - - - The console window is a very simple console indeed: one can - get the newline with "000" and the "C" button is a backspace. - Do not expect a terminal capable of vt100 or ANSI sequences. - The console is also "ASCII", you cannot input e.g. any accented - letters. Because of obvious physical constraints the console is - also very small: (in Nokia 6600) 22 columns, 17 rows. - - The following libraries are available: - AnyDBM_File AutoLoader base Carp Config Cwd constant - DynaLoader Exporter File::Spec integer lib strict Symbol - vars warnings XSLoader - - The following extensions are available: - attributes Compress::Zlib Cwd Data::Dumper Devel::Peek Digest::MD5 DynaLoader - Fcntl File::Glob Filter::Util::Call IO List::Util MIME::Base64 - PerlIO::scalar PerlIO::via SDBM_File Socket Storable Time::HiRes - - The following extensions are missing for various technical reasons: - B ByteLoader Devel::DProf Devel::PPPort Encode GDBM_File - I18N::Langinfo IPC::SysV NDBM_File Opcode PerlIO::encoding POSIX - re Safe Sys::Hostname Sys::Syslog - threads threads::shared Unicode::Normalize - - Using MakeMaker or the Module::* to build and install modules - is not supported. - - Building XS other than the ones in the core is not supported. - -Since this is 0.something release, any future releases are almost -guaranteed to be binary incompatible. As a sign of this the Symbian -symbol exports are kept unfrozen and the .def files fully rebuilt -every time. - -=item * - -0.2.0: October 2005 - - - Perl 5.9.3 (patch level 25741) - - Compress::Zlib and IO::Zlib supported - - sisify.pl added - -We maintain the binary incompatibility. - -=item * - -0.3.0: October 2005 - - - Perl 5.9.3 (patch level 25911) - - Series 80 2.0 and UIQ 2.1 support - -We maintain the binary incompatibility. - -=item * - -0.4.0: November 2005 - - - Perl 5.9.3 (patch level 26052) - - adding a sample Symbian extension - -We maintain the binary incompatibility. - -=item * - -0.4.1: December 2006 - - - Perl 5.9.5-to-be (patch level 30002) - - added extensions: Compress/Raw/Zlib, Digest/SHA, - Hash/Util, Math/BigInt/FastCalc, Text/Soundex, Time/Piece - - port to S90 1.1 by alexander smishlajev - -We maintain the binary incompatibility. - -=item * - -0.4.2: March 2007 - - - catchup with Perl 5.9.5-to-be (patch level 30812) - - tested to build with Microsoft Visual C++ 2005 Express Edition - (which uses Microsoft Visual C 8, instead of the old VC6), - SDK used for testing S60_2nd_FP3 aka 8.1a - -We maintain the binary incompatibility. - -=back - -=cut |