--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/README.txt Tue Feb 16 10:07:05 2010 +0530
@@ -0,0 +1,321 @@
+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.