KDE Mobile/Harmattan

KDE on Meego 1.2 Harmattan

This page is intended for developers seeking to deploy their KDE Applications on a Harmattan Device like the N9(50).

Getting Started

If you are new to Harmattan you should check out the [#General_Hints] section first

Development Repositories

For KDE Development you need several third party libraries. Several are available in the Nokia SDK repository which is also preinstalled in scratchbox. To provide additional libraries there are several packages needed by KDE available from the "rzr" repository, which is one of the biggest community repos. To enable this repository in your scratchbox or on your device add the following to you /etc/apt/sources.list:

deb http://harmattan-dev.nokia.com/ harmattan/sdk free non-free deb http://repo.pub.meego.com/home:/rzr:/harmattan/MeeGo_1.2_Harmattan_Maemo.org_MeeGo_1.2_Harmattan_standard/ ./

The SDK is already enabled in scratchbox but you need it on your device as it supplies dependencies needed by rzr packages.

For more on the rzr repository see: https://build.pub.meego.com/project/show?project=home%3Arzr%3Aharmattan

Set up a development Environment

Using Madde

You can use the following command to install kde libraries into your madde system root: mad-admin xdpkg -i <mylibrary.deb>

Here is the current issue: 1. KDE reports absolute paths to CMake. This causes trouble at build time in cross-compiling environments where these files are often relocated. 2. Once 1. is resolved, you have the issue that at run-time the libraries will again be relocated, so you need to adjust the rpath when building the package. You can also use LD_LIBRARY_PATH for that from a bash script file run from the desktop file. Those ways will be explained later.

There was a discussion started about a "--sysroot" option addition to cmake. It is something that has been existing for a while in case of Qt projects. It is handled properly by the QtCreator which is using MADDE underneath.

Here you can find the relevant thread about the discussion: http://mail.kde.org/pipermail/kde-buildsystem/2011-November/008270.html

Using Scratchbox

Scratchbox utilizes qemu and some changeroot style path seperation to allow you to have a development environment where you can "natively" compile for armel and work with armel packages on a generic Host system.

For information on how to install it see: http://harmattan-dev.nokia.com/platform-sdk

General Hints

When you start out with an N950 you might first want to upgrade your image to the latest version: http://wiki.meego.com/N950_landing_page offers information on how to do that.

Enabling Developer Mode

This is actually quite easy and there is even a GUI on the devices for it (reachable via Settings -> Security -> Developer Mode) This will also install an ssh server on your device which makes the rest of the installation much more comfortable.

Also, having enabled the Developer Mode, you will be able to check out the /var/log/syslog on your device for further information. Developer mode is intended for developing applications into the Nokia OVI store. You might need to use the "develsh" on your device for testing your application in certain cases.

Configure SSH

To connect to your ssh server you first have to set a password for the "user" account. To do that open the Terminal application and use devel-su to log in as root (default root password is rootme) and set the password for the user by calling passwd user. Now you are able to connect to your device as user and configure the OpenSSH server as usual.

Having enabled the developer mode, you also use the SDK Connection util on the applauncher screen to get the password for your connection. Let it USB or WI-FI. You can just then use the following command to log into your device over ssh: ssh [email protected]

Note: You have to use the desired password from the SDK Connection util at the prompt. Also, there are no differences between SDK Connection and Sync&Connect mode after plugging in your mini usb cable. They will both work for your development purposes in most cases (There are some Mac and Windows corner cases though).

Packaging your KDE Mobile application with shared libraries

This task comes into the picture when you would like to package your KDE Mobile application for OVI usage (ie.: for publish it into the Nokia OVI Store).

As for development, you can use the workflow aforementioned: just installing the kdelibs, kde-runtime, libkdeedu and so forth packages also in Scratchbox, Madde or the gadget.

However this is not the case for shipping your application into OVI store. The preferred workflow is grabbing the shared libraries after installing the relevant debian packages from the community repository and then put them into your application package (ie.: it becomes the part of your OVI application, like a "bundled" package). Note that, you are not obligated to use the pre-built kdelibs packages from the Community Open Build Service repository (or some fallback KDE Community Harmattan repository), if you do not wish. You can build your own version. It is just only for convenience.

The following examples demonstrates this theory.

main.cpp:

#include <KDE/KCmdLineArgs>

#include <stdio.h>
 
int main (int argc, char *argv[])
{
    KCmdLineArgs::init( argc, argv, 0 );
    printf("Hello KDE Mobile!\n");
    return 0;
}

This program is not very useful, but represents the situation when you are trying to use some feature of the kde libraries. It is a very good example for representing the issue we face during the packaging.

CMakeLists.txt:

project(packaging-test)
find_package(KDE4 REQUIRED)
include (KDE4Defaults)
include_directories(${KDE4_INCLUDES})
set(tutorial1_SRCS main.cpp)
kde4_add_executable(tutorial1 ${tutorial1_SRCS})
target_link_libraries(tutorial1 ${KDE4_KDECORE_LIBS} ${QT_QTCORE_LIBRARY})
install(TARGETS tutorial1 ${INSTALL_TARGETS_DEFAULT_ARGS})

This cmake file is very similar to the one from the Development Tutorial 1. It is basically almost a skeleton cmake file for kdelibs usage in general.

debian/rules:

#!/usr/bin/make -f

# Use this variable to allow options passed to cmake to be overridable
DEB_CMAKE_OPTIONS ?= -DCMAKE_INSTALL_RPATH=/opt/test/lib

%:
	dh $@

override_dh_auto_configure:
	dh_auto_configure -- $(DEB_CMAKE_OPTIONS)

debian/control:

Source: test
Priority: optional
Maintainer: Laszlo Papp <[email protected]>
Build-Depends: debhelper (>= 7.0.50), cmake
Standards-Version: 3.9.2
Section: utils

Package: test
Section: utils
Architecture: any
Depends: ${misc:Depends}
Description: Test package for packaging
 This package is for testing the integration of a shared library into the same
 package. The purpose of this is to see how application developers can ship
 application to various app stores, like OVI, Android market and so on, if the
 platform itself does not even provide those library functionalities.

The trick is actually happening on the packaging side, as you can see. It is not a biggie, but you can do this way: just setting the relevant rpath variable. The form of that is normally "/opt/myapp/lib" in case of the libraries.

You might want to protect your "bundles /opt/myapp path in order to prevent the incorrect plugin installation in there. It might sound a bit weird at first glance, but it is not any different from the desktop system. Anybody, meaning that any application from OVI, could install a new plugin underneath your application. For instance for kdelibs. It starts being a problem when there might be a variety of plugin versions available. Therefore, addressing the issue might well mean to protect your folder against it either by using aegis or other mechanisms. It is not that big task after all. The debian developers addressed this issue by having a "dlrestriction" library for avoiding this, but it is better to use the Harmattan platform capabilities for this task. Using dlrestriction would make the library slightly bigger (~13 KB), even though that is not a big disadvantage in comparison with the measured libkdecore5.so (~2,7 MB). Other distributions do not normally address this issue (apart from supporting the users in case of collided plugin versions).

The remaining files, like debian/control and so on are general. It is also possible to download the project in a tarball. See the attachment for details.

Testing and debugging your KDE Mobile application on the device

For QML deployment and testing: http://pontifications.hardakers.net/computers/speeding-up-qml-development-on-an-n950/

You can also use rsync for this purpose. 1) Log into the device 2) Run a script that rsyncs the code from my workstation, deleting any local changes and then runs the application

It is quite fast and you can see the stdout of your application in the terminal window.