Initial Commit

database/perl/lib/pods/perlsymbian.pod

@@ -0,0 +1,434 @@
+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
+   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