PYTHON FOR S60

==============

Python(r) for S60 is a scripting language environment for the S60 smartphone

platform, based on Python 2.5.4.

Note: This README instructs how you can build Python for S60. If you are only

developing Python scripts for a Nokia device you can use the existing binary

builds for development - in this case building PyS60 from source code is not

needed.

TRADEMARKS

==========

Python and the Python logo are registered trademarks of the Python

Software Foundation.

LICENSING

=========

Copyright (c) 2005-2009 Nokia Corporation. This is Python for S60 created by

Nokia Corporation. The original software, including modifications of Nokia

Corporation therein, is licensed under the applicable license(s) for

Python 2.5.4, unless specifically indicated otherwise in the relevant source

code file.

See http://www.apache.org/licenses/LICENSE-2.0

and http://www.python.org/2.5.4/license.html

CHANGES TO PYTHON 2.5.4

=======================

See the file changes.txt for a list of changes to Python 2.5.4.

REQUIREMENTS

============

To build PyS60, you need:

- Python 2.5.x

- Open C/C++ Plug-ins. 

  Refer the release notes for the exact version of plug-ins compatible with

  this release.

- S60 C++ SDK. Currently supported versions for building are:

  - S60 SDK 3.0, S60 SDK 3.2 and S60 SDK 5.0

   - To patch the SDK's headers you need the GNU patch utility.

Adding support for other SDK versions is probably not very

difficult. See the beginning of setup.py for the configuration

parameters required.

Requirements for extensions

============================

sensor

------

The Sensor API plug-in from Forum Nokia is needed for building sensor module on

all S60 3rd Edition SDKs. On S60 5th Edition Sdk, the module can be built

without any plug-in

"Sensor Plug-in for S60 3rd Edition SDK for Symbian OS, for C++, MR, for Nokia

5500 Sport"

Available from:

http://www.forum.nokia.com/info/sw.nokia.com/id/4284ae69-d37a-4319-bdf0-d4acdab39700/Sensor_plugin_S60_3rd_ed.exe.html

"Sensor API Plug-in for S60 3rd Edition SDK for Symbian OS, Feature Pack 2", MR,

for Nokia N85, N96, E75, 6720, 6210, 6710 and E55

Available from:

http://www.forum.nokia.com/info/sw.nokia.com/id/8059e8ae-8c22-4684-be6b-d40d443d7efc/Sensor_API_Plug_in_S60_3rd_FP2.html

The sensor extension has been tested in Nokia N95 and 5800 XpressMusic. The 

sensor module cannot be loaded on the emulator because of the limitations in the

sensor plug-in.

There are 2 sensor modules available

a. src\ext\amaretto\sensor - for S60 3rd Edition SDK and S60 3rd Edition SDK FP1

b. src\ext\sensorfw - for S60 3rd Edition SDK FP2 and S60 5th Edition SDK

You can compile the code without the sensor module by removing the respective

mmp file entry from \src\newcore\Symbian\group\bld.inf.in.template.

Extension

---------

The C++ extensions plug-ins for S60 3rd Edition SDKs extend the features of an

S60 platform SDK, offering improved device emulation and support for additional

functionality included in shipped devices or specific to a certain device.

As a result, the plug-ins enable a greater range of applications to be built and

tested using the S60 device emulator supplied in the SDK. The Extension plug-in

is available at this URL:

http://www.forum.nokia.com/info/sw.nokia.com/id/48a93bd5-028a-4b3e-a0b1-148ff203b2b3/Extensions_plugin_S60_3rd_ed.html

FIXING THE S60 3rd edition HEADERS

==================================

There are some bugs in the shipped SDK headers. To fix these, you must

apply the patch pys60-fix-3rded-sdk.diff. To do this, you will need

the GNU patch utility.

You can patch the headers by going to the \epoc32\include directory on

your SDK drive and giving the command:

  patch -p1 < (path to the diff file)\src\misc\pys60-fix-3rded-sdk.diff

You need to do this only once.

FIXING THE x86 compiler build issues

====================================

Python source code doesn't get compiled using the latest x86 compiler 

(build > 471). Work around would be is to download x86 compiler of build 471 

from the link "http://tools.ext.nokia.com/download/beta_build.php" and extract 

the same to epoc32 folder.

COMPILING

=========

- The build system assumes that it is being run from a subst'ed drive

pointed at the root of your SDK and that EPOCROOT is \. For example if

you are using S60 SDK 3.0, you can create a substed drive T: with the

command:

  subst t: C:\Symbian\9.1\S60_3rd_MR

- Make sure that Python 2.5.4 is in your PATH.

COMPILING USING setup.py

===========================

Configuring

------------

usage:python setup.py configure [options]

For more information about options check the command line help

ex: python setup.py configure --help

If any command line option is absent default values will be used for that.

- To configure the source for a particular SDK, run

  setup.py configure -s <your SDK> [options]

Compiling

----------

To compile for the device and the emulator, run:

  setup.py build

build_device and build_emu builds just for the device or the emulator.

Note: Unless you specify a version tag, setup.py will automatically assign a

final tag to it. You can specify the version tag using the configure command.

  setup.py configure --version-tag <version_tag>

For general instructions on porting existing extension modules to PyS60 1.9.x and

S60 editions, refer the doc http://pys60.garage.maemo.org/doc/s60/extendandembed.html 

Signing

-------

All SIS packages installed to a S60 device must be signed, and so

the setup.py command bdist_sis will automatically sign the created SIS packages

with the given key.

You need to pass the following build parameters to configure for bdist_sis:

usage:python setup.py bdist_sis [options]

options:

  -h, --help               Show this help message and exit

  --keydir=KEYDIR          specify key path. Default is '..\keys'

  -k KEY, --key=KEY        specify key name to use,

                           Default: None - packages are left unsigned

All built SIS files are signed with the same key.

Capabilities

------------

The capabilities assigned to different packages are given as build

parameters. The default set of capabilities in the setup.py is the 3.2 device 

capability set which is available using a self-signed certificate. This set is:

  LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment Location  

If you are using a self-signed certificate, the maximum set of

capabilities is:

3.0 devices:

  LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment

3.2 and 5.0 devices:

  LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment Location

If you have a devcert with higher capabilities or if you want to build

a self-signed package with only user-grantable capabilities, then you

can redefine this with the following build parameters:

DLL_CAPABILITIES: the capabilities assigned to the DLL's contained in the Python runtime package.

Examples:

  setup.py configure -s 30armv5 -k selfsigned --caps "LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment"

This could be also done using "setcaps" option even without recompiling the source

Example:

  setup.py setcaps --caps "LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment"

INSTALLING TO THE EMULATOR

==========================

Building the code for the emulator is sufficient and no further installation

is needed.

INSTALLING TO THE DEVICE

========================

To package the software into a SIS package for installation on your device, run

  setup.py bdist_sis

This will create a SIS package of the compiled code. The packages are signed

with the key and certificate given in the configure phase. Alternatively, you

may specify the key and key directory parameters on the bdist_sis command line.

NOTE: This command packages the code as it exists on disk at the time of its

execution. It does not recompile anything automatically. Use PyS60 Application

packager tool for packaging PyS60 applications

ONE BUTTON BUILD

================

To invoke the steps configure, build, bdisk_sdk and bdist_sis in one step, run:

  setup.py obb <your SDK> [<other configure parameters>]

ONE COMMAND TESTING

===================

TO run test cases automatically on emulator with one command, run:

   python setup.py test [options]

Runs test cases automatically on emulator. This calls regrtest.py internally.

Pre-requisite: source code must be configured and built for emulator.

Group of test cases in a single interpreter instance:

   Use "--use-testsets-cfg" option to run a group of test cases in a single

interpreter instance. The test case names needs to be added in

testapp\src\testsets.cfg file using "<<<<TestCase<<<<" and ">>>>TestCase>>>>"

to separate each set of test cases.

   Example: testsets.cfg

   <<<<TestCase<<<<

   test_cpickle

   test_cmath

   test_math

   >>>>TestCase>>>>

   <<<<TestCase<<<<

   test_StringIO

   >>>>TestCase>>>>

   python setup.py test --use-testsets-cfg testsets.cfg

Execute N tests at a time:

   Use "--testset-size" option to look through the Lib/test directory, find all

test cases and automatically run N test cases at a time.

    Example:

    setup.py test --testset-size 10

Pass options to regrtest.py:

    Supports all the options of regrtest.py. For more information execute

    setup.py test -h

If any command line option is absent default values will be used for that.

Note:

-->This command builds the test code

-->It starts up emulator and executes all the test cases that are in newcore\Lib\test

-->Puts output results in data\python\test\regrtest_emu.log.

NOTE: PyS60 source code must be built for emulator before running this command

ADDING NEW MODULES

==================

To add a new module to the distribution, you need to do the following:

- create a directory for it under ext

- take a look at one of the existing extensions to see the required

files. The inbox module is a good example. The elemlist module under extras

directory also is a good starting point.

- Use one of the following command for building just this module.

    - setup.py build <ext-module>         : Build for both emu and device

    - setup.py build_emu <ext-module>     : Build just for emu

    - setup.py build_device <ext-module>  : Build just for device

For S60 3.0 extension porting, please refer the doc http://pys60.garage.maemo.org/doc/s60/extendandembed.html

DOCUMENTATION

=============

For building the documentation and the needed prerequisites, refer to README in

src\newcore\Doc.