Latest revision as of 17:33, 22 March 2012

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

Community Open Build Service

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 community repository see:

https://build.pub.meego.com/project/show?project=home%3Arzr%3Aharmattan

Fallback KDE Harmattan Repository

The idea is that: we have a fallback repository for the Community Open Build Service.

The purpose of that is to aid the KDE Mobile development workflow for Harmattan. We could probably establish an "external" site, but a KDE community site is more "official". We have the Community Open Build Service for automated building and then publishing, but it sometimes fails even for weeks. Hence, avoiding the stuck for weeks sometimes in the KDE Mobile development workflow, we need a fallback for those cases.

This is not intended be as quality based as c-obs, but fine for fallback option to get the kde packages for your mobile development. The principle, behind it, is a simple push policy. If you have a kde library to share with us, you can just push those package(s) to this fallback repository since the harmattan target does not really work well on c-obs (it is still asort of experiment target addition). It does not mean that everybody will able entitled to push packages into this repository, and would probably need some discussion with the modulo approvals of the other team members before getting a new type of package in.

As for an example, what the Kolab team established for Fremantle:

http://files.kolab.org/local/maemo/dists/fremantle/testing/binary-armel/kdepimlibs/

They partially have an automated workflow. However, this is sometimes too much for publishing packages as a workaround. Note, we do not intend to replace the Community Open Build Service since it has the proper design for this workflow. Unfortunately, it does not work perfectly implementation-wise. Also, Kolab is a company, not a community in that sense even if they deal with open source projects.

You can find the fallback repository here:

http://files.kde.org/maemo/dists/harmattan

To enable this repository in your scratchbox or on your device add the following to you /etc/apt/sources.list:

deb http://files.kde.org/maemo/dists/harmattan ./

Set up a development Environment

Using Madde

To setup madde there's some required black magic involved. You'll have to run this [1] script first so that you can compile your KDE applications easily.

[1] http://proli.net/meu/kde/setupmad.sh

You can run it like as follows:

setupmad.sh <path to mad binary> <target name>

for example:

setupmad.sh ~/QtSdk/Madde/bin harmattan-platform-api

you can list the targets by using:

mad list

This script adds some relevant packages to your desired madde installation and patches KDE's CMake files so that they can find KDE's Harmattan include files and libraries.

Now if you want to work with it, you'll add "mad" at the beginning of the command to run, for example:

mad -t <target> dpkg-buildpackage

or

mad -t <target> cmake ../myproject
mad -t <target> make

Remember that in Harmattan you can only execute binaries installed from a debian package!

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. The following page offers information on how to do that:

http://wiki.meego.com/N950_landing_page

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).

Development

Harmattan Components:

http://harmattan-dev.nokia.com/docs/library/html/qt-components/qt-components-meego-simpletutorial.html?tab=1

Pure QML Elements:

http://harmattan-dev.nokia.com/docs/library/html/qt4/qdeclarativeelements.html?tab=1

The list of the available Plasma Components:

https://projects.kde.org/projects/kde/kde-runtime/repository/revisions/master/entry/plasma/declarativeimports/plasmacomponents/qml/qmldir

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 Harmattan!\r\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: user/kde
Maemo-Flags: visible

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).

You can see the "Section: user/kde" and "Maemo-Flags: visible" entries. They are a bit of duplicated as of now. They were put into this simple example to show how certain things can be done in different ways.

After either of those lines, you will be able to execute the following command: pkgmgr --install-file --file <your-deb-file>

It will help you to install packages as a non-root user. This can be handy at points. The idea was that the "Section: user/*" line is replaced with "Maemo-Flags: visible". Both should work, but the Maemo-Flags method never entered common knowledge.The original purpose of the section/flag was to help with browsing the repositories, as in: not show everything that is inside those repositories. Now that the Application Manager is no longer a repository browser, it does not need explicit flags actually: just show what the user has manually installed, and hide all automatically installed packages. This realization was a bit late on the platform developers' side.

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 have some options for doing this:

1) Log into the device and run a script making an rsync the code from your host, deleting any local changes and then runs the application:

http://wiki.meego.com/RsyncAndRunShellScript#Rsync_.26_run_your_projects_on_the_device_using_a_shell_script

It is quite fast and you can see the stdout of your application in the terminal window. It is good for incremental updates in larger projects.

2) You can always just simply use "scp -r" for your qml folder and if that is simpler for your use case.

3) As a last resort, you can also use "dpkg-buildpackage -nc" and "fakeroot ./debian/rules binary" like commands for speeding up the rebuilding process in scratchbox, at least.

Ported Applications

New Applications