Symbian port of Perl

Message-ID: <B356D8F434D20B40A8CEDAEC305A1F2453D653@esebe105.NOE.Nokia.com>

p4raw-id: //depot/perl@24271

1 files changed, 352 insertions, 0 deletions

diff --git a/README.symbian b/README.symbian
new file mode 100644
index 0000000000..e6cb4dc643
--- /dev/null
+++ b/README.symbian
@@ -0,0 +1,352 @@
+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
+
+README.symbian - 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.1.0) 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
+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 Symbian SDK installed.
+
+    These instructions have been tested under various Nokia Series 60
+    Symbian SDKs (1.2 to 2.6).  You can get the SDKs from
+    Forum Nokia (http://www.forum.nokia.com/).
+
+    A prerequisite for any of the SDKs is to install ActivePerl
+    from ActiveState, 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 Serie s60 2.0 VC SDK installation talks
+    about ActivePerl build 518, which does no more (as of mid-2004) 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 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)
+
+(4) Build the project, either by
+
+	make all
+
+    in cmd.exe or by using either the Metrowerks CodeWarrior
+    or the Visual C++ 6.0.
+
+    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.
+
+    The following Series 60 SDK and compiler configurations and Nokia
+    phones that were tested (+ = compiled and PerlApp run, - = not),
+    both for Perl 5.8.x and 5.9.x:
+
+        SDK | VC | CW |
+        ----+----+----+---
+        1.2 | +  | +  | 3650 (*)
+        2.0 | +  | +  | 6600
+        2.1 | -  | +  | 6670
+        2.6 | +  | +  | 6630    
+
+    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.
+    (*) Compiles but does not work, unfortunately.
+
+    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.as\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 1.9 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 (210 kB -> 470 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 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 througg 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 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 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 you might for example see C: as the flash main memory, D: as the
+RAM drive, E: as the memory card (MMC), Z: as the ROM.  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\.
+
+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.1.0 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 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++)
+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.
+
+=head1 LICENSE
+
+The Symbian port is licensed under the same terms as Perl itself.
+
+=head1 HISTORY
+
+Perl Symbian Port version 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:
+    attrs 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.  A future solution might use the native
+    SIS packaging format (see symbian\TODO).
+  - Building XS other than the ones in the core is not supported.
+
+Since this is 0.1.0, 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 rebuilt every time.
+
+=cut
+