1              The Ensymble developer utilities for Symbian OS

     2               Copyright 2006, 2007, 2008, 2009 Jussi Ylänen

     3            Portions Copyright (c) 2008 - 2009 Nokia Corporation

     4 

     5                          Last updated 2009-01-30

     6 

     7 

     8 ABOUT

     9 =====

    10 

    11 This is the Ensymble developer utilities for Symbian OS(TM), a

    12 collection of Python® modules and command line programs for Symbian OS

    13 [1] software development.

    14 

    15 Current focus of Ensymble development is to provide useful tools for

    16 making "Python for S60" [2] (also called PyS60) programs. Supported

    17 functions include generation of SIS (installation) packages, merging

    18 several SIS packages into one, (re-)signing existing SIS packages and

    19 modifying extension DLL headers. Support for other Symbian OS software

    20 development tasks will follow.

    21 

    22 A long term goal of Ensymble is to provide a cross-platform, open-source

    23 way to do Symbian OS software development, supporting Symbian OS

    24 versions 9.1 and later. The original tools by Symbian are closed source

    25 and only available for the Windows® operating system.

    26 

    27 Symbian OS is the operating system used by Nokia [3] in some of its

    28 mobile phones [4]. Other manufacturers have also licensed Symbian OS.

    29 Python for S60 is a port of the popular Python programming language [5]

    30 to a Nokia phone platform called S60® [6]. Before November 2005, S60 was

    31 called Series 60.

    32 

    33 

    34 VERSION COMPATIBILITY

    35 =====================

    36 

    37 Ensymble targets Symbian OS v9.1 and later. For Nokia phones, this means

    38 S60 3rd Edition. 1st and 2nd Edition phones are not directly supported

    39 by Ensymble. A program called py2sisng [7] supports 1st and 2nd Edition

    40 phones and can be used for a subset of tasks that Ensymble performs.

    41 

    42 The py2sis command of the Ensymble command line tool produces

    43 installation packages (SIS) for Python for S60 version 1.4.0 and later.

    44 Version 1.4.0 of Python for S60 is the first officially signed release

    45 from Nokia. Although packages generated with Ensymble also work with

    46 PyS60 from v1.3.8 upto v1.3.23, a harmless warning is generated during

    47 installation for a missing Python for S60 component.

    48 

    49 Ensymble is written in Python. Python v2.2 or newer is required, as

    50 older versions lack necessary language features. Ensymble has been

    51 tested on the following systems:

    52 

    53  * Debian GNU/Linux Sid (i386) with Python v2.3.5, v2.4.5 and v2.5.2

    54  * Red Hat Linux release 9 (i386) with Python v2.2.2

    55  * Red Hat Enterprise Linux AS release 3 (i386) with Python v2.2.3

    56  * Red Hat Enterprise Linux AS release 4 (i386) with Python v2.3.4

    57  * Apple OS X Tiger (G4) with Python v2.3.5

    58  * Apple OS X Leopard (i386) with Python v2.5

    59  * Microsoft Windows XP, SP2 with Python v2.5

    60 

    61 Note: Python for S60 versions 1.3.20 and older require that SIS files

    62 generated by Ensymble are installed into main phone memory instead of

    63 memory card. This bug has been corrected in version 1.3.21 of PyS60.

    64 

    65 

    66 INSTALLATION

    67 ============

    68 

    69 Care has been taken to ensure that minimum amount of extra software is

    70 needed to run Ensymble. A working installation of Python is required

    71 (see VERSION COMPATIBILITY above). In addition, the OpenSSL command line

    72 tool [8] is required for installation package (SIS) generation, merging

    73 and (re-)signing. Any recent version will do, and can usually be found

    74 pre-installed. For Windows, the Stunnel OpenSSL binaries [9] are

    75 recommended, but any other binaries will do as well.

    76 

    77 The Ensymble command line tool is normally installed as a single file

    78 "ensymble.py". This file contains everything except the OpenSSL command

    79 line tool and is created using Fredrik Lundh's nifty squeeze utility

    80 [10]. Pre-squeezed files for various Python versions may be downloaded

    81 from the Ensymble home page. To find out which version to download, type

    82 "python -V" on the command line:

    83 

    84     $ python -V

    85     Python 2.4.4

    86 

    87 or

    88 

    89     C:\> python -V

    90     Python 2.4.4

    91 

    92 A pre-squeezed version for Python 2.4 would be the correct one in this

    93 case.

    94 

    95 Users on Unix-like systems (Linux, *BSD, Apple OS X) can download the

    96 correct pre-squeezed version and put in in the "bin" directory under the

    97 user's home directory (if such a thing exists), and possibly rename the

    98 file to "ensymble.py" as well.

    99 

   100 Windows users need to download "openssl.zip" (NOT "stunnel-n.nn.exe" or

   101 "stunnel-n.nn-installer.exe") [9] and unpack it somewhere, for example

   102 "C:\Ensymble", and then put the correct pre-squeezed version of Ensymble

   103 there as well, renamed to "ensymble.py":

   104 

   105     C:\Ensymble\      [directory]

   106         ensymble.py   [76046 bytes]

   107         openssl.exe   [1153024 bytes]

   108         libssl32.dll  [632226 bytes]

   109         libeay32.dll  [1578787 bytes]

   110 

   111 To allow using the Ensymble command line tool without explicitly giving

   112 a full command path each time, it is advisable to add the installation

   113 directory ("C:\Ensymble" in the example above) in the Path environment

   114 variable in Windows' environment variables dialog (My Computer ->

   115 Properties -> Advanced -> Environment Variables -> System Variables ->

   116 Path). The Command Prompt window must be restarted after the change.

   117 

   118 Installation is also possible from the original source package. For

   119 Unix-like systems, there is a simple installation script which squeezes

   120 all the required files together and copies the resulting package to a

   121 given directory (which must exist already):

   122 

   123     $ ./install.sh ~/bin

   124 

   125 

   126 USAGE

   127 =====

   128 

   129 DESCRIPTION

   130 

   131 The Ensymble command line tool provides access to most Ensymble

   132 functionality:

   133 

   134     $ ensymble.py command options...

   135 

   136 , where "command" is the command to be executed and "options" are the

   137 command specific options. Running ensymble.py without arguments will

   138 list all the available commands.

   139 

   140 The following commands are currently supported by Ensymble:

   141 

   142     altere32   Alter the IDs and capabilities of e32image files (EXEs, DLLs)

   143     genuid     Generate a new test-range UID from a name

   144     infoe32    Show the IDs and capabilities of e32image files (EXEs, DLLs)

   145     mergesis   Merge several SIS packages into one

   146     py2sis     Create a SIS package for a "Python for S60" application

   147     signsis    Sign a SIS package

   148     simplesis  Create a SIS package from a directory structure

   149     version    Print Ensymble version

   150 

   151 Each command is documented in detail below.

   152 

   153 Note about security: When using SIS certificates, the private key of the

   154 certificate is saved unencrypted to a temporary file and could be

   155 recovered by others. This is due to compatibility with old versions of

   156 OpenSSL. In the future, Ensymble may require a more recent version of

   157 OpenSSL.

   158 

   159 

   160 COMMON OPTIONS

   161 

   162     --encoding=terminal,filesystem

   163     -e terminal,filesystem

   164 

   165 Local character encodings for terminal and filesystem. For example

   166 "--encoding=utf8,latin1", if the terminal is using a UTF-8 character set

   167 and the filesystem is still using the older latin1 (ISO-8859-1)

   168 character set. See [11] for a list of Python standard encodings.

   169 

   170 The encodings will be autodetected most of the time, but on some special

   171 environments this may not be possible, hence this option.

   172 

   173     --verbose

   174     -v

   175 

   176 Print extra statistics, such as file names, option summary.

   177 

   178     --help

   179     -h

   180 

   181 On-line help for a command can be found using this option.

   182 

   183 

   184 EXAMPLES

   185 

   186     $ ensymble.py

   187 

   188     Ensymble developer utilities for Symbian OS

   189 

   190     usage: ensymble.py command [command options]...

   191 

   192     Commands:

   193         altere32   Alter the IDs and capabilities of e32image files (EXEs, DLLs)

   194         genuid     Generate a new test-range UID from a name

   195         infoe32    Show the IDs and capabilities of e32image files (EXEs, DLLs)

   196         mergesis   Merge several SIS packages into one

   197         py2sis     Create a SIS package for a "Python for S60" application

   198         signsis    Sign a SIS package

   199         simplesis  Create a SIS package from a directory structure

   200         version    Print Ensymble version

   201 

   202     Use 'ensymble.py command --help' to get command specific help.

   203 

   204 When no commands and options are given, Ensymble prints a short help.

   205 

   206     $ ensymble.py version -h

   207 

   208     Ensymble developer utilities for Symbian OS

   209 

   210     usage: ensymble.py version

   211 

   212     Print Ensymble version.

   213 

   214 Each command has an on-line help. A short description of what the

   215 command does and a list of options are printed.

   216 

   217 

   218 The "altere32" command

   219 ----------------------

   220 

   221 SYNOPSIS

   222 

   223     $ ensymble.py altere32

   224         [--uid=0x01234567] [--secureid=0x01234567] [--vendorid=0x01234567]

   225         [--caps=Cap1+Cap2+...] [--encoding=terminal,filesystem] [--verbose]

   226         <infile> <outfile>

   227 

   228 or

   229 

   230     $ ensymble.py altere32

   231         [--uid=0x01234567] [--secureid=0x01234567] [--vendorid=0x01234567]

   232         [--caps=Cap1+Cap2+...] [--encoding=terminal,filesystem] [--verbose]

   233         --inplace <infile>...

   234 

   235 

   236 DESCRIPTION

   237 

   238 The "altere32" command alters the IDs and capabilities of e32image files

   239 (Symbian EXEs and DLLs). Extension module authors can use this command

   240 to quickly generate variations of extension modules without recompiling.

   241 

   242 

   243 PARAMETERS

   244 

   245     infile

   246 

   247 Path of the original e32image file. If option "--inplace" (see below) is

   248 set, there may be more than one file name present.

   249 

   250     outfile

   251 

   252 Path of the modified e32image file. Only used when not using option

   253 "--inplace", see below. If a directory name is given, input file name is

   254 used as the output file name.

   255 

   256     --inplace

   257     -i

   258 

   259 Allow more than one input file name, modify input files in-place.

   260 

   261 Note: Use this option with caution, as no backups of the original files

   262 will be made!

   263 

   264     --uid=0x01234567

   265     -u 0x01234567

   266 

   267 Symbian UID for the e32image. This is normally same as the secure ID,

   268 see below. If this option is not given, the UID is not changed.

   269 

   270     --secureid=0x01234567

   271     -s 0x01234567

   272 

   273 Secure ID for the e32image. This is normally same as the UID, see above.

   274 If this option is not given, the secure ID is not changed.

   275 

   276     --vendorid=0x01234567

   277     -r 0x01234567

   278 

   279 Vendor ID for the e32image. In most cases the vendor ID is 0. If this

   280 option is not given, the vendor ID is not changed.

   281 

   282     --caps=Cap1+Cap2+...

   283     -b Cap1+Cap2+...

   284 

   285 or

   286 

   287     --caps=0x12345

   288     -b 0x12345

   289 

   290 Capability names separated by "+" or a numeric capability bitmask. If no

   291 capability option is given, capabilities are not changed.

   292 

   293     --heapsize=min,max

   294     -H min,max

   295 

   296 Heap size limits for the e32image, only valid for EXEs. If no heap size

   297 option is given, the heap size limits are not changed. If only one value

   298 is given, it is used as both the heap minimum value and heap maximum

   299 value.

   300 

   301 Values may have suffix "k" or "M" (case insensitive) to denote kilobytes

   302 (1024 bytes) and megabytes (1048576 bytes), respectively.

   303 

   304 The heap minimum value determines if a program is allowed to start. If

   305 less than the set amount of memory is available, program start-up fails.

   306 The heap maximum value limits the memory a program can allocate. Memory

   307 allocations beyond the set limit will fail.

   308 

   309 

   310 EXAMPLES

   311 

   312 Note: The command lines below may be wrapped over multiple lines due to

   313 layout constraints. In reality, each of them should be contained in one

   314 physical command line, with no spaces around the "+" characters.

   315 

   316     $ ensymble.py altere32

   317         --caps=LocalServices+Location+NetworkServices+PowerMgmt+ProtServ+

   318         ReadUserData+SurroundingsDD+SWEvent+UserEnvironment+WriteUserData+

   319         ReadDeviceData+TrustedUI+WriteDeviceData

   320         myextension_orig.pyd myextension.pyd

   321 

   322 This will modify "myextension_orig.pyd" (a "Python for S60" extension

   323 DLL) with the capabilities listed, and generate file "myextension.pyd"

   324 with the new capabilities.

   325 

   326     $ ensymble.py altere32 --caps=0xff1b4 --inplace *.dll

   327 

   328 This modifies every DLL file in the current directory using the same

   329 capabilities as above but in a numeric form. Original files will be

   330 modified, so use the "--inplace" option with caution!

   331 

   332     $ ensymble.py altere32 --heapsize=4k,4M myapp_orig.exe myapp.exe

   333 

   334 Program "myapp.exe" is modified so that it can allocate upto four

   335 megabytes of memory. Heap minimum value is usually kept at the default

   336 four kilobytes.

   337 

   338 Note: When modifying the UID, the secure ID should be modified

   339 accordingly. Modifying UIDs of application EXEs is generally not

   340 possible, because applications usually include the UID in program code

   341 as well.

   342 

   343 

   344 The "genuid" command

   345 --------------------

   346 

   347 SYNOPSIS

   348 

   349     $ ensymble.py genuid

   350     [--encoding=terminal,filesystem] [--verbose]

   351     <name>...

   352 

   353 

   354 DESCRIPTION

   355 

   356 The "genuid" command generates a test-range UID from an application or

   357 extension module name. It is suggested that Ensymble-generated UIDs are

   358 used instead of choosing an arbitrary test-range UID, to prevent clashes

   359 with software from other authors.

   360 

   361 

   362 PARAMETERS

   363 

   364     name

   365 

   366 One or more names for which UIDs are generated. Names are

   367 case-insensitive and fully support the international Unicode characters.

   368 

   369 Generated UIDs are compatible with the automatic UID generation of

   370 py2sis and simplesis commands. The name must not contain version

   371 information or any file prefixes, just the name itself, e.g.

   372 "myextension" instead of "myextension_v1.2.3.sis".

   373 

   374 

   375 EXAMPLES

   376 

   377     $ ensymble.py genuid myapplication myextension

   378     myapplication: 0xe0942bea

   379     myextension: 0xe325ed58

   380 

   381 This will generate two UIDs: one for "myapplication" and another for

   382 "myextension".

   383 

   384 

   385 The "infoe32" command

   386 ---------------------

   387 

   388 SYNOPSIS

   389 

   390     $ ensymble.py infoe32

   391     [--encoding=terminal,filesystem] [--verbose]

   392     <infile>...

   393 

   394 

   395 DESCRIPTION

   396 

   397 The "infoe32" command displays information about Symbian e32image files

   398 (Symbian EXEs and DLLs). All three UIDs as well as the vendor ID and

   399 secure ID are printed. Capabilities are displayed textually and as a

   400 hexadecimal number.

   401 

   402 

   403 PARAMETERS

   404 

   405     infile

   406 

   407 One or more e32image files to inspect.

   408 

   409 

   410 EXAMPLES

   411 

   412     $ ensymble.py infoe32 myprogram.exe somelibrary.dll

   413     myprogram.exe:

   414         UID1          0x1000007a

   415         UID2          0x100039ce

   416         UID3          0x12345678

   417         Secure ID     0x12345678

   418         Vendor ID     0x00000000

   419         Capabilities  0x0 (NONE)

   420     somelibrary.dll:

   421         UID1          0x10000079

   422         UID2          0x00000000

   423         UID3          0x00000000

   424         Secure ID     0x00000000

   425         Vendor ID     0x00000000

   426         Capabilities  0xff7be (ALL-TCB-DRM-AllFiles)

   427 

   428 This will display information about "myprogram.exe" and

   429 "somelibrary.dll".

   430 

   431 

   432 The "mergesis" command

   433 ----------------------

   434 

   435 SYNOPSIS

   436     $ ensymble.py mergesis

   437         [--cert=mycert.cer] [--privkey=mykey.key] [--passphrase=12345]

   438         [--encoding=terminal,filesystem] [--verbose]

   439         <infile> [mergefile]... <outfile>

   440 

   441 

   442 DESCRIPTION

   443 

   444 The "mergesis" command takes a set of SIS files and inserts them as

   445 unconditional embedded SIS files in the first one. The resulting SIS

   446 package is then signed with the certificate provided. None of the

   447 certificates of the first SIS file are preserved.

   448 

   449 Note: The "mergesis" command will only work with SIS files that do not

   450 already contain other embedded SIS files.

   451 

   452 

   453 PARAMETERS

   454 

   455     infile

   456 

   457 Path of the base SIS file.

   458 

   459     mergefile

   460 

   461 Zero or more SIS files to embed in the base sis file.

   462 

   463     outfile

   464 

   465 Path of the resulting SIS file. If a directory name is given, base SIS

   466 file name is used as the output file name.

   467 

   468     --cert=mycert.cer

   469     -a mycert.cer

   470 

   471 Certificate to use for signing in PEM (text) format. If no certificate

   472 and its private key are given, Ensymble uses a default self-signed

   473 certificate (see option "--cert" for command "py2sis" above).

   474 

   475     --privkey=mykey.key

   476     -k mykey.key

   477 

   478 Private key of the certificate in PEM (text) format. If option "--cert"

   479 (above) is given, this option is required as well.

   480 

   481     --passphrase=12345

   482     -p 12345

   483 

   484 Pass phrase of the private key.

   485 

   486 Note: Using command line options to give the pass phrase is insecure.

   487 Any user of the computer will be able to see command lines of started

   488 programs and thus will see the pass phrase in plain view. Instead,

   489 standard input should be used (see examples below).

   490 

   491 If no pass phrase is given on the command line or standard input, it

   492 will be asked interactively.

   493 

   494 

   495 EXAMPLES

   496 

   497 Note: The command lines below may be wrapped over multiple lines due to

   498 layout constraints. In reality, each of them should be contained in one

   499 physical command line.

   500 

   501     $ ensymble.py mergesis

   502         --cert=mycert.cer --key=mykey.key --passphrase=12345

   503         myapp_v1_0_0.sis PythonForS60_1_3_17_3rdEd_selfsigned.SIS

   504         myapp_standalone_v1_0_0.sis

   505 

   506 A Python for S60 script "myapp_v1_0_0.sis" will be merged with Python

   507 runtime SIS "PythonForS60_1_3_17_3rdEd_selfsigned.SIS". A new SIS file

   508 "myscript_standalone_v1_0_0.sis" will be created and signed with

   509 "mycert.cer" using private key "mykey.key".

   510 

   511     $ echo "12345" | ensymble.py mergesis

   512         --cert=mycert.cer --key=mykey.key

   513         basefile.sis addon1.sis addon2.sis

   514 

   515 Pass phrase can be given in Ensymble standard input, so that it will not

   516 be visible to all users of the computer (see option "--passphrase"

   517 above).

   518 

   519 

   520 The "py2sis" command

   521 --------------------

   522 

   523 SYNOPSIS

   524 

   525     $ ensymble.py py2sis

   526         [--uid=0x01234567] [--appname=AppName] [--version=1.0.0]

   527         [--lang=EN,...] [--icon=icon.svg] [--shortcaption="App. Name",...]

   528         [--caption="Application Name",...] [--drive=C]

   529         [--textfile=mytext_%C.txt] [--cert=mycert.cer] [--privkey=mykey.key]

   530         [--passphrase=12345] [--caps=Cap1+Cap2+...]

   531         [--vendor="Vendor Name",...] [--autostart]

   532         [--encoding=terminal,filesystem] [--verbose]

   533         <src> [sisfile]

   534 

   535 

   536 DESCRIPTION

   537 

   538 The "py2sis" command is used to pack a Python for S60 application script

   539 and its auxiliary files (if any) into a Symbian installation package

   540 (SIS).

   541 

   542 

   543 PARAMETERS

   544 

   545     src

   546 

   547 The source script or directory name. When a directory name is given, the

   548 directory structure is preserved under an application specific private

   549 directory ("\private\<uid>\") on the phone. A file called "default.py"

   550 is required to exist on the root of the directory given. This will be

   551 the main file that starts the application. (See option "--extrasdir"

   552 below for more options for file placement.)

   553 

   554 When a regular file name is given, it will be located under the

   555 application specific private directory, with the name "default.py".

   556 

   557     sisfile

   558 

   559 Path of the SIS file to create. If a directory name is given, output

   560 file name is derived from input file name and application version (see

   561 option "--version" below). This is also the case when no SIS file name

   562 is given.

   563 

   564     --appname=AppName

   565     -n AppName

   566 

   567 Name of the application. If no application name is given, it will be

   568 derived from the input file name.

   569 

   570 This name is used as the base for all generated file names (EXE, icon,

   571 resources) on the phone. It will also be used as the default caption if

   572 none are given, and a temporary UID (see option "--uid" below) will be

   573 generated from application name if not given explicitly.

   574 

   575     --uid=0x01234567

   576     -u 0x01234567

   577 

   578 Symbian UID for the application. If the UID option is not given, the

   579 main Python file ("default.py", see parameter "src" above) will be

   580 scanned for a special string. If no UID can be found, a temporary UID is

   581 generated from the application name (see option "--appname" and command

   582 "genuid" above).

   583 

   584 The special UID string can appear anywhere in the main Python file,

   585 including comments and as part of string literals. It is of the form

   586 

   587     SYMBIAN_UID = UID

   588 

   589 , where whitespace around the equals sign is optional. UID is in the

   590 same format as with the command line parameter (see option "--uid"

   591 above).

   592 

   593 Note: Use a real UID for all applications to be distributed. The

   594 auto-generated test-range UID is only meant for development and testing,

   595 not for real applications. UIDs can be ordered from Symbian Signed [12].

   596 If you have already ordered UIDs for 1st or 2nd Edition phones, to use

   597 these UIDs in 3rd Edition phones the first hex digit (a "1") needs to be

   598 changed to an "f".

   599 

   600 Also note: When changing the application name (or source file /

   601 directory name in case no application name is explicitly given), the

   602 temporary UID changes and the SIS package will be considered a new

   603 application on the phone, unless an UID is explicitly specified.

   604 

   605     --version=1.0.0

   606     -r 1.0.0

   607 

   608 Application version: X.Y.Z or X,Y,Z (major, minor, build). There may be

   609 a "v" or "V" in front of the major number. Minor and build numbers are

   610 optional.

   611 

   612 If the version option is not given, the main Python file ("default.py",

   613 see parameter "src" above) will be scanned for a special string. If no

   614 version can be found, it defaults to 1.0.0.

   615 

   616 The special version string can appear anywhere in the main Python file,

   617 including comments and as part of string literals. It is of the form

   618 

   619     SIS_VERSION = "1.0.0"

   620 

   621 , where whitespace around the equals sign is optional. Version is in the

   622 same format as with the command line parameter (see option "--version"

   623 above), except that it may optionally be enclosed in single or double

   624 quotes.

   625 

   626     --lang=EN,...

   627     -l EN,...

   628 

   629 Comma separated list of two-character language codes. These are the

   630 languages that the SIS file claims to support, English by default.

   631 Application must then somehow determine which language was selected

   632 during install. Symbian installation tools reference [13] lists the

   633 available language codes.

   634 

   635     --icon=icon.svg

   636     -i icon.svg

   637 

   638 Icon file in SVG-Tiny format. If no icon is given, the Python logo is

   639 used as the icon. The Python logo is a trademark of the Python Software

   640 Foundation.

   641 

   642 Ensymble does not support the old style MBM bitmap icons.

   643 

   644     --shortcaption="App. Name",...

   645     -s "App. Name",...

   646 

   647     --caption="Application Name",...

   648     -c "Application Name",...

   649 

   650 Comma separated list of short and long captions in all selected

   651 languages, i.e. there must be as many comma separated captions as there

   652 are languages listed with the "--lang" option. If no captions are given,

   653 application name is used (see option "--appname" above). If only the

   654 short captions are given, long captions will use those instead.

   655 

   656 Captions are visible names used in various places on the phone display.

   657 Short caption is displayed under the application icon when using the

   658 grid layout. Long caption is used on top of the screen when the

   659 application is launched and beside the icon in list layout. Long caption

   660 is also used as the package name, which is displayed during application

   661 installation.

   662 

   663     --drive=C

   664     -f C

   665 

   666 Installation drive "C" or "E" or "any", to select where the SIS is to be

   667 installed. Default is "any", which causes the phone to ask the user

   668 where to install the package.

   669 

   670     --extrasdir=root

   671     -x root

   672 

   673 Name of "extras" directory under the application source directory. The

   674 extras directory contains a directory tree which is placed under the

   675 root of the installation drive, instead of in the application private

   676 directory. If no extras directory name is given, this feature is

   677 disabled.

   678 

   679 Option "--extrasdir" is similar to the "simplesis" command (see below).

   680 It allows placing files under "\sys\bin" and "\resource", for example.

   681 

   682     --textfile=mytext_%C.txt

   683     -t mytext_%C.txt

   684 

   685 Text file (or pattern, see below) to display during install. If none is

   686 given, no extra text will be displayed during install.

   687 

   688 Files to display are in UTF-8 encoding, without Byte-Order Marker (BOM).

   689 The file name may contain formatting characters that are substituted for

   690 each selected language (see option "--lang" above). If no formatting

   691 characters are present, the same text will be used for all languages.

   692 

   693     %%           - literal %

   694     %n           - language number (01 - 99)

   695     %c           - two-character language code in lowercase letters

   696     %C           - two-character language code in capital letters

   697     %l           - language name in English, using only lowercase letters

   698     %l           - language name in English, using mixed case letters

   699 

   700 For example, if there are files named "mytext_EN.txt", "mytext_GE.txt"

   701 and "mytext_SP.txt", a pattern of "mytext_%C.txt" will be able to use

   702 them.

   703 

   704     --cert=mycert.cer

   705     -a mycert.cer

   706 

   707 Certificate to use for signing in PEM (text) format.

   708 

   709 SIS files for Symbian OS v9 and later are required to be digitally

   710 signed. Unsigned packages will not install on the phone. A

   711 self-generated ("self-signed" in crypto parlance) certificate will do,

   712 but only a restricted subset of features ("capabilities", see option

   713 "--caps" below) are available for self-signed applications.

   714 

   715 If no certificate and its private key are given, Ensymble uses a default

   716 self-signed certificate. Software authors are encouraged to create their

   717 own unique certificates for SIS packages that are to be distributed.

   718 

   719     --privkey=mykey.key

   720     -k mykey.key

   721 

   722 Private key of the certificate in PEM (text) format. If option "--cert"

   723 (above) is given, this option is required as well.

   724 

   725     --passphrase=12345

   726     -p 12345

   727 

   728 Pass phrase of the private key.

   729 

   730 Note: Using command line options to give the pass phrase is insecure.

   731 Any user of the computer will be able to see command lines of started

   732 programs and thus will see the pass phrase in plain view. Instead,

   733 standard input should be used (see examples below).

   734 

   735 If no pass phrase is given on the command line or standard input, it

   736 will be asked interactively.

   737 

   738     --caps=Cap1+Cap2+...

   739     -b Cap1+Cap2+...

   740 

   741 or

   742 

   743     --caps=0x12345

   744     -b 0x12345

   745 

   746 Capability names separated by "+" or a numeric capability bitmask. If no

   747 capability option is given, the capabilities : LocalServices, NetworkServices,

   748 ReadUserData, WriteUserData and UserEnvironment are granted by default. 

   749 Symbian Signed [12] has an FAQ which explains all the available capabilities.

   750 

   751     --vendor=Name,...

   752     -d Name,...

   753 

   754 Comma separated list of vendor names in all selected languages, i.e.

   755 there must be as many comma separated vendor names as there are

   756 languages listed with the "--lang" option. Alternatively, if only one

   757 vendor name is given, it will be used for all languages. If no vendor

   758 names are given then "Ensymble" will be used.

   759 

   760 Vendor name is visible during installation and on the Application

   761 manager, except when using self-signed certificates (see option "--cert"

   762 above).

   763 

   764     --autostart

   765     -g

   766 

   767 Flag to control automatic startup of the application. On S60 3rd Edition

   768 phones, an application can register itself to be automatically started

   769 when the phone is turned on.

   770 

   771 Note: Self-signed applications and applications with UID in the

   772 unprotected range cannot register to be automatically started (see

   773 options "--uid" and "--cert" above).

   774 

   775     --runinstall

   776     -R

   777 

   778 Run the application after installation. After copying all files to the

   779 phone, the application is automatically started.

   780 

   781 Note: Phones will ignore this flag in SIS files using self-signed

   782 certificates (see option "--cert" above).

   783 

   784     --heapsize=min,max

   785     -H min,max

   786 

   787 Heap size limits for the application. Defaults of 100 kilobytes and four

   788 megabytes are used if no heap size option is given. If only one value is

   789 given, it is used as both the heap minimum and heap maximum value.

   790 

   791 Values may have suffix "k" or "M" (case insensitive) to denote kilobytes

   792 (1024 bytes) and megabytes (1048576 bytes), respectively.

   793 

   794 The heap minimum value determines if a program is allowed to start. If

   795 less than the set amount of memory is available, program start-up fails.

   796 The heap maximum value limits the memory a program can allocate. Memory

   797 allocations beyond the set limit will fail. The default of one megabyte

   798 is usually enough, but processing large datasets such as images from an

   799 integrated camera might require setting the heap maximum value higher.

   800 

   801     --profile=console

   802     -P console

   803 

   804 The profile selected determines the environment in which the packaged Python 

   805 script is run. The two possible values are 's60ui' and 'console', the former

   806 being the default value. The Python core remains the same in both the profiles.

   807 

   808 If the console profile is selected then the application needs OpenC's STDIO

   809 console already installed. All UI related modules like appuifw, graphics will

   810 not work in this mode.

   811 

   812     --mode=pycore

   813     -m pycore

   814 

   815 The mode option takes two values - 'pycore' or 'pys60'. Setting the mode as

   816 'pycore' will result in the Python core modules taking priority over the PyS60

   817 extension modules when module names conflict. When 'pycore' mode is selected

   818 the conflicting PyS60 extension modules will not be available with the same

   819 name. However you can import the conflicting modules using their new names as

   820 mentioned in the note below. In 'pys60' mode the conflicting core modules will

   821 not be available at all. The default value of this option is 'pycore'.

   822 Note: calendar and socket are the only two conflicting modules and they can be

   823 imported using their new names e32calendar and btsocket in 'pycore' mode.

   824 

   825     --extra-modules=mod1,mod2

   826     -o mod1,mod2

   827 

   828 This option can be used to specify any additional dependencies that should be

   829 packaged with the application sis. The dependencies will be searched in the

   830 custom search paths specified in module_search_path.cfg present under the

   831 dev-modules directory and then in standard-module and dev-modules directories.

   832 

   833     --ignore-missing-deps

   834 

   835 If specified the packaging continues by displaying any missing dependencies as

   836 warnings. Else packaging is aborted after displaying the missing dependencies

   837 as errors.

   838 

   839     --platform-uid=0x101f7961,...

   840 

   841 This option can be used to specify the S60 platform UID of the devices on which

   842 the application is supported. The default value of this option are 

   843 0x101f7961 and 0x1028315F (referring to S603rdEditon and S605thEditon UID 

   844 respectively)

   845     

   846     --sourcecode

   847 

   848 By default the application is packaged as bytecode. In this mode, the module

   849 import is faster but the source code is not visible in tracebacks. With the

   850 --sourcecode option, the application is packaged as source code and as a result

   851 tracebacks contain the code.

   852 

   853 EXAMPLES

   854 

   855 Note: The command lines below may be wrapped over multiple lines due to

   856 layout constraints. In reality, each of them should be contained in one

   857 physical command line.

   858 

   859     $ ensymble.py py2sis myprog.py

   860 

   861 This generates a SIS file called "myprog_v1_0_0.sis" in current working

   862 directory. This SIS file is ready to be uploaded to a S60 3rd Edition

   863 phone. Package version defaults to 1.0.0, a test-range UID is

   864 auto-generated for the package and a default self-signed certificate is

   865 used to digitally sign the SIS file. A default icon (the Python logo) is

   866 used for application icon.

   867 

   868     $ echo "12345" | ensymble.py py2sis

   869         --cert mycert.cer --privkey mykey.key

   870         myprog.py

   871 

   872 Pass phrase can be given in Ensymble standard input, so that it will not

   873 be visible to all users of the computer (see option "--passphrase"

   874 above).

   875 

   876 

   877 The "signsis" command

   878 ---------------------

   879 

   880 SYNOPSIS

   881 

   882     $ ensymble.py signsis

   883         [--unsign]

   884         [--cert=mycert.cer] [--privkey=mykey.key] [--passphrase=12345]

   885         [--execaps=Cap1+Cap2+...] [--dllcaps=Cap1+Cap2+...]

   886         [--encoding=terminal,filesystem] [--verbose]

   887         <infile> [outfile]

   888 

   889 

   890 DESCRIPTION

   891 

   892 The "signsis" command (re-)signs a SIS package with the certificate

   893 provided, stripping out any existing certificates, if any. Capabilities

   894 of all EXE and DLL files contained in the SIS package can optionally be

   895 modified.

   896 

   897 Extension module authors may want to distribute a version of their SIS

   898 packages with only limited capabilities. Users can then adjust the

   899 capabilities according to their own needs and sign the SIS package with

   900 their own certificates.

   901 

   902 Note: SIS packages may embed other SIS packages. The "signsis" command

   903 will only alter the main SIS, leaving all embedded SIS packages intact.

   904 

   905 

   906 PARAMETERS

   907 

   908     infile

   909 

   910 Path of the original SIS file.

   911 

   912     outfile

   913 

   914 Path of the modified SIS file. If a directory name is given, input file

   915 name is used as the output file name.

   916 

   917 Note: If no output file name is given, original SIS file is overwritten!

   918 

   919     --unsign

   920     -u

   921 

   922 Instead of signing a SIS file, remove all signatures from it. This is

   923 useful when submitting the SIS file to an external signing authority,

   924 otherwise the Ensymble default certificate may remain in the resulting

   925 signed SIS file.

   926 

   927     --cert=mycert.cer

   928     -a mycert.cer

   929 

   930 Certificate to use for signing in PEM (text) format. If no certificate

   931 and its private key are given, Ensymble uses a default self-signed

   932 certificate (see option "--cert" for command "py2sis" above).

   933 

   934     --privkey=mykey.key

   935     -k mykey.key

   936 

   937 Private key of the certificate in PEM (text) format. If option "--cert"

   938 (above) is given, this option is required as well.

   939 

   940     --passphrase=12345

   941     -p 12345

   942 

   943 Pass phrase of the private key.

   944 

   945 Note: Using command line options to give the pass phrase is insecure.

   946 Any user of the computer will be able to see command lines of started

   947 programs and thus will see the pass phrase in plain view. Instead,

   948 standard input should be used (see examples below).

   949 

   950 If no pass phrase is given on the command line or standard input, it

   951 will be asked interactively.

   952 

   953     --execaps=Cap1+Cap2+...

   954     -b Cap1+Cap2+...

   955 

   956 or

   957 

   958     --execaps=0x12345

   959     -b 0x12345

   960 

   961 Capability names separated by "+" or a numeric capability bitmask. EXEs

   962 inside the SIS file will be modified according to these capabilities. If

   963 no capability option is given, no EXEs will be modified. Symbian Signed

   964 [12] has an FAQ which explains all the available capabilities.

   965 

   966     --dllcaps=Cap1+Cap2+...

   967     -d Cap1+Cap2+...

   968 

   969 or

   970 

   971     --dllcaps=0x12345

   972     -d 0x12345

   973 

   974 Capability names separated by "+" or a numeric capability bitmask. DLLs

   975 inside the SIS file will be modified according to these capabilities. If

   976 no capability option is given, no DLLs will be modified.

   977 

   978 

   979 EXAMPLES

   980 

   981 Note: The command lines below may be wrapped over multiple lines due to

   982 layout constraints. In reality, each of them should be contained in one

   983 physical command line, with no spaces around the "+" characters.

   984 

   985     $ ensymble.py signsis

   986         --dllcaps=LocalServices+Location+NetworkServices+PowerMgmt+ProtServ+

   987         ReadUserData+SurroundingsDD+SWEvent+UserEnvironment+WriteUserData+

   988         ReadDeviceData+TrustedUI+WriteDeviceData

   989         --cert=mycert.cer --key=mykey.key --passphrase=12345

   990         coolextension_nocert.sis coolextension_mycert.sis

   991 

   992 Extension module "coolextension_nocert.sis" will be modified with the

   993 capabilities listed. A new SIS file "coolextension_mycert.sis" will be

   994 created and signed with "mycert.cer" using private key "mykey.key".

   995 

   996     $ echo "12345" | ensymble.py signsis

   997         --dllcaps=0xff1b4 --cert=mycert.cer --key=mykey.key

   998         coolextension_nocert.sis coolextension_mycert.sis

   999 

  1000 Pass phrase can be given in Ensymble standard input, so that it will not

  1001 be visible to all users of the computer (see option "--passphrase"

  1002 above).

  1003 

  1004 

  1005 The "simplesis" command

  1006 -----------------------

  1007 

  1008 SYNOPSIS

  1009 

  1010     $ ensymble.py simplesis

  1011         [--uid=0x01234567] [--version=1.0.0] [--lang=EN,...]

  1012         [--caption="Package Name",...] [--drive=C] [--textfile=mytext_%C.txt]

  1013         [--cert=mycert.cer] [--privkey=mykey.key] [--passphrase=12345]

  1014         [--vendor="Vendor Name",...] [--encoding=terminal,filesystem]

  1015         [--verbose]

  1016         <srcdir> [sisfile]

  1017 

  1018 

  1019 DESCRIPTION

  1020 

  1021 The "simplesis" command is used to create a Symbian installation package

  1022 (SIS) from an existing directory structure. Conditional inclusion of

  1023 files, dependencies or other fancy features of SIS files are not

  1024 supported.

  1025 

  1026 

  1027 PARAMETERS

  1028 

  1029     srcdir

  1030 

  1031 The source directory name. The directory structure is preserved under

  1032 the installation drive, i.e files and directories under "srcdir" will be

  1033 located on the root of the installation drive.

  1034 

  1035     sisfile

  1036 

  1037 Path of the SIS file to create. If a directory name is given, output

  1038 file name is derived from source directory name and package version (see

  1039 option "--version" below). This is also the case when no SIS file name

  1040 is given.

  1041 

  1042     --uid=0x01234567

  1043     -u 0x01234567

  1044 

  1045 Symbian UID for the package. If the UID option is not given, the source

  1046 directory name will be used to generate a temporary UID (see command

  1047 "genuid" above).

  1048 

  1049 Note: Use a real UID for all packages to be distributed. The

  1050 auto-generated test-range UID is only meant for development and testing,

  1051 not for real packages. UIDs can be ordered from Symbian Signed [12]. If

  1052 you have already ordered UIDs for 1st or 2nd Edition phones, to use

  1053 these UIDs in 3rd Edition phones the first hex digit (a "1") needs to be

  1054 changed to an "f".

  1055 

  1056 Also note: When changing the source directory name, the temporary UID

  1057 changes and the SIS package will be considered a new application on the

  1058 phone.

  1059 

  1060     --version=1.0.0

  1061     -r 1.0.0

  1062 

  1063 Package version: X.Y.Z or X,Y,Z (major, minor, build). There may be a

  1064 "v" or "V" in front of the major number. Minor and build numbers are

  1065 optional.

  1066 

  1067 If the version option is not given it defaults to 1.0.0.

  1068 

  1069     --lang=EN,...

  1070     -l EN,...

  1071 

  1072 Comma separated list of two-character language codes. These are the

  1073 languages that the SIS file claims to support, English by default.

  1074 Symbian installation tools reference [13] lists the available language

  1075 codes.

  1076 

  1077     --caption="Application Name",...

  1078     -c "Application Name",...

  1079 

  1080 Comma separated list of package captions in all selected languages, i.e.

  1081 there must be as many comma separated captions as there are languages

  1082 listed with the "--lang" option. If no captions are given, source

  1083 directory name is used (see parameter "srcdir" above).

  1084 

  1085 Package caption is displayed during application installation.

  1086 

  1087     --drive=C

  1088     -f C

  1089 

  1090 Installation drive "C" or "E" or "any", to select where the SIS is to be

  1091 installed. Default is "any", which causes the phone to ask the user

  1092 where to install the package.

  1093 

  1094     --textfile=mytext_%C.txt

  1095     -t mytext_%C.txt

  1096 

  1097 Text file (or pattern, see below) to display during install. If none is

  1098 given, no extra text will be displayed during install.

  1099 

  1100 Files to display are in UTF-8 encoding, without Byte-Order Marker (BOM).

  1101 The file name may contain formatting characters that are substituted for

  1102 each selected language (see option "--lang" above). If no formatting

  1103 characters are present, the same text will be used for all languages.

  1104 

  1105     %%           - literal %

  1106     %n           - language number (01 - 99)

  1107     %c           - two-character language code in lowercase letters

  1108     %C           - two-character language code in capital letters

  1109     %l           - language name in English, using only lowercase letters

  1110     %l           - language name in English, using mixed case letters

  1111 

  1112 For example, if there are files named "mytext_EN.txt", "mytext_GE.txt"

  1113 and "mytext_SP.txt", a pattern of "mytext_%C.txt" will be able to use

  1114 them.

  1115 

  1116     --cert=mycert.cer

  1117     -a mycert.cer

  1118 

  1119 Certificate to use for signing in PEM (text) format.

  1120 

  1121 SIS files for Symbian OS v9 and later are required to be digitally

  1122 signed. Unsigned packages will not install on the phone. A

  1123 self-generated ("self-signed" in crypto parlance) certificate will do,

  1124 but only a restricted subset of features ("capabilities", see option

  1125 "--caps" below) are available for self-signed applications.

  1126 

  1127 If no certificate and its private key are given, Ensymble uses a default

  1128 self-signed certificate. Software authors are encouraged to create their

  1129 own unique certificates for SIS packages that are to be distributed.

  1130 

  1131     --privkey=mykey.key

  1132     -k mykey.key

  1133 

  1134 Private key of the certificate in PEM (text) format. If option "--cert"

  1135 (above) is given, this option is required as well.