--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/tools/py2sis/ensymble/README Tue Feb 16 10:07:05 2010 +0530
@@ -0,0 +1,1412 @@
+ The Ensymble developer utilities for Symbian OS
+ Copyright 2006, 2007, 2008, 2009 Jussi Ylänen
+ Portions Copyright (c) 2008 - 2009 Nokia Corporation
+
+ Last updated 2009-01-30
+
+
+ABOUT
+=====
+
+This is the Ensymble developer utilities for Symbian OS(TM), a
+collection of Python® modules and command line programs for Symbian OS
+[1] software development.
+
+Current focus of Ensymble development is to provide useful tools for
+making "Python for S60" [2] (also called PyS60) programs. Supported
+functions include generation of SIS (installation) packages, merging
+several SIS packages into one, (re-)signing existing SIS packages and
+modifying extension DLL headers. Support for other Symbian OS software
+development tasks will follow.
+
+A long term goal of Ensymble is to provide a cross-platform, open-source
+way to do Symbian OS software development, supporting Symbian OS
+versions 9.1 and later. The original tools by Symbian are closed source
+and only available for the Windows® operating system.
+
+Symbian OS is the operating system used by Nokia [3] in some of its
+mobile phones [4]. Other manufacturers have also licensed Symbian OS.
+Python for S60 is a port of the popular Python programming language [5]
+to a Nokia phone platform called S60® [6]. Before November 2005, S60 was
+called Series 60.
+
+
+VERSION COMPATIBILITY
+=====================
+
+Ensymble targets Symbian OS v9.1 and later. For Nokia phones, this means
+S60 3rd Edition. 1st and 2nd Edition phones are not directly supported
+by Ensymble. A program called py2sisng [7] supports 1st and 2nd Edition
+phones and can be used for a subset of tasks that Ensymble performs.
+
+The py2sis command of the Ensymble command line tool produces
+installation packages (SIS) for Python for S60 version 1.4.0 and later.
+Version 1.4.0 of Python for S60 is the first officially signed release
+from Nokia. Although packages generated with Ensymble also work with
+PyS60 from v1.3.8 upto v1.3.23, a harmless warning is generated during
+installation for a missing Python for S60 component.
+
+Ensymble is written in Python. Python v2.2 or newer is required, as
+older versions lack necessary language features. Ensymble has been
+tested on the following systems:
+
+ * Debian GNU/Linux Sid (i386) with Python v2.3.5, v2.4.5 and v2.5.2
+ * Red Hat Linux release 9 (i386) with Python v2.2.2
+ * Red Hat Enterprise Linux AS release 3 (i386) with Python v2.2.3
+ * Red Hat Enterprise Linux AS release 4 (i386) with Python v2.3.4
+ * Apple OS X Tiger (G4) with Python v2.3.5
+ * Apple OS X Leopard (i386) with Python v2.5
+ * Microsoft Windows XP, SP2 with Python v2.5
+
+Note: Python for S60 versions 1.3.20 and older require that SIS files
+generated by Ensymble are installed into main phone memory instead of
+memory card. This bug has been corrected in version 1.3.21 of PyS60.
+
+
+INSTALLATION
+============
+
+Care has been taken to ensure that minimum amount of extra software is
+needed to run Ensymble. A working installation of Python is required
+(see VERSION COMPATIBILITY above). In addition, the OpenSSL command line
+tool [8] is required for installation package (SIS) generation, merging
+and (re-)signing. Any recent version will do, and can usually be found
+pre-installed. For Windows, the Stunnel OpenSSL binaries [9] are
+recommended, but any other binaries will do as well.
+
+The Ensymble command line tool is normally installed as a single file
+"ensymble.py". This file contains everything except the OpenSSL command
+line tool and is created using Fredrik Lundh's nifty squeeze utility
+[10]. Pre-squeezed files for various Python versions may be downloaded
+from the Ensymble home page. To find out which version to download, type
+"python -V" on the command line:
+
+ $ python -V
+ Python 2.4.4
+
+or
+
+ C:\> python -V
+ Python 2.4.4
+
+A pre-squeezed version for Python 2.4 would be the correct one in this
+case.
+
+Users on Unix-like systems (Linux, *BSD, Apple OS X) can download the
+correct pre-squeezed version and put in in the "bin" directory under the
+user's home directory (if such a thing exists), and possibly rename the
+file to "ensymble.py" as well.
+
+Windows users need to download "openssl.zip" (NOT "stunnel-n.nn.exe" or
+"stunnel-n.nn-installer.exe") [9] and unpack it somewhere, for example
+"C:\Ensymble", and then put the correct pre-squeezed version of Ensymble
+there as well, renamed to "ensymble.py":
+
+ C:\Ensymble\ [directory]
+ ensymble.py [76046 bytes]
+ openssl.exe [1153024 bytes]
+ libssl32.dll [632226 bytes]
+ libeay32.dll [1578787 bytes]
+
+To allow using the Ensymble command line tool without explicitly giving
+a full command path each time, it is advisable to add the installation
+directory ("C:\Ensymble" in the example above) in the Path environment
+variable in Windows' environment variables dialog (My Computer ->
+Properties -> Advanced -> Environment Variables -> System Variables ->
+Path). The Command Prompt window must be restarted after the change.
+
+Installation is also possible from the original source package. For
+Unix-like systems, there is a simple installation script which squeezes
+all the required files together and copies the resulting package to a
+given directory (which must exist already):
+
+ $ ./install.sh ~/bin
+
+
+USAGE
+=====
+
+DESCRIPTION
+
+The Ensymble command line tool provides access to most Ensymble
+functionality:
+
+ $ ensymble.py command options...
+
+, where "command" is the command to be executed and "options" are the
+command specific options. Running ensymble.py without arguments will
+list all the available commands.
+
+The following commands are currently supported by Ensymble:
+
+ altere32 Alter the IDs and capabilities of e32image files (EXEs, DLLs)
+ genuid Generate a new test-range UID from a name
+ infoe32 Show the IDs and capabilities of e32image files (EXEs, DLLs)
+ mergesis Merge several SIS packages into one
+ py2sis Create a SIS package for a "Python for S60" application
+ signsis Sign a SIS package
+ simplesis Create a SIS package from a directory structure
+ version Print Ensymble version
+
+Each command is documented in detail below.
+
+Note about security: When using SIS certificates, the private key of the
+certificate is saved unencrypted to a temporary file and could be
+recovered by others. This is due to compatibility with old versions of
+OpenSSL. In the future, Ensymble may require a more recent version of
+OpenSSL.
+
+
+COMMON OPTIONS
+
+ --encoding=terminal,filesystem
+ -e terminal,filesystem
+
+Local character encodings for terminal and filesystem. For example
+"--encoding=utf8,latin1", if the terminal is using a UTF-8 character set
+and the filesystem is still using the older latin1 (ISO-8859-1)
+character set. See [11] for a list of Python standard encodings.
+
+The encodings will be autodetected most of the time, but on some special
+environments this may not be possible, hence this option.
+
+ --verbose
+ -v
+
+Print extra statistics, such as file names, option summary.
+
+ --help
+ -h
+
+On-line help for a command can be found using this option.
+
+
+EXAMPLES
+
+ $ ensymble.py
+
+ Ensymble developer utilities for Symbian OS
+
+ usage: ensymble.py command [command options]...
+
+ Commands:
+ altere32 Alter the IDs and capabilities of e32image files (EXEs, DLLs)
+ genuid Generate a new test-range UID from a name
+ infoe32 Show the IDs and capabilities of e32image files (EXEs, DLLs)
+ mergesis Merge several SIS packages into one
+ py2sis Create a SIS package for a "Python for S60" application
+ signsis Sign a SIS package
+ simplesis Create a SIS package from a directory structure
+ version Print Ensymble version
+
+ Use 'ensymble.py command --help' to get command specific help.
+
+When no commands and options are given, Ensymble prints a short help.
+
+ $ ensymble.py version -h
+
+ Ensymble developer utilities for Symbian OS
+
+ usage: ensymble.py version
+
+ Print Ensymble version.
+
+Each command has an on-line help. A short description of what the
+command does and a list of options are printed.
+
+
+The "altere32" command
+----------------------
+
+SYNOPSIS
+
+ $ ensymble.py altere32
+ [--uid=0x01234567] [--secureid=0x01234567] [--vendorid=0x01234567]
+ [--caps=Cap1+Cap2+...] [--encoding=terminal,filesystem] [--verbose]
+ <infile> <outfile>
+
+or
+
+ $ ensymble.py altere32
+ [--uid=0x01234567] [--secureid=0x01234567] [--vendorid=0x01234567]
+ [--caps=Cap1+Cap2+...] [--encoding=terminal,filesystem] [--verbose]
+ --inplace <infile>...
+
+
+DESCRIPTION
+
+The "altere32" command alters the IDs and capabilities of e32image files
+(Symbian EXEs and DLLs). Extension module authors can use this command
+to quickly generate variations of extension modules without recompiling.
+
+
+PARAMETERS
+
+ infile
+
+Path of the original e32image file. If option "--inplace" (see below) is
+set, there may be more than one file name present.
+
+ outfile
+
+Path of the modified e32image file. Only used when not using option
+"--inplace", see below. If a directory name is given, input file name is
+used as the output file name.
+
+ --inplace
+ -i
+
+Allow more than one input file name, modify input files in-place.
+
+Note: Use this option with caution, as no backups of the original files
+will be made!
+
+ --uid=0x01234567
+ -u 0x01234567
+
+Symbian UID for the e32image. This is normally same as the secure ID,
+see below. If this option is not given, the UID is not changed.
+
+ --secureid=0x01234567
+ -s 0x01234567
+
+Secure ID for the e32image. This is normally same as the UID, see above.
+If this option is not given, the secure ID is not changed.
+
+ --vendorid=0x01234567
+ -r 0x01234567
+
+Vendor ID for the e32image. In most cases the vendor ID is 0. If this
+option is not given, the vendor ID is not changed.
+
+ --caps=Cap1+Cap2+...
+ -b Cap1+Cap2+...
+
+or
+
+ --caps=0x12345
+ -b 0x12345
+
+Capability names separated by "+" or a numeric capability bitmask. If no
+capability option is given, capabilities are not changed.
+
+ --heapsize=min,max
+ -H min,max
+
+Heap size limits for the e32image, only valid for EXEs. If no heap size
+option is given, the heap size limits are not changed. If only one value
+is given, it is used as both the heap minimum value and heap maximum
+value.
+
+Values may have suffix "k" or "M" (case insensitive) to denote kilobytes
+(1024 bytes) and megabytes (1048576 bytes), respectively.
+
+The heap minimum value determines if a program is allowed to start. If
+less than the set amount of memory is available, program start-up fails.
+The heap maximum value limits the memory a program can allocate. Memory
+allocations beyond the set limit will fail.
+
+
+EXAMPLES
+
+Note: The command lines below may be wrapped over multiple lines due to
+layout constraints. In reality, each of them should be contained in one
+physical command line, with no spaces around the "+" characters.
+
+ $ ensymble.py altere32
+ --caps=LocalServices+Location+NetworkServices+PowerMgmt+ProtServ+
+ ReadUserData+SurroundingsDD+SWEvent+UserEnvironment+WriteUserData+
+ ReadDeviceData+TrustedUI+WriteDeviceData
+ myextension_orig.pyd myextension.pyd
+
+This will modify "myextension_orig.pyd" (a "Python for S60" extension
+DLL) with the capabilities listed, and generate file "myextension.pyd"
+with the new capabilities.
+
+ $ ensymble.py altere32 --caps=0xff1b4 --inplace *.dll
+
+This modifies every DLL file in the current directory using the same
+capabilities as above but in a numeric form. Original files will be
+modified, so use the "--inplace" option with caution!
+
+ $ ensymble.py altere32 --heapsize=4k,4M myapp_orig.exe myapp.exe
+
+Program "myapp.exe" is modified so that it can allocate upto four
+megabytes of memory. Heap minimum value is usually kept at the default
+four kilobytes.
+
+Note: When modifying the UID, the secure ID should be modified
+accordingly. Modifying UIDs of application EXEs is generally not
+possible, because applications usually include the UID in program code
+as well.
+
+
+The "genuid" command
+--------------------
+
+SYNOPSIS
+
+ $ ensymble.py genuid
+ [--encoding=terminal,filesystem] [--verbose]
+ <name>...
+
+
+DESCRIPTION
+
+The "genuid" command generates a test-range UID from an application or
+extension module name. It is suggested that Ensymble-generated UIDs are
+used instead of choosing an arbitrary test-range UID, to prevent clashes
+with software from other authors.
+
+
+PARAMETERS
+
+ name
+
+One or more names for which UIDs are generated. Names are
+case-insensitive and fully support the international Unicode characters.
+
+Generated UIDs are compatible with the automatic UID generation of
+py2sis and simplesis commands. The name must not contain version
+information or any file prefixes, just the name itself, e.g.
+"myextension" instead of "myextension_v1.2.3.sis".
+
+
+EXAMPLES
+
+ $ ensymble.py genuid myapplication myextension
+ myapplication: 0xe0942bea
+ myextension: 0xe325ed58
+
+This will generate two UIDs: one for "myapplication" and another for
+"myextension".
+
+
+The "infoe32" command
+---------------------
+
+SYNOPSIS
+
+ $ ensymble.py infoe32
+ [--encoding=terminal,filesystem] [--verbose]
+ <infile>...
+
+
+DESCRIPTION
+
+The "infoe32" command displays information about Symbian e32image files
+(Symbian EXEs and DLLs). All three UIDs as well as the vendor ID and
+secure ID are printed. Capabilities are displayed textually and as a
+hexadecimal number.
+
+
+PARAMETERS
+
+ infile
+
+One or more e32image files to inspect.
+
+
+EXAMPLES
+
+ $ ensymble.py infoe32 myprogram.exe somelibrary.dll
+ myprogram.exe:
+ UID1 0x1000007a
+ UID2 0x100039ce
+ UID3 0x12345678
+ Secure ID 0x12345678
+ Vendor ID 0x00000000
+ Capabilities 0x0 (NONE)
+ somelibrary.dll:
+ UID1 0x10000079
+ UID2 0x00000000
+ UID3 0x00000000
+ Secure ID 0x00000000
+ Vendor ID 0x00000000
+ Capabilities 0xff7be (ALL-TCB-DRM-AllFiles)
+
+This will display information about "myprogram.exe" and
+"somelibrary.dll".
+
+
+The "mergesis" command
+----------------------
+
+SYNOPSIS
+ $ ensymble.py mergesis
+ [--cert=mycert.cer] [--privkey=mykey.key] [--passphrase=12345]
+ [--encoding=terminal,filesystem] [--verbose]
+ <infile> [mergefile]... <outfile>
+
+
+DESCRIPTION
+
+The "mergesis" command takes a set of SIS files and inserts them as
+unconditional embedded SIS files in the first one. The resulting SIS
+package is then signed with the certificate provided. None of the
+certificates of the first SIS file are preserved.
+
+Note: The "mergesis" command will only work with SIS files that do not
+already contain other embedded SIS files.
+
+
+PARAMETERS
+
+ infile
+
+Path of the base SIS file.
+
+ mergefile
+
+Zero or more SIS files to embed in the base sis file.
+
+ outfile
+
+Path of the resulting SIS file. If a directory name is given, base SIS
+file name is used as the output file name.
+
+ --cert=mycert.cer
+ -a mycert.cer
+
+Certificate to use for signing in PEM (text) format. If no certificate
+and its private key are given, Ensymble uses a default self-signed
+certificate (see option "--cert" for command "py2sis" above).
+
+ --privkey=mykey.key
+ -k mykey.key
+
+Private key of the certificate in PEM (text) format. If option "--cert"
+(above) is given, this option is required as well.
+
+ --passphrase=12345
+ -p 12345
+
+Pass phrase of the private key.
+
+Note: Using command line options to give the pass phrase is insecure.
+Any user of the computer will be able to see command lines of started
+programs and thus will see the pass phrase in plain view. Instead,
+standard input should be used (see examples below).
+
+If no pass phrase is given on the command line or standard input, it
+will be asked interactively.
+
+
+EXAMPLES
+
+Note: The command lines below may be wrapped over multiple lines due to
+layout constraints. In reality, each of them should be contained in one
+physical command line.
+
+ $ ensymble.py mergesis
+ --cert=mycert.cer --key=mykey.key --passphrase=12345
+ myapp_v1_0_0.sis PythonForS60_1_3_17_3rdEd_selfsigned.SIS
+ myapp_standalone_v1_0_0.sis
+
+A Python for S60 script "myapp_v1_0_0.sis" will be merged with Python
+runtime SIS "PythonForS60_1_3_17_3rdEd_selfsigned.SIS". A new SIS file
+"myscript_standalone_v1_0_0.sis" will be created and signed with
+"mycert.cer" using private key "mykey.key".
+
+ $ echo "12345" | ensymble.py mergesis
+ --cert=mycert.cer --key=mykey.key
+ basefile.sis addon1.sis addon2.sis
+
+Pass phrase can be given in Ensymble standard input, so that it will not
+be visible to all users of the computer (see option "--passphrase"
+above).
+
+
+The "py2sis" command
+--------------------
+
+SYNOPSIS
+
+ $ ensymble.py py2sis
+ [--uid=0x01234567] [--appname=AppName] [--version=1.0.0]
+ [--lang=EN,...] [--icon=icon.svg] [--shortcaption="App. Name",...]
+ [--caption="Application Name",...] [--drive=C]
+ [--textfile=mytext_%C.txt] [--cert=mycert.cer] [--privkey=mykey.key]
+ [--passphrase=12345] [--caps=Cap1+Cap2+...]
+ [--vendor="Vendor Name",...] [--autostart]
+ [--encoding=terminal,filesystem] [--verbose]
+ <src> [sisfile]
+
+
+DESCRIPTION
+
+The "py2sis" command is used to pack a Python for S60 application script
+and its auxiliary files (if any) into a Symbian installation package
+(SIS).
+
+
+PARAMETERS
+
+ src
+
+The source script or directory name. When a directory name is given, the
+directory structure is preserved under an application specific private
+directory ("\private\<uid>\") on the phone. A file called "default.py"
+is required to exist on the root of the directory given. This will be
+the main file that starts the application. (See option "--extrasdir"
+below for more options for file placement.)
+
+When a regular file name is given, it will be located under the
+application specific private directory, with the name "default.py".
+
+ sisfile
+
+Path of the SIS file to create. If a directory name is given, output
+file name is derived from input file name and application version (see
+option "--version" below). This is also the case when no SIS file name
+is given.
+
+ --appname=AppName
+ -n AppName
+
+Name of the application. If no application name is given, it will be
+derived from the input file name.
+
+This name is used as the base for all generated file names (EXE, icon,
+resources) on the phone. It will also be used as the default caption if
+none are given, and a temporary UID (see option "--uid" below) will be
+generated from application name if not given explicitly.
+
+ --uid=0x01234567
+ -u 0x01234567
+
+Symbian UID for the application. If the UID option is not given, the
+main Python file ("default.py", see parameter "src" above) will be
+scanned for a special string. If no UID can be found, a temporary UID is
+generated from the application name (see option "--appname" and command
+"genuid" above).
+
+The special UID string can appear anywhere in the main Python file,
+including comments and as part of string literals. It is of the form
+
+ SYMBIAN_UID = UID
+
+, where whitespace around the equals sign is optional. UID is in the
+same format as with the command line parameter (see option "--uid"
+above).
+
+Note: Use a real UID for all applications to be distributed. The
+auto-generated test-range UID is only meant for development and testing,
+not for real applications. UIDs can be ordered from Symbian Signed [12].
+If you have already ordered UIDs for 1st or 2nd Edition phones, to use
+these UIDs in 3rd Edition phones the first hex digit (a "1") needs to be
+changed to an "f".
+
+Also note: When changing the application name (or source file /
+directory name in case no application name is explicitly given), the
+temporary UID changes and the SIS package will be considered a new
+application on the phone, unless an UID is explicitly specified.
+
+ --version=1.0.0
+ -r 1.0.0
+
+Application version: X.Y.Z or X,Y,Z (major, minor, build). There may be
+a "v" or "V" in front of the major number. Minor and build numbers are
+optional.
+
+If the version option is not given, the main Python file ("default.py",
+see parameter "src" above) will be scanned for a special string. If no
+version can be found, it defaults to 1.0.0.
+
+The special version string can appear anywhere in the main Python file,
+including comments and as part of string literals. It is of the form
+
+ SIS_VERSION = "1.0.0"
+
+, where whitespace around the equals sign is optional. Version is in the
+same format as with the command line parameter (see option "--version"
+above), except that it may optionally be enclosed in single or double
+quotes.
+
+ --lang=EN,...
+ -l EN,...
+
+Comma separated list of two-character language codes. These are the
+languages that the SIS file claims to support, English by default.
+Application must then somehow determine which language was selected
+during install. Symbian installation tools reference [13] lists the
+available language codes.
+
+ --icon=icon.svg
+ -i icon.svg
+
+Icon file in SVG-Tiny format. If no icon is given, the Python logo is
+used as the icon. The Python logo is a trademark of the Python Software
+Foundation.
+
+Ensymble does not support the old style MBM bitmap icons.
+
+ --shortcaption="App. Name",...
+ -s "App. Name",...
+
+ --caption="Application Name",...
+ -c "Application Name",...
+
+Comma separated list of short and long captions in all selected
+languages, i.e. there must be as many comma separated captions as there
+are languages listed with the "--lang" option. If no captions are given,
+application name is used (see option "--appname" above). If only the
+short captions are given, long captions will use those instead.
+
+Captions are visible names used in various places on the phone display.
+Short caption is displayed under the application icon when using the
+grid layout. Long caption is used on top of the screen when the
+application is launched and beside the icon in list layout. Long caption
+is also used as the package name, which is displayed during application
+installation.
+
+ --drive=C
+ -f C
+
+Installation drive "C" or "E" or "any", to select where the SIS is to be
+installed. Default is "any", which causes the phone to ask the user
+where to install the package.
+
+ --extrasdir=root
+ -x root
+
+Name of "extras" directory under the application source directory. The
+extras directory contains a directory tree which is placed under the
+root of the installation drive, instead of in the application private
+directory. If no extras directory name is given, this feature is
+disabled.
+
+Option "--extrasdir" is similar to the "simplesis" command (see below).
+It allows placing files under "\sys\bin" and "\resource", for example.
+
+ --textfile=mytext_%C.txt
+ -t mytext_%C.txt
+
+Text file (or pattern, see below) to display during install. If none is
+given, no extra text will be displayed during install.
+
+Files to display are in UTF-8 encoding, without Byte-Order Marker (BOM).
+The file name may contain formatting characters that are substituted for
+each selected language (see option "--lang" above). If no formatting
+characters are present, the same text will be used for all languages.
+
+ %% - literal %
+ %n - language number (01 - 99)
+ %c - two-character language code in lowercase letters
+ %C - two-character language code in capital letters
+ %l - language name in English, using only lowercase letters
+ %l - language name in English, using mixed case letters
+
+For example, if there are files named "mytext_EN.txt", "mytext_GE.txt"
+and "mytext_SP.txt", a pattern of "mytext_%C.txt" will be able to use
+them.
+
+ --cert=mycert.cer
+ -a mycert.cer
+
+Certificate to use for signing in PEM (text) format.
+
+SIS files for Symbian OS v9 and later are required to be digitally
+signed. Unsigned packages will not install on the phone. A
+self-generated ("self-signed" in crypto parlance) certificate will do,
+but only a restricted subset of features ("capabilities", see option
+"--caps" below) are available for self-signed applications.
+
+If no certificate and its private key are given, Ensymble uses a default
+self-signed certificate. Software authors are encouraged to create their
+own unique certificates for SIS packages that are to be distributed.
+
+ --privkey=mykey.key
+ -k mykey.key
+
+Private key of the certificate in PEM (text) format. If option "--cert"
+(above) is given, this option is required as well.
+
+ --passphrase=12345
+ -p 12345
+
+Pass phrase of the private key.
+
+Note: Using command line options to give the pass phrase is insecure.
+Any user of the computer will be able to see command lines of started
+programs and thus will see the pass phrase in plain view. Instead,
+standard input should be used (see examples below).
+
+If no pass phrase is given on the command line or standard input, it
+will be asked interactively.
+
+ --caps=Cap1+Cap2+...
+ -b Cap1+Cap2+...
+
+or
+
+ --caps=0x12345
+ -b 0x12345
+
+Capability names separated by "+" or a numeric capability bitmask. If no
+capability option is given, the capabilities : LocalServices, NetworkServices,
+ReadUserData, WriteUserData and UserEnvironment are granted by default.
+Symbian Signed [12] has an FAQ which explains all the available capabilities.
+
+ --vendor=Name,...
+ -d Name,...
+
+Comma separated list of vendor names in all selected languages, i.e.
+there must be as many comma separated vendor names as there are
+languages listed with the "--lang" option. Alternatively, if only one
+vendor name is given, it will be used for all languages. If no vendor
+names are given then "Ensymble" will be used.
+
+Vendor name is visible during installation and on the Application
+manager, except when using self-signed certificates (see option "--cert"
+above).
+
+ --autostart
+ -g
+
+Flag to control automatic startup of the application. On S60 3rd Edition
+phones, an application can register itself to be automatically started
+when the phone is turned on.
+
+Note: Self-signed applications and applications with UID in the
+unprotected range cannot register to be automatically started (see
+options "--uid" and "--cert" above).
+
+ --runinstall
+ -R
+
+Run the application after installation. After copying all files to the
+phone, the application is automatically started.
+
+Note: Phones will ignore this flag in SIS files using self-signed
+certificates (see option "--cert" above).
+
+ --heapsize=min,max
+ -H min,max
+
+Heap size limits for the application. Defaults of 100 kilobytes and four
+megabytes are used if no heap size option is given. If only one value is
+given, it is used as both the heap minimum and heap maximum value.
+
+Values may have suffix "k" or "M" (case insensitive) to denote kilobytes
+(1024 bytes) and megabytes (1048576 bytes), respectively.
+
+The heap minimum value determines if a program is allowed to start. If
+less than the set amount of memory is available, program start-up fails.
+The heap maximum value limits the memory a program can allocate. Memory
+allocations beyond the set limit will fail. The default of one megabyte
+is usually enough, but processing large datasets such as images from an
+integrated camera might require setting the heap maximum value higher.
+
+ --profile=console
+ -P console
+
+The profile selected determines the environment in which the packaged Python
+script is run. The two possible values are 's60ui' and 'console', the former
+being the default value. The Python core remains the same in both the profiles.
+
+If the console profile is selected then the application needs OpenC's STDIO
+console already installed. All UI related modules like appuifw, graphics will
+not work in this mode.
+
+ --mode=pycore
+ -m pycore
+
+The mode option takes two values - 'pycore' or 'pys60'. Setting the mode as
+'pycore' will result in the Python core modules taking priority over the PyS60
+extension modules when module names conflict. When 'pycore' mode is selected
+the conflicting PyS60 extension modules will not be available with the same
+name. However you can import the conflicting modules using their new names as
+mentioned in the note below. In 'pys60' mode the conflicting core modules will
+not be available at all. The default value of this option is 'pycore'.
+Note: calendar and socket are the only two conflicting modules and they can be
+imported using their new names e32calendar and btsocket in 'pycore' mode.
+
+ --extra-modules=mod1,mod2
+ -o mod1,mod2
+
+This option can be used to specify any additional dependencies that should be
+packaged with the application sis. The dependencies will be searched in the
+custom search paths specified in module_search_path.cfg present under the
+dev-modules directory and then in standard-module and dev-modules directories.
+
+ --ignore-missing-deps
+
+If specified the packaging continues by displaying any missing dependencies as
+warnings. Else packaging is aborted after displaying the missing dependencies
+as errors.
+
+ --platform-uid=0x101f7961,...
+
+This option can be used to specify the S60 platform UID of the devices on which
+the application is supported. The default value of this option are
+0x101f7961 and 0x1028315F (referring to S603rdEditon and S605thEditon UID
+respectively)
+
+ --sourcecode
+
+By default the application is packaged as bytecode. In this mode, the module
+import is faster but the source code is not visible in tracebacks. With the
+--sourcecode option, the application is packaged as source code and as a result
+tracebacks contain the code.
+
+EXAMPLES
+
+Note: The command lines below may be wrapped over multiple lines due to
+layout constraints. In reality, each of them should be contained in one
+physical command line.
+
+ $ ensymble.py py2sis myprog.py
+
+This generates a SIS file called "myprog_v1_0_0.sis" in current working
+directory. This SIS file is ready to be uploaded to a S60 3rd Edition
+phone. Package version defaults to 1.0.0, a test-range UID is
+auto-generated for the package and a default self-signed certificate is
+used to digitally sign the SIS file. A default icon (the Python logo) is
+used for application icon.
+
+ $ echo "12345" | ensymble.py py2sis
+ --cert mycert.cer --privkey mykey.key
+ myprog.py
+
+Pass phrase can be given in Ensymble standard input, so that it will not
+be visible to all users of the computer (see option "--passphrase"
+above).
+
+
+The "signsis" command
+---------------------
+
+SYNOPSIS
+
+ $ ensymble.py signsis
+ [--unsign]
+ [--cert=mycert.cer] [--privkey=mykey.key] [--passphrase=12345]
+ [--execaps=Cap1+Cap2+...] [--dllcaps=Cap1+Cap2+...]
+ [--encoding=terminal,filesystem] [--verbose]
+ <infile> [outfile]
+
+
+DESCRIPTION
+
+The "signsis" command (re-)signs a SIS package with the certificate
+provided, stripping out any existing certificates, if any. Capabilities
+of all EXE and DLL files contained in the SIS package can optionally be
+modified.
+
+Extension module authors may want to distribute a version of their SIS
+packages with only limited capabilities. Users can then adjust the
+capabilities according to their own needs and sign the SIS package with
+their own certificates.
+
+Note: SIS packages may embed other SIS packages. The "signsis" command
+will only alter the main SIS, leaving all embedded SIS packages intact.
+
+
+PARAMETERS
+
+ infile
+
+Path of the original SIS file.
+
+ outfile
+
+Path of the modified SIS file. If a directory name is given, input file
+name is used as the output file name.
+
+Note: If no output file name is given, original SIS file is overwritten!
+
+ --unsign
+ -u
+
+Instead of signing a SIS file, remove all signatures from it. This is
+useful when submitting the SIS file to an external signing authority,
+otherwise the Ensymble default certificate may remain in the resulting
+signed SIS file.
+
+ --cert=mycert.cer
+ -a mycert.cer
+
+Certificate to use for signing in PEM (text) format. If no certificate
+and its private key are given, Ensymble uses a default self-signed
+certificate (see option "--cert" for command "py2sis" above).
+
+ --privkey=mykey.key
+ -k mykey.key
+
+Private key of the certificate in PEM (text) format. If option "--cert"
+(above) is given, this option is required as well.
+
+ --passphrase=12345
+ -p 12345
+
+Pass phrase of the private key.
+
+Note: Using command line options to give the pass phrase is insecure.
+Any user of the computer will be able to see command lines of started
+programs and thus will see the pass phrase in plain view. Instead,
+standard input should be used (see examples below).
+
+If no pass phrase is given on the command line or standard input, it
+will be asked interactively.
+
+ --execaps=Cap1+Cap2+...
+ -b Cap1+Cap2+...
+
+or
+
+ --execaps=0x12345
+ -b 0x12345
+
+Capability names separated by "+" or a numeric capability bitmask. EXEs
+inside the SIS file will be modified according to these capabilities. If
+no capability option is given, no EXEs will be modified. Symbian Signed
+[12] has an FAQ which explains all the available capabilities.
+
+ --dllcaps=Cap1+Cap2+...
+ -d Cap1+Cap2+...
+
+or
+
+ --dllcaps=0x12345
+ -d 0x12345
+
+Capability names separated by "+" or a numeric capability bitmask. DLLs
+inside the SIS file will be modified according to these capabilities. If
+no capability option is given, no DLLs will be modified.
+
+
+EXAMPLES
+
+Note: The command lines below may be wrapped over multiple lines due to
+layout constraints. In reality, each of them should be contained in one
+physical command line, with no spaces around the "+" characters.
+
+ $ ensymble.py signsis
+ --dllcaps=LocalServices+Location+NetworkServices+PowerMgmt+ProtServ+
+ ReadUserData+SurroundingsDD+SWEvent+UserEnvironment+WriteUserData+
+ ReadDeviceData+TrustedUI+WriteDeviceData
+ --cert=mycert.cer --key=mykey.key --passphrase=12345
+ coolextension_nocert.sis coolextension_mycert.sis
+
+Extension module "coolextension_nocert.sis" will be modified with the
+capabilities listed. A new SIS file "coolextension_mycert.sis" will be
+created and signed with "mycert.cer" using private key "mykey.key".
+
+ $ echo "12345" | ensymble.py signsis
+ --dllcaps=0xff1b4 --cert=mycert.cer --key=mykey.key
+ coolextension_nocert.sis coolextension_mycert.sis
+
+Pass phrase can be given in Ensymble standard input, so that it will not
+be visible to all users of the computer (see option "--passphrase"
+above).
+
+
+The "simplesis" command
+-----------------------
+
+SYNOPSIS
+
+ $ ensymble.py simplesis
+ [--uid=0x01234567] [--version=1.0.0] [--lang=EN,...]
+ [--caption="Package Name",...] [--drive=C] [--textfile=mytext_%C.txt]
+ [--cert=mycert.cer] [--privkey=mykey.key] [--passphrase=12345]
+ [--vendor="Vendor Name",...] [--encoding=terminal,filesystem]
+ [--verbose]
+ <srcdir> [sisfile]
+
+
+DESCRIPTION
+
+The "simplesis" command is used to create a Symbian installation package
+(SIS) from an existing directory structure. Conditional inclusion of
+files, dependencies or other fancy features of SIS files are not
+supported.
+
+
+PARAMETERS
+
+ srcdir
+
+The source directory name. The directory structure is preserved under
+the installation drive, i.e files and directories under "srcdir" will be
+located on the root of the installation drive.
+
+ sisfile
+
+Path of the SIS file to create. If a directory name is given, output
+file name is derived from source directory name and package version (see
+option "--version" below). This is also the case when no SIS file name
+is given.
+
+ --uid=0x01234567
+ -u 0x01234567
+
+Symbian UID for the package. If the UID option is not given, the source
+directory name will be used to generate a temporary UID (see command
+"genuid" above).
+
+Note: Use a real UID for all packages to be distributed. The
+auto-generated test-range UID is only meant for development and testing,
+not for real packages. UIDs can be ordered from Symbian Signed [12]. If
+you have already ordered UIDs for 1st or 2nd Edition phones, to use
+these UIDs in 3rd Edition phones the first hex digit (a "1") needs to be
+changed to an "f".
+
+Also note: When changing the source directory name, the temporary UID
+changes and the SIS package will be considered a new application on the
+phone.
+
+ --version=1.0.0
+ -r 1.0.0
+
+Package version: X.Y.Z or X,Y,Z (major, minor, build). There may be a
+"v" or "V" in front of the major number. Minor and build numbers are
+optional.
+
+If the version option is not given it defaults to 1.0.0.
+
+ --lang=EN,...
+ -l EN,...
+
+Comma separated list of two-character language codes. These are the
+languages that the SIS file claims to support, English by default.
+Symbian installation tools reference [13] lists the available language
+codes.
+
+ --caption="Application Name",...
+ -c "Application Name",...
+
+Comma separated list of package captions in all selected languages, i.e.
+there must be as many comma separated captions as there are languages
+listed with the "--lang" option. If no captions are given, source
+directory name is used (see parameter "srcdir" above).
+
+Package caption is displayed during application installation.
+
+ --drive=C
+ -f C
+
+Installation drive "C" or "E" or "any", to select where the SIS is to be
+installed. Default is "any", which causes the phone to ask the user
+where to install the package.
+
+ --textfile=mytext_%C.txt
+ -t mytext_%C.txt
+
+Text file (or pattern, see below) to display during install. If none is
+given, no extra text will be displayed during install.
+
+Files to display are in UTF-8 encoding, without Byte-Order Marker (BOM).
+The file name may contain formatting characters that are substituted for
+each selected language (see option "--lang" above). If no formatting
+characters are present, the same text will be used for all languages.
+
+ %% - literal %
+ %n - language number (01 - 99)
+ %c - two-character language code in lowercase letters
+ %C - two-character language code in capital letters
+ %l - language name in English, using only lowercase letters
+ %l - language name in English, using mixed case letters
+
+For example, if there are files named "mytext_EN.txt", "mytext_GE.txt"
+and "mytext_SP.txt", a pattern of "mytext_%C.txt" will be able to use
+them.
+
+ --cert=mycert.cer
+ -a mycert.cer
+
+Certificate to use for signing in PEM (text) format.
+
+SIS files for Symbian OS v9 and later are required to be digitally
+signed. Unsigned packages will not install on the phone. A
+self-generated ("self-signed" in crypto parlance) certificate will do,
+but only a restricted subset of features ("capabilities", see option
+"--caps" below) are available for self-signed applications.
+
+If no certificate and its private key are given, Ensymble uses a default
+self-signed certificate. Software authors are encouraged to create their
+own unique certificates for SIS packages that are to be distributed.
+
+ --privkey=mykey.key
+ -k mykey.key
+
+Private key of the certificate in PEM (text) format. If option "--cert"
+(above) is given, this option is required as well.
+
+ --passphrase=12345
+ -p 12345
+
+Pass phrase of the private key.
+
+Note: Using command line options to give the pass phrase is insecure.
+Any user of the computer will be able to see command lines of started
+programs and thus will see the pass phrase in plain view. Instead,
+standard input should be used (see examples below).
+
+If no pass phrase is given on the command line or standard input, it
+will be asked interactively.
+
+
+EXAMPLES
+
+Note: The command lines below may be wrapped over multiple lines due to
+layout constraints. In reality, each of them should be contained in one
+physical command line.
+
+ $ ls -R mymodule
+ mymodule:
+ resource/ sys/
+
+ mymodule/resource:
+ apps/ mymodule.py
+
+ mymodule/resource/apps:
+ mymodule.rsc
+
+ mymodule/sys:
+ bin/
+
+ mymodule/sys/bin:
+ _mymodule.pyd
+ $ ensymble.py simplesis mymodule
+
+This generates a SIS file called "mymodule_v1_0_0.sis" in current
+working directory. Contents of the SIS file are directly taken from
+directory "mymodule" and the relative path of each file is preserved.
+The SIS file is ready to be uploaded to a S60 3rd Edition phone. Package
+version defaults to 1.0.0, a test UID is auto-generated for the package
+and a default self-signed certificate is used to digitally sign the SIS
+file.
+
+ $ echo "12345" | ensymble.py py2sis
+ --cert mycert.cer --privkey mykey.key
+ mymodule
+
+Pass phrase can be given in Ensymble standard input, so that it will not
+be visible to all users of the computer (see option "--passphrase"
+above).
+
+
+The "version" command
+---------------------
+
+SYNOPSIS
+
+ $ ensymble.py version
+
+
+DESCRIPTION
+
+The "version" command prints Ensymble version.
+
+
+PARAMETERS
+
+No parameters
+
+
+EXAMPLES
+
+ $ ensymble.py version
+ Ensymble v0.28 2009-01-30
+
+The version string is printed.
+
+
+PROJECT HISTORY
+===============
+
+2009-01-30
+Released Ensymble version v0.28 2009-01-30.
+Added genuid command for generating test-range UIDs.
+Added --unsign option to the signsis command.
+Corrected a bug where DLLs (PYDs) would fail with the py2sis --extrasdir option.
+Corrected an encoding bug in simplesis automatic UID generation.
+Corrected a possible Unicode exception in py2sis automatic UID generation.
+Added a warning about manually specifying a different test-range UID.
+
+2008-10-17
+Converted everything from ISO-8859-1 to UTF-8 encoding.
+
+2008-06-30
+Released Ensymble version v0.27 2008-06-30.
+Implemented --heapsize option for the py2sis and altere32 commands.
+Implemented --extrasdir option for the py2sis command for more flexibility.
+Added support for PKCS#8 format private keys which Symbian sends to people.
+
+2008-01-27
+Released Ensymble version v0.26 2008-01-27.
+Incorporated a --runinstall option for the py2sis command, by Jari Kirma.
+Commands mergesis and signsis no longer choke on extra bytes in input SIS files.
+
+2007-12-15
+Released Ensymble version v0.25 2007-12-15.
+Added --drive option to py2sis and simplesis commands, for installation drive.
+Added --vendor option for the simplesis command, as well.
+The OpenSSL command line tool can reside in the same directory as Ensymble now.
+Prevent leaving zero-byte output files behind when no OpenSSL tool is found.
+Made it possible to use numeric capability bitmasks.
+Rewrote installation instructions to better take Windows users into account.
+
+2007-10-18
+Released Ensymble version v0.24 2007-10-18.
+Added --autostart option to the py2sis command, like in the official py2sis.
+Added --vendor option to the py2sis command, useful when signing packages.
+Added infoe32 command contributed by Martin Storsjö.
+
+2007-07-16
+Released Ensymble version v0.23 2007-07-16.
+Python for S60 changed its UID due to Nokia finally signing it, adapted.
+Clarified README in using embedded version and UID strings with py2sis command.
+
+2007-02-08
+Released Ensymble version 2007-02-08 v0.22.
+Added simplesis command for creating a SIS package out of a directory structure.
+Added maximum file size sanity check for py2sis command.
+
+2007-02-01
+Released Ensymble version 2007-02-01 v0.21.
+Added mergesis command for combining several SIS files into one.
+
+2007-01-01
+Released Ensymble version 2007-01-01 v0.20.
+Revamped documentation. Now every command and option is explained.
+Added signsis command for (re-)signing SIS files.
+Added altere32 command for altering pre-compiled Symbian EXEs and DLLs.
+Implemented text file option for py2sis command ("Freeware Route to Market").
+Made py2sis language option more robust against mistyped language codes.
+Made it possible modify signatures of an existing SISController object.
+Generated capability fields are smaller now (4 bytes instead of 8 bytes).
+Moved default certificate to its own module: defaultcert.py.
+Made exception dumps more verbose when the --debug option is present.
+Miscellaneous clean-ups.
+
+2006-11-18
+Released Ensymble version 2006-11-18 v0.15.
+Rewrote certificate to binary conversion. Fixes problems on Windows.
+Removed line feed after pass phrase for OpenSSL. It will not work on Windows.
+
+2006-11-12
+Released Ensymble version 2006-11-12 v0.14.
+Modified the generated SIS a bit, to be compatible with native signsis.exe.
+Test UIDs use lower case appname now, due to Symbian OS being case insensitive.
+Added support for signature chains. Symbian Signed uses those.
+
+2006-10-06
+Fourth public preview release: 2006-10-06 v0.13
+OpenSSL invocation uses absolute paths now. Windows XP Pro should work now.
+
+2006-10-05
+Third public preview release: 2006-10-05 v0.12
+Implemented automatic test UID generation for the py2sis command.
+Added warning message for UIDs in the protected range.
+Changed OpenSSL path detection to be carried out only on demand.
+Added debug messages for troubleshooting OpenSSL-related problems.
+Miscellaneous clean-ups
+
+2006-09-26
+Second public preview release: 2006-09-26 v0.11
+Made the default certificate a bit more anonymous.
+Added Windows (NT/2000/XP) support.
+
+2006-09-25
+Tested Ensymble on Python v2.2.
+Added COPYING file to the source package.
+Minor edits to README and ensymble.html
+
+2006-09-24
+First public preview release: 2006-09-24 v0.10
+
+
+LICENSE
+=======
+
+Ensymble developer utilities for Symbian OS(TM)
+Copyright 2006, 2007 Jussi Ylänen
+Released under the GNU General Public Licence (see file COPYING)
+
+
+CONTACT
+=======
+
+Official web page for Ensymble can be found at
+
+ http://www.nbl.fi/jussi.ylanen/ensymble.html
+
+
+Please send comments, suggestions, corrections and enhancements to:
+
+ jussi.ylanen@iki.fi
+
+
+ACKNOWLEDGEMENTS
+================
+
+Symbian and all Symbian-based marks and logos are trade marks of Symbian
+Limited.
+
+"Python" and the Python logo are trademarks or registered trademarks of
+the Python Software Foundation.
+
+Nokia, S60 and logo, Series 60 are trademarks or registered trademarks
+of Nokia Corporation.
+
+Windows is a registered trademark of Microsoft Corporation in the United
+States and other countries.
+
+
+REFERENCES
+==========
+
+[1]
+Symbian OS
+http://www.symbian.com
+
+[2]
+Python for S60
+http://www.forum.nokia.com/python
+
+[3]
+Nokia
+http://www.nokia.com
+
+[4]
+A list of Nokia S60 phone editions:
+http://www.forum.nokia.com/devices/matrix_s60_1.html
+
+[5]
+The Python programming language
+http://www.python.org
+
+[6]
+S60 Platform
+http://www.s60.com
+
+[7]
+Python-to-SIS, the next generation by Jussi Ylänen
+http://www.nbl.fi/jussi.ylanen/py2sisng.html
+
+[8]
+OpenSSL
+http://www.openssl.org
+
+[9]
+Stunnel OpenSSL binaries
+http://www.stunnel.org/download/binaries.html
+
+[10]
+squeeze utility by Fredrik Lundh
+http://effbot.org/zone/squeeze.htm
+
+[11]
+Python standard encodings
+http://docs.python.org/lib/standard-encodings.html
+
+[12]
+Symbian Signed
+http://www.symbiansigned.com
+
+[13]
+Symbian installation tools reference
+http://www.symbian.com/developer/techlib/v70sdocs/doc_source/ToolsAndUtilities/Installing-ref/PackageFileFormatReference.guide.html