Friday fun with SQL

February 19, 2010

This week Symbian released the first PDK built from 100% open source code (release notes). Why not try out Symbian^3 Platform Release v3.0.g?

Here’s some database humour for Friday afternoon…

More posts next week – including news about our forthcoming Symbian Press book on Symbian SQL.

Help us with GCC-E compilation errors

February 12, 2010

As Mark Wilcox posted on the Symbian blog in It’s Open, So Now What? and mentioned in the theregister.co.uk today we can’t build all of the Symbian packages with the open source GCC-E compiler yet.

We have a couple of GCC-E bugs in persistentdata: bug 1767 and bug 1795.

If you’d like to help, have a look at the Compiler Compatibility page for more details.

Getting started

February 12, 2010

Want to get started developing on Symbian?

These steps explain what you need to do to set-up a development environment for the Symbian platform.

1. Install Perl
To build the code you need ActivePerl, a standard distribution of the Perl language. The Symbian Foundation recommend Perl 5.8.9. Further information in Kits Q&A.

2. Install Python
Symbian Build System v2 (SBSv2) needs ActiveState Python 2.5.1 or later installed. This is a standard distribution of the Python language. Symbian Foundation suggests Python 2.5.4, but I installed ActivePython 2.6.4.10 as the latest version of SBSv2 didn’t find python26.dll otherwise. Further information in Kits Q&A.

3. Install Java
Download the Java SE Development Kit from java.sun.com. I used JDK 6 Update 18

4. Install 7-zip
The Product Development Kit is distributed as a collection of zip files. You should install 7-zip from www.7-zip.org to unpack them because other zip tools have been known to have problems with the number of files in the archives.

5. Get a Product Development Kit
The Product Development Kit (PDK) contains the binaries, tools and source code you need to develop code and build products. The latest PDK is Symbian^3 Platform Release v3.0.f.

You can download the zip files using your browser and unzip them using 7-Zip, or better still use the downloadkit.py utility as described in How to Download a PDK. Unzip everything to a new drive, created with the subst command.

6. Install PDT 1.5
The Product Development Toolkit (PDT) contains a complete set of PC-side tools (such as Carbide.c++) and documentation. I installed the Product Development Toolkit (PDT) v1.5 and then the PDK overlay to install the tools to the epoc32 tree.

7. Install the GCC compiler
Install Sourcery G++ Lite 2009q3-63 to build for ARM hardware using the free GCC toolchain. When installing, do not use the default installation path. You need to install it without any spaces in the path as described in The GCCE toolchain initiative

Download the update needed to SBSv2 from the PDK download page (GCC Support – Raptor 2.12.1) and unzip it over the Raptor directory in your PDT install.

You might need to set-up some environment variables to get everything running. There’s good advice on developer.symbian.org if you do a search. I had to add:

set SBS_GCCE432BIN=C:/Apps/CodeSourcery/GCCE/bin

8. Install Mercurial
Mercurial is the SCM tool used by the Symbian Foundation. Install it from the Mercurial site and follow the guidance in Mercurial Quick Start to configure the tool.

9. Check your development environment
Follow the instructions on developer.symbian.org to test your development environment. The output will look something like this:

Z:\>perl -version

This is perl, v5.8.9 built for MSWin32-x86-multi-thread
(with 12 registered patches, see perl -V for more detail)

Z:\>python -V
Python 2.5.4

Z:\>java -version
java version “1.6.0_18”
Java(TM) SE Runtime Environment (build 1.6.0_18-b07)
Java HotSpot(TM) Client VM (build 16.0-b13, mixed mode, sharing)

Z:\>mwccsym2.exe -version
Nokia Codewarrior C/C++ Compiler for Windows/x86.
Copyright (c) 2008, Nokia Corporation
All rights reserved.
Version 3.2.5 build 473 (Build 473)
Runtime Built: Apr 30 2008 14:33:37

Z:\>arm-none-symbianelf-gcc.exe -v
Using built-in specs.
Target: arm-none-symbianelf
Configured with: ….
Thread model: single
gcc version 4.4.1 (Sourcery G++ Lite 2009q3-63)

Start the emulator with \epoc32\release\winscw\udeb\epoc.exe

10. Get the code, and make changes
Get the latest persistentdata MCL code using Mercurial:

Z:\>hg clone http://developer.symbian.org/oss/MCL/sf/os/persistentdata/
destination directory: persistentdata
requesting all changes
adding changesets
adding manifests
adding file changes
added 5 changesets with 5738 changes to 5727 files (+1 heads)
updating to branch default
5721 files updated, 0 files merged, 0 files removed, 0 files unresolved

Everything you need to know about building the code, working with Mercurial and making your first change is available from the Symbian Platform Contributors category on developer.symbian.org. If you get stuck, use the Developer Forums. We’ll be happy to help.

Summary
This post describes how you can install and configure a Symbian development environment for development. It might seem like a lot of steps to get set-up, but most of the tools are a one-off installation and once installed can be used for every new release of the platform.

There is a nice graphical representation of the installation process on the Symbian developer site.

Symbian is open: Join our package team today!

February 5, 2010

Symbian is open

The entire Symbian platform is now available under the terms of the open source Eclipse Public License.

This is fantastic news, and I’m excited about what it means for the future of the package and the Symbian platform. Next week I will write about how you can get started with the persistentdata code and suggest some activities you can help us with.

You can find more information in yesterday’s announcement on the Symbian blog and the official press release.

Open sourcing the Symbian platform is a major achievement. It was reported in the mainstream and technical press. Several examples below:


Image Project 365 #303: 301009 Blink And You’ll Miss It! by comedy_nose used under a Creative Commons Attribution licence.

Persistentdata for beginners series review

February 4, 2010


Image created with wordle.net.

I have introduced the Persistent Data Services (persistentdata) package APIs over the last five weeks.

Persistent Storage collection

  • Central Repository, the settings store
  • DBMS, the first database engine for Symbian
  • Symbian SQL, the client-server database incorporating SQLite
  • SQLite3 API, the standard SQLite C API
  • Store, the essential classes for data persistence

Logging Services

  • Event Logger, the database of recent calls and other events
  • File Logger, a file logger for debugging purposes
  • RFile Logger, the file logger for Test Execute Framework

Feature Management

  • Feature Manager, the API to query the presence or absence of hardware and software features
  • Feature Registry, a deprecated API to query feature status

Trace Services

  • Comms Debug Utility, a file and serial port logger for debugging purposes
  • Trace Framework, the trace API replaced by Open System Trace framework
  • UTrace, a deprecated trace API

Links to each post in the series are available in the first post in the series.

What did you think about the series? What do you want to know more about? What was most or least useful?

Please leave a comment to share your opinion.

Persistentdata for beginners: UTrace

February 3, 2010

UTrace is a deprecated platform API for system-wide logging of trace messages. It is only included in the Symbian^2 release. We removed it from the platform in Symbian^3.

The deprecated UTrace API is defined in utrace.h. It was replaced by e32utrace.h, published by tracefw, which will be soon replaced by the Open System Trace framework.

I recommend that developers who need to instrument their code look at File Logger, CDU or BTrace until the Open System Trace framework is available.

Further resources

Update February 4, 2010:
One of my colleagues from the Nokia Dynamic Analysis Tools team recommends that the BTrace API is used for instrumenting code until Open System Trace is available as it will fit in best with OSTv2. The team is working hard to finish the OST contribution, so hopefully we won’t need to wait long.

Persistentdata for beginners: Trace Framework

February 3, 2010

The software contained in the Trace Framework component is being refactored into a comprehensive trace framework suitable for instrumenting all Symbian based software; the Open System Trace framework.

The Open System Trace API specification is published on the Symbian developer site, and the header file (opensystemtrace.h) can be seen in the OSS Source Browser under /sf/os/kernelhwsrv/kernel/eka/include/

Nokia is building the OST framework on top of the BTrace kernel service from the Kernel & Hardware Services package. A full end-to-end solution will be provided – including an API to instrument source code with trace points, software to configure trace filters, software to capture and output trace information and off-device analysis tools.

The platform API provided by Tracefw now (e32utrace.h) is not part of the Open System Trace solution. It will be deprecated after the OST solution is fully available.

Further resources

  • Mark Welsh’s architecture presentation to the Tools Special Interest Group describes Nokia’s proposed Open System Trace contribution (see slides 9 & 10)

Persistentdata for beginners: Comms Debug Utility

February 2, 2010

Comms Debug Utility (CDU) provides efficient and reliable logging of messages to a log file or serial port.

It was developed as an improved version of file logger but due to the risk of breaking existing flogger clients it was delivered as a new component. The original designers named the component “Comms Debug Utility” to distinguish it from file logger and to highlight its intended usage as an internal API for the Symbian Software Networking team. In common with file logger, the API was used by code in other packages and it is effectively a public API now.

CDU supports a several destinations for log messages: log file, RDebug, serial port 1, serial port 2, and the Windows debug port (for the emulator). You can configure where the log messages are written to and which components are enabled in the commsdbg.ini file. The CDU server searches for this file on start-up in the \logs and \resource directories. When logging to file, the output is written to C:\logs\log.txt.

A recent submission introduced a migration path to the forthcoming Open System Trace framework. You can now specify that the CDU log is written using OSTv2 format to enable interleaved traces to continue to be captured whilst packages move to OST.

Comms Debug Utility API

The API is defined in comms-infras/commsdebugutility.h. It defines the same class as file logger (RFileLogger) plus a set of macros to simplify the addition and removal of logging from release builds. Client code should link to comsdbgutil.lib.

CDU is mostly source compatible with file logger. All file logger APIs are supported, but there are behaviour changes which may need source changes to fix. For example, the logging directory and log file name could be up to 100 characters in file logger but CDU has a maximum of 16 characters and will truncate longer strings.

CDU is not data compatible with file logger. It writes the log to a single file only, whereas file logger writes to several log files. The advantage of writing to a single destination is that log messages from different components are interleaved (i.e. showing different layers of a communications stack) so it is easier to diagnose issues.

CommsDebugUtility is not binary compatible with file logger as the RFileLogger object has changed in size and no longer derives from RSessionBase.

Further resources

Coming up next…
Trace Framework and UTrace will be the last components in the Persistentdata for beginners series.

Persistentdata for beginners: Feature Registry

February 1, 2010

Feature Registry is a deprecated component that provides similar functionality to Feature Manager. It provides APIs to query at run-time which features are present on a device.

Feature Manager has taken the place of Feature Registry in the Symbian platform. The Feature Registry API is deprecated and the current implementation is a wrapper around Feature Manager. There is no reason for newly written code to use the Feature Registry API.

Feature Registry API

Feature Registry clients should link to featreg.lib. The purpose of each class is summarised below:

API Purpose
RFeatureRegistry Deprecated API to query if features are supported on the device. Use Feature Manager instead
RFeatureRegistryNotify Deprecated interface for notification of changes in the Feature Registry. Use Feature Manager instead

Further resources

Coming up next…

The next part of the Persistentdata for beginners series will cover Comms Debug Utility. Originally designed as a better version of file logger it is the main logging tool for Comms Framework, Cellular Baseband Services, Networking Services and many other packages.

Persistentdata for beginners: Feature Manager

February 1, 2010

Feature Manager provides APIs to query and configure the status of hardware and software features.

It controls a set of feature flags associated with the features (functional abilities) of a mobile device. Features include but are not limited to: Bluetooth, DRM, printing, and vibration. Each functional ability managed may have a feature flag or set of flags associated with that ability.

A feature flag is represented by three 32-bit values:

  • Feature UID: A UID that uniquely identifies the feature
  • Status flags: Feature flag properties (e.g. feature is supported)
  • Feature data: Additional feature information related to the feature

The initial state of the feature flags is defined by the features.dat file or feature information plug-ins stored in the ROM image. The Build package provides perl tools to generate the features.dat file from XML input files. Modified and added feature information is stored in the Feature Manager server’s private directory on the System drive. When the Feature Manager server starts up, it reads all the available feature information from these sources and holds that information in RAM.

Applications can query the feature manager to determine the capabilities of the device they are running on. For example, a game that supports vibration effects can determine whether the device supports a vibration capability by querying the Feature Manager.

Feature Manager API

Feature manager clients should link to featdiscovery.lib to use the CFeatureDiscovery public API. To use the other platform classes you need to link to featmgr.lib.

The purpose of each class is summarised below:

API Purpose
CFeatureDiscovery
(featdiscovery.h)
Provides methods to query which features are supported
TFeatureSet
(featdiscovery.h)
A collection of features used to query the status of multiple features in a single request
FeatureManager
(featmgr.h)
Deprecated API for querying whether features are supported; use CFeatureDiscovery instead
CFeatureInfoPlugin
(featureinfoplugin.h)
Base class for feature information plug-ins
MFeatureInfoPluginCallback
(featureinfoplugin.h)
Interface implemented by feature manager server to receive responses from feature information plug-ins
FeatureInfoCommand::
TEnhancedFeatureInfo
(featureinfoplugin.h)
Data structure used to pass data with ELoadEnhancedFeatureInfoCmdId response (for features that have custom flags and user data)
FeatureInfoCommand::TFeature
(featureinfoplugin.h)
Data structure used to list the features in data structure TFeatureInfo
FeatureInfoCommand::
TFeatureInfo
(featureinfoplugin.h)
Data structure used to pass data with ELoadFeatureInfoCmdId response (for “simple” features without custom flags and user data)
CFeatureNotifier
(featurenotifier.h)
Active object for notification of feature changes
MFeatureObserver
(featurenotifier.h)
Interface for feature change notification
TFeatureEntry
(featurecmn.h)
Encapsulates a feature, status flags and feature data
RFeatureControl
(featurecontrol.h)
Enable/disable features at run-time, plus query methods

Further resources

  • Symbian^3 reference documentation for Feature Manager
  • Configurability Mechanisms wiki documentation on Feature Manager
  • Coming up next…

    Feature Registry is the next part of the Persistentdata for beginners series.