"Fossies" - the Fresh Open Source Software Archive

Member "perl-5.32.1/README.symbian" (18 Dec 2020, 15344 Bytes) of package /linux/misc/perl-5.32.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

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