|
1 PYTHON FOR S60 |
|
2 ============== |
|
3 |
|
4 Python(r) for S60 is a scripting language environment for the S60 smartphone |
|
5 platform, based on Python 2.5.4. |
|
6 |
|
7 Note: This README instructs how you can build Python for S60. If you are only |
|
8 developing Python scripts for a Nokia device you can use the existing binary |
|
9 builds for development - in this case building PyS60 from source code is not |
|
10 needed. |
|
11 |
|
12 |
|
13 TRADEMARKS |
|
14 ========== |
|
15 |
|
16 Python and the Python logo are registered trademarks of the Python |
|
17 Software Foundation. |
|
18 |
|
19 |
|
20 LICENSING |
|
21 ========= |
|
22 |
|
23 Copyright (c) 2005-2009 Nokia Corporation. This is Python for S60 created by |
|
24 Nokia Corporation. The original software, including modifications of Nokia |
|
25 Corporation therein, is licensed under the applicable license(s) for |
|
26 Python 2.5.4, unless specifically indicated otherwise in the relevant source |
|
27 code file. |
|
28 |
|
29 See http://www.apache.org/licenses/LICENSE-2.0 |
|
30 and http://www.python.org/2.5.4/license.html |
|
31 |
|
32 |
|
33 CHANGES TO PYTHON 2.5.4 |
|
34 ======================= |
|
35 |
|
36 See the file changes.txt for a list of changes to Python 2.5.4. |
|
37 |
|
38 |
|
39 REQUIREMENTS |
|
40 ============ |
|
41 |
|
42 To build PyS60, you need: |
|
43 |
|
44 - Python 2.5.x |
|
45 - Open C/C++ Plug-ins. |
|
46 Refer the release notes for the exact version of plug-ins compatible with |
|
47 this release. |
|
48 - S60 C++ SDK. Currently supported versions for building are: |
|
49 - S60 SDK 3.0, S60 SDK 3.2 and S60 SDK 5.0 |
|
50 - To patch the SDK's headers you need the GNU patch utility. |
|
51 |
|
52 Adding support for other SDK versions is probably not very |
|
53 difficult. See the beginning of setup.py for the configuration |
|
54 parameters required. |
|
55 |
|
56 |
|
57 Requirements for extensions |
|
58 ============================ |
|
59 |
|
60 sensor |
|
61 ------ |
|
62 |
|
63 The Sensor API plug-in from Forum Nokia is needed for building sensor module on |
|
64 all S60 3rd Edition SDKs. On S60 5th Edition Sdk, the module can be built |
|
65 without any plug-in |
|
66 |
|
67 "Sensor Plug-in for S60 3rd Edition SDK for Symbian OS, for C++, MR, for Nokia |
|
68 5500 Sport" |
|
69 |
|
70 Available from: |
|
71 http://www.forum.nokia.com/info/sw.nokia.com/id/4284ae69-d37a-4319-bdf0-d4acdab39700/Sensor_plugin_S60_3rd_ed.exe.html |
|
72 |
|
73 "Sensor API Plug-in for S60 3rd Edition SDK for Symbian OS, Feature Pack 2", MR, |
|
74 for Nokia N85, N96, E75, 6720, 6210, 6710 and E55 |
|
75 |
|
76 Available from: |
|
77 http://www.forum.nokia.com/info/sw.nokia.com/id/8059e8ae-8c22-4684-be6b-d40d443d7efc/Sensor_API_Plug_in_S60_3rd_FP2.html |
|
78 |
|
79 The sensor extension has been tested in Nokia N95 and 5800 XpressMusic. The |
|
80 sensor module cannot be loaded on the emulator because of the limitations in the |
|
81 sensor plug-in. |
|
82 |
|
83 There are 2 sensor modules available |
|
84 a. src\ext\amaretto\sensor - for S60 3rd Edition SDK and S60 3rd Edition SDK FP1 |
|
85 b. src\ext\sensorfw - for S60 3rd Edition SDK FP2 and S60 5th Edition SDK |
|
86 |
|
87 You can compile the code without the sensor module by removing the respective |
|
88 mmp file entry from \src\newcore\Symbian\group\bld.inf.in.template. |
|
89 |
|
90 Extension |
|
91 --------- |
|
92 |
|
93 The C++ extensions plug-ins for S60 3rd Edition SDKs extend the features of an |
|
94 S60 platform SDK, offering improved device emulation and support for additional |
|
95 functionality included in shipped devices or specific to a certain device. |
|
96 As a result, the plug-ins enable a greater range of applications to be built and |
|
97 tested using the S60 device emulator supplied in the SDK. The Extension plug-in |
|
98 is available at this URL: |
|
99 |
|
100 http://www.forum.nokia.com/info/sw.nokia.com/id/48a93bd5-028a-4b3e-a0b1-148ff203b2b3/Extensions_plugin_S60_3rd_ed.html |
|
101 |
|
102 |
|
103 FIXING THE S60 3rd edition HEADERS |
|
104 ================================== |
|
105 |
|
106 There are some bugs in the shipped SDK headers. To fix these, you must |
|
107 apply the patch pys60-fix-3rded-sdk.diff. To do this, you will need |
|
108 the GNU patch utility. |
|
109 |
|
110 You can patch the headers by going to the \epoc32\include directory on |
|
111 your SDK drive and giving the command: |
|
112 |
|
113 patch -p1 < (path to the diff file)\src\misc\pys60-fix-3rded-sdk.diff |
|
114 |
|
115 You need to do this only once. |
|
116 |
|
117 |
|
118 FIXING THE x86 compiler build issues |
|
119 ==================================== |
|
120 Python source code doesn't get compiled using the latest x86 compiler |
|
121 (build > 471). Work around would be is to download x86 compiler of build 471 |
|
122 from the link "http://tools.ext.nokia.com/download/beta_build.php" and extract |
|
123 the same to epoc32 folder. |
|
124 |
|
125 |
|
126 COMPILING |
|
127 ========= |
|
128 |
|
129 - The build system assumes that it is being run from a subst'ed drive |
|
130 pointed at the root of your SDK and that EPOCROOT is \. For example if |
|
131 you are using S60 SDK 3.0, you can create a substed drive T: with the |
|
132 command: |
|
133 |
|
134 subst t: C:\Symbian\9.1\S60_3rd_MR |
|
135 |
|
136 - Make sure that Python 2.5.4 is in your PATH. |
|
137 |
|
138 |
|
139 COMPILING USING setup.py |
|
140 =========================== |
|
141 |
|
142 Configuring |
|
143 ------------ |
|
144 usage:python setup.py configure [options] |
|
145 For more information about options check the command line help |
|
146 ex: python setup.py configure --help |
|
147 |
|
148 If any command line option is absent default values will be used for that. |
|
149 - To configure the source for a particular SDK, run |
|
150 |
|
151 setup.py configure -s <your SDK> [options] |
|
152 |
|
153 Compiling |
|
154 ---------- |
|
155 To compile for the device and the emulator, run: |
|
156 |
|
157 setup.py build |
|
158 |
|
159 build_device and build_emu builds just for the device or the emulator. |
|
160 |
|
161 Note: Unless you specify a version tag, setup.py will automatically assign a |
|
162 final tag to it. You can specify the version tag using the configure command. |
|
163 |
|
164 setup.py configure --version-tag <version_tag> |
|
165 |
|
166 For general instructions on porting existing extension modules to PyS60 1.9.x and |
|
167 S60 editions, refer the doc http://pys60.garage.maemo.org/doc/s60/extendandembed.html |
|
168 |
|
169 Signing |
|
170 ------- |
|
171 |
|
172 All SIS packages installed to a S60 device must be signed, and so |
|
173 the setup.py command bdist_sis will automatically sign the created SIS packages |
|
174 with the given key. |
|
175 |
|
176 You need to pass the following build parameters to configure for bdist_sis: |
|
177 |
|
178 usage:python setup.py bdist_sis [options] |
|
179 |
|
180 options: |
|
181 -h, --help Show this help message and exit |
|
182 --keydir=KEYDIR specify key path. Default is '..\keys' |
|
183 -k KEY, --key=KEY specify key name to use, |
|
184 Default: None - packages are left unsigned |
|
185 |
|
186 All built SIS files are signed with the same key. |
|
187 |
|
188 Capabilities |
|
189 ------------ |
|
190 |
|
191 The capabilities assigned to different packages are given as build |
|
192 parameters. The default set of capabilities in the setup.py is the 3.2 device |
|
193 capability set which is available using a self-signed certificate. This set is: |
|
194 |
|
195 LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment Location |
|
196 |
|
197 If you are using a self-signed certificate, the maximum set of |
|
198 capabilities is: |
|
199 3.0 devices: |
|
200 LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment |
|
201 3.2 and 5.0 devices: |
|
202 LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment Location |
|
203 |
|
204 If you have a devcert with higher capabilities or if you want to build |
|
205 a self-signed package with only user-grantable capabilities, then you |
|
206 can redefine this with the following build parameters: |
|
207 |
|
208 DLL_CAPABILITIES: the capabilities assigned to the DLL's contained in the Python runtime package. |
|
209 Examples: |
|
210 |
|
211 setup.py configure -s 30armv5 -k selfsigned --caps "LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment" |
|
212 |
|
213 This could be also done using "setcaps" option even without recompiling the source |
|
214 Example: |
|
215 |
|
216 setup.py setcaps --caps "LocalServices NetworkServices ReadUserData WriteUserData UserEnvironment" |
|
217 |
|
218 |
|
219 INSTALLING TO THE EMULATOR |
|
220 ========================== |
|
221 |
|
222 Building the code for the emulator is sufficient and no further installation |
|
223 is needed. |
|
224 |
|
225 INSTALLING TO THE DEVICE |
|
226 ======================== |
|
227 |
|
228 To package the software into a SIS package for installation on your device, run |
|
229 |
|
230 setup.py bdist_sis |
|
231 |
|
232 This will create a SIS package of the compiled code. The packages are signed |
|
233 with the key and certificate given in the configure phase. Alternatively, you |
|
234 may specify the key and key directory parameters on the bdist_sis command line. |
|
235 |
|
236 NOTE: This command packages the code as it exists on disk at the time of its |
|
237 execution. It does not recompile anything automatically. Use PyS60 Application |
|
238 packager tool for packaging PyS60 applications |
|
239 |
|
240 |
|
241 ONE BUTTON BUILD |
|
242 ================ |
|
243 |
|
244 To invoke the steps configure, build, bdisk_sdk and bdist_sis in one step, run: |
|
245 |
|
246 setup.py obb <your SDK> [<other configure parameters>] |
|
247 |
|
248 |
|
249 ONE COMMAND TESTING |
|
250 =================== |
|
251 |
|
252 TO run test cases automatically on emulator with one command, run: |
|
253 |
|
254 python setup.py test [options] |
|
255 |
|
256 Runs test cases automatically on emulator. This calls regrtest.py internally. |
|
257 Pre-requisite: source code must be configured and built for emulator. |
|
258 |
|
259 Group of test cases in a single interpreter instance: |
|
260 Use "--use-testsets-cfg" option to run a group of test cases in a single |
|
261 interpreter instance. The test case names needs to be added in |
|
262 testapp\src\testsets.cfg file using "<<<<TestCase<<<<" and ">>>>TestCase>>>>" |
|
263 to separate each set of test cases. |
|
264 |
|
265 Example: testsets.cfg |
|
266 <<<<TestCase<<<< |
|
267 test_cpickle |
|
268 test_cmath |
|
269 test_math |
|
270 >>>>TestCase>>>> |
|
271 <<<<TestCase<<<< |
|
272 test_StringIO |
|
273 >>>>TestCase>>>> |
|
274 |
|
275 python setup.py test --use-testsets-cfg testsets.cfg |
|
276 |
|
277 Execute N tests at a time: |
|
278 Use "--testset-size" option to look through the Lib/test directory, find all |
|
279 test cases and automatically run N test cases at a time. |
|
280 |
|
281 Example: |
|
282 setup.py test --testset-size 10 |
|
283 |
|
284 Pass options to regrtest.py: |
|
285 Supports all the options of regrtest.py. For more information execute |
|
286 setup.py test -h |
|
287 |
|
288 If any command line option is absent default values will be used for that. |
|
289 |
|
290 Note: |
|
291 -->This command builds the test code |
|
292 -->It starts up emulator and executes all the test cases that are in newcore\Lib\test |
|
293 -->Puts output results in data\python\test\regrtest_emu.log. |
|
294 |
|
295 NOTE: PyS60 source code must be built for emulator before running this command |
|
296 |
|
297 |
|
298 ADDING NEW MODULES |
|
299 ================== |
|
300 |
|
301 To add a new module to the distribution, you need to do the following: |
|
302 |
|
303 - create a directory for it under ext |
|
304 |
|
305 - take a look at one of the existing extensions to see the required |
|
306 files. The inbox module is a good example. The elemlist module under extras |
|
307 directory also is a good starting point. |
|
308 |
|
309 - Use one of the following command for building just this module. |
|
310 - setup.py build <ext-module> : Build for both emu and device |
|
311 - setup.py build_emu <ext-module> : Build just for emu |
|
312 - setup.py build_device <ext-module> : Build just for device |
|
313 |
|
314 For S60 3.0 extension porting, please refer the doc http://pys60.garage.maemo.org/doc/s60/extendandembed.html |
|
315 |
|
316 |
|
317 DOCUMENTATION |
|
318 ============= |
|
319 |
|
320 For building the documentation and the needed prerequisites, refer to README in |
|
321 src\newcore\Doc. |