close
The Wayback Machine - https://web.archive.org/web/20141006103540/https://sailfishos.org/wiki/Porting/Harmattan

Porting/Harmattan

Porting from MeeGo Harmattan to Sailfish OS

This guide contains useful information and guides on how to port existing MeeGo 1.2 Harmattan applications (for the Nokia N9) to Sailfish OS devices.

Similarities and differences between Harmattan and Sailfish

Harmattan Sailfish
System and Toolkit X11, Qt 4, QtQuick 1.0 Wayland, Qt 5, QtQuick 2.0
Swipe Lock screen.allowSwipe in QML or via SwipeControl / X11 Atom In Qt 5 via Qt::WindowOverridesSystemGestures
Application Startup applauncherd mapplauncherd (1)
.desktop file Freedesktop.org-compliant
Services / Daemons upstart (Creating daemons documentation) systemd
Orientation QtComponents Page orientationLock property Silica Page allowedOrientations property
Sensors Qt Mobility 1.2 Sensors API (accelerometer) Qt5 QtSensors (accelerometer)
Multimedia Qt Mobility 1.2 MultimediaKit (audio, video)
PulseAudio 		Qt5 QtMultimedia (audio, video)
PulseAudio
Feedback / Haptics Qt Mobility 1.2 Feedback API Qt5 QtFeedback (a Qt Add-on module)
Game Development Qt 4 (for OpenGL ES 2.0)
SDL 1.2 (for OpenGL ES 1.1 and 2.0) 		Qt 5 (for OpenGL ES 2.0)
SDL 2.0 (for OpenGL ES 1.1 and 2.0)
System Information qmsystem2, Qt Mobility 1.2 SystemInfo Qt5 QtSystemInfo (a Qt Add-on module)
UI Components Qt Quick Components Silica Components
UX Guidelines N9 UX Guidelines Sailfish OS User Experience
Packaging Debian-based ".deb"
apt Package manager
Security manifest: Aegis 		SuSE-based ".rpm"
zypper Package manager
No security manifest
Display Resolution 854x480 16:9 aspect ratio (2)

Notes:
(1) Without Splash Screen support (use --type=silica-qt5 for Silica apps in .desktop file, other supported boosters: qt5 qtquick2)
(2) Make your UI adapt to different resolutions, do not hard-code towards any particular screen resolution

Framework Porting Instructions

Some of the projects, frameworks and libraries that have been updated in Sailfish have their own instructions for porting from the old version to the new version:

Qt 4 to Qt 5

SDL 1.2 to SDL 2.0

  • Official Migration Guide - Explaining API differences and replacement functions when porting from SDL 1.2 to SDL 2.0.
  • sdl12compat.h, sdl12compat.c - Example code on how one could quickly implement SDL1.2-style API wrappers for SDL 2.0 with OpenGL ES 1.1 rendering

Debian packaging to RPM packaging

  • openSUSE Packaging Portal - For all things related to RPM packaging
  • Debian-Zypper Cheat Sheet - Contains listing of dpkg/apt commands and their corresponding rpm/zypper commands.
  • Mer Packaging guidelines - Packaging guidelines for Mer - more related to system-level packages, but in combination with the openSUSE Packaging Portal relevant to application developers as well.

Application Porting Tutorials

Some of these tutorials are still targeted towards the Alpha SDK (which had Qt 4 and X11), so be aware that additional porting steps might be required starting from the Alpha Qt 5 SDK (which has Qt 5 and Wayland):

Qt Quick Components to Sailfish Silica

Various packages with QML Components exist for different use cases, here is a list of the most important ones:

Harmattan Sailfish OS
Basic Components Qt Quick 1.1 Qt Quick 2.0
Web View Qt WebKit QML Module Qt 5 WebKit QML Module
Native User Interface Qt Quick Components
Qt Quick Components Extras 		Sailfish Silica Components
Multimedia Qt Mobility MultimediaKit Qt Multimedia 5.0
Additional modules Qt Mobility 1.2 QML Plugins Qt 5.0 Additional QML Modules
Nemo Mobile QML Plugins

As the user interface paradigm for Harmattan Qt Components and Sailfish Silica changes a bit, not all components map exactly. The following describes replacements for common UI elements in Harmattan with their Silica equivalents:

Harmattan Sailfish
Menus and Toolbars QML ToolBar QML PullDownMenu
Scrolling Views QML ListView
QML Flickable 		QML SilicaListView
QML SilicaFlickable
Item Selection QML MultiSelectionDialog
QML SelectionDialog 		QML ComboBox
Notifications QML InfoBanner None
Task Manager Integration None QML CoverBackground
QML CoverAction
Undo Functionality None QML RemorseItem

For a general overview of how Sailfish Silica works, please see the Sailfish Silica Component Gallery example that is shipped with the SDK Emulator.

Porting examples

Porting QtQuick QML applications

The Qt 5 documentation has an example how the Flickr application can be ported to Qt 5:

This tutorial shows how Qt Quick Components map to Sailfish Silica. As this tutorial has been written for the Alpha SDK, some changes might be necessary to get it working with the Alpha Qt 5 SDK:

Porting SDL / OpenGL ES applications

In general, you can follow the SDL 2.0 Migration Guide. What you usually have to do:

  • If you are using software rendering, render the final image to the screen via OpenGL ES
  • Instead of SDL_SetVideoMode, use SDL_CreateWindow (and SDL_GL_CreateContext if you've been using SDL_OPENGL / SDL_OPENGLES in SDL_SetVideoMode before)
  • Input events are not sent as mouse events anymore, but as SDL_TouchFingerEvent, which is an API tailored more towards multi-touch input (you need to handle SDL_FINGERMOTION, SDL_FINGERDOWN and SDL_FINGERUP)
  • The SDL_ActiveEvent is gone, and should be replaced with SDL_WindowEvent
  • All SDL extension libraries (SDL_mixer, SDL_ttf, SDL_image, etc...) have corresponding SDL2 versions - link against SDL2_mixer, etc.. (or better: use pkg-config)

Example commits that demonstrate code changes necessary to go from SDL 1.2 to SDL 2.0:

Example code that shows basic API usage of SDL 2.0 and usage of extension libraries:

API Gaps

The following APIs are still in development, more information will be available in the future:

  • Nemo Mobile QML Plugins
  • ...