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]