diff -r 000000000000 -r ca70ae20a155 src/README.txt --- /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 [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 + +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 [] + + +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>>>>" +to separate each set of test cases. + + Example: testsets.cfg + <<<>>>TestCase>>>> + <<<>>>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 : Build for both emu and device + - setup.py build_emu : Build just for emu + - setup.py build_device : 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.