The Ensymble developer utilities for Symbian OS
              Copyright 2006, 2007, 2008, 2009 Jussi Ylänen

                         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 application will not have any special
capabilities. 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 4 kilobytes and one
megabyte 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.


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-range 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:

        [email protected]


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