PyS60 extensions creation using Carbide

From OpenSource

Jump to: navigation, search

Contents

[edit] Preface

This tutorial will tell how to build and edit PyS60 native extension using Carbide C++. The tutorial applies for Series 60 3.0 and forward: older SDKs require WINS toolchain (Microsoft Visual Studio) instead free WINSCW (Nokia's own compiler) toolchain for building emulator targets. Text here is largely based the [tutorial] written by Simo Salminen.

All files, including Carbide C++ project files, are downloadable at the Google code project page.

Python extensions are native modules which provide Python bindings to its native environment.

Carbide C++ is Nokia's IDE build on Eclipse technology. Carbide C++ Express is free and allows one to build emulation and device target native code.

This tutorial will tell how to build and structure native extensions. It will not go to the details of Symbian and Python programming.

[edit] Introduction

We will build a module called uikludges 2.0. This module will provide additional Series 60 UI components for Python besides those available in Nokia's appuifw module. The sample extension source code is available as ZIP file. UIKludges 2.0 module is licensed under BSD license.

The module will provide enhanced version of some appuifw functions. Some new functions are introduced. Since we are building on appuifw code base, some code is directly taken from appuifw source code.

[edit] Extension structure

[edit] Files

  • bld.inf Define components (mmp files) and target platforms (Windows, device) which are build
  • uikludges.mmp Components' C++ source code files, UID, needed capabilities
  • uikludges.rss Symbian resource definitions for the project
  • uikludges.cpp C++ source code for the extensios native bindings (will be compiled to _uikludges.pyd DLL file)
  • uikludges.py Python module which wraps extension providing the decoration for the cake
  • uikludges.pkg Build instructions for SIS files
  • _build Folder where files going to SIS distribution are placed
  • uikludges.sis Symbian application distribution file
  • Makefile Makefile recipes for performing common tasks, like generating API documentation, which are not directly available in Carbide IDE

There also exist Eclipse project files and misc. resource files which are taken from the orignal Python for Series 60 distribution.

[edit] Build process

[edit] Requirements

Install the C++ SDK typical installation. The PyS60 SDK is extracted from the .zip file over the C++ SDK directory structure. You can verify that the installation worked by starting the emulator from Window start menu: Python interactive shell should be in Installat. subfolder on the emulator menu.

[edit] Building for emulator

You need to have Python SDK for emulator to be installed before you can test files. Python SDK will create EPOCROOT\winscw\c\Python folder on your virtual emulator mass storage.

Click build icon (Hammer) to build the emulator target. Output will appear in $EPOCROOT\release\winscw\udeb. In my case, the location was C:\Symbian\9.2\S60_3rd_FP1\Epoc32\release\winscw\udeb

Close the emulator if it's running. Windows reserves file handles otherwise and files cannot be overwritten.

Copy .pyd file from udeb folder to C:\Symbian\9.2\S60_3rd_FP1\Epoc32\winscw\c\sys\bin.

Copy Python .py wrapper modules from workspace to C:\Symbian\9.2\S60_3rd_FP1\Epoc32\winscw\c\Python. This can be most easily done by holding CTRL and dragging files from Eclipse navigator to open Windows Explorer window. Leave windows open for background.

Restart the emulator in order to get new DLL version loaded.

Start Python shell in menu. Run your module self test code, in our case uikludges.py.

[edit] Building for device

Click Build button (hammer icon) and choose GCCE urel target.

This build will produce file C:\Symbian\9.2\S60_3rd_FP1\epoc32\release\gcce\urel\_uikludges.pyd.

Now go to the project folder in command shell.

The next step is create a temporary folder where all native files going to SIS distribution are placed. Then they are sis'sified with makesis command from Symbian SDK. To see internals of the process, check the Makefile.

In command shell, go to the project folder. Set your EPOCROOT variable point to the current Symbian SDK. E.g. 

 set EPOCROOT=\Symbian\9.2\S60_3rd_FP1\

Then run: 

 make sis

A new file called uikludges.SIS should appear in the project folder.

Currently, S60 loads .pyd extension only from C:\sys\bin folder which is a protected folder in the device. The only way to get new files there is to run them through SIS installer. There exists a silent installer API, but no one has yet automatized Python extension installing.

[edit] UID and signing

Before you can install the DLL or SIS file to your phone, it must be signed.

Signing is very challenging and manual labour sensitive task. Why the fuck wont my SIS file install is a good site highlighting some of the problems.

PYD files are DLL files and DLL files appear as executables from Symbian OS. Thus, they need to have

  • UID: unique identifier. choose Hex number from 0x10000000 upwards
  • Capabilities: flags which device capabilities DLL is allowed to access. EXE loading DLL capabilities must be less than the loader EXE's capabilities.
  • Certicication: you need to sign all sis files before they can be put on the device

[edit] Settings UID

  • Go to symbiansigned.com, register an account and demand protected UIDs

Then edit uikludges.mmp: 

TARGETTYPE	dll
UID 0x20012AE2 0x20012AE3
TARGET		_uikludges.pyd
TARGETPATH	\sys\bin

(you can also do this in Carbide GUI, but I couldn't attach screenshot to this Wiki)

[edit] Development signing

I suggest you to use Ensymble for the task. Below is a makefile example how to sign. Be careful with tabs and spaces in Makefile! 



PYTHON=c:\python25\python
ENSYMBLE=c:\ensymble\ensymble.py
CERT=${FOO}\certificates\Foo.cer
PRIV_KEY=${FOO}\certificates\ACSCert.pfx.key
SIGN_PASS=notused

sign:
   ${PYTHON} $(ENSYMBLE) simplesis --uid=${UID} --verbose --cert=${CERT} --privkey=${PRIV_KEY} --passphrase=${SIGN_PASS} _build $(DLLNAME).SIS

[edit] Public signing

When you want to distribute your extension with a commercial PyS60 application, you need to include .PYD file as is in the installation SIS. Do not embed DLL SIS to the main SIS, since certication parties cannot certificate embedded SIS files.

[edit] Debugging

I recommend you to debug in the emulator as much as possible, since every target code change requires you to go through the manual SIS installation process. On the emulator, you just can copy new .PYD files from the output folder to the emulator folder (see Building for emulator for the details).

For more information how to debug Python code on S60, see this tutorial.

Getting state information from the native extension code is difficult. Looks like Carbide C++ breakpoints are not effective in the emulator (needs confirmation from Nokia), so using the IDE for debugging native code is not possible.

You can output from C++ using Symbian file logger called RFileLogger.

  • Enable macro __DO_LOGGING__ in uikludges.mmp
  • Include logger.h and see its content how to set-up the logger.
  • Create folder c:\logs on your phone. The log files will be placed here.
  • Use macro LOG to output from CPP. Note that output strings must be Symbian unicode strings. 
  LOG(_L("Switch"))

[edit] API documentation

A recommended way to document API of your native extension is to create a stub functions in .py file and create comment documentation for them. Later you can convert this to a nice HTML documetation automatically and you do not need to maintain a seperate documetation.

Example code below. 

#
# Since the name of the native module is _uikludges, we import it as an internal module
#
if e32.s60_version_info>=(3,0):
	# Symbian 9.0 way to import things
    import imp
    _uikludges=imp.load_dynamic('_uikludges', 'c:\\sys\\bin\\_uikludges.pyd')    
else:
	# Old way
    import _uikludges


# 
# An example function which wraps native _uikludges.set_softkey_visiblity function 
# and provides parameter defaults and documentation for it.
#
def set_softkey_visibility(command, visibility):
	""" 
	Hides or shows soft key label.
	
	Softkey labels are defined per command. So, you are not changing
	the softkey itself, but command it presents.
	
	@param command: One of EAknSoftKey* constants in uikludges.py
	@param visibility: True for visible, False for hidden
		
	@type command: int
	@type visibility: boolean
	
	@raise SymbianError: if native code execution fails
	@return: None
	"""
	_uikludges.set_softkey_visibility(command, visibility)

[edit] Common errors 

 SystemError: _PyImport_ FixupExtension: module miso2 not loaded

See this thread

Retrieved from "http://wiki.opensource.nokia.com/projects/PyS60_extensions_creation_using_Carbide"
Personal tools
MediaWiki Resources