diff -r 000000000000 -r ca70ae20a155 src/tools/py2sis/ensymble/README --- /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] + + +or + + $ ensymble.py altere32 + [--uid=0x01234567] [--secureid=0x01234567] [--vendorid=0x01234567] + [--caps=Cap1+Cap2+...] [--encoding=terminal,filesystem] [--verbose] + --inplace ... + + +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] + ... + + +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] + ... + + +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] + [mergefile]... + + +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] + [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\\") 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] + [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] + [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