Revision as of 11:14, 19 April 2013

Introduction

Nemo needs to be ready for Qt 5. This page attempts to document some information on how we're addressing that, as well as common hurdles and approaches.

Approach

With the advent of webhooks, we are now able to easily build software we maintain on OBS just with git interaction. Luckily, it also gives us the capability to build a single source repository in multiple places, possibly with different spec files. We're taking advantage of this to (where possible) do ports in-place by adding qt5 packaging, and hacking the build system and code to handle that conditionally where possible.

NB: this document does not attempt to handle porting of software we do not maintain. Yet.

Rules of thumb/tips:

Keep the ports in-place where possible! Same source tree and branch as the qt4 version. If this isn't possible, talk to someone (i.e. w00t) about why to make sure it isn't, and let's figure out an alternative strategy.
Keep the ports minimal: use ifdefs and defines to minimize the pain in fairly central places (see below for some examples). This avoids you accidentally breaking something and keeps the maintenance cost minimal.
While you're porting, examine opportunities to minimize dependencies. Some code pulls in all sorts of crazy crap (an example: libmlocale pulled *everything in Qt* into the QT variable, even though it used basically none of it.)
Avoid linking to QtWidgets. It's heavy, and we want to not have it.
Avoid scope creep: port one thing at a time. When you get to an error, grep around for other instances, and fix them. Resist the urge to fix things that are not part of the port. File bugs or come back to it later.
Split your work into multiple small commits rather than one gigantic "Port to Qt 5" commit, unless the changes are tiny.

Initial setup

Make sure the project has been set up for git packaging:

Check it has a webhook in https://webhook.merproject.org/webhook/
Check it has an rpm/ directory
Check the hook in github etc is set up correctly
Check it's building correctly from the webhook

If these steps aren't OK, then fix it. If you don't know how, talk to w00t.

Then:

Add a new set of packaging following the name convention as follows: libfoo-qt => libfoo-qt5, libfoo => libfoo-qt5
Add dependencies to minimal needed Qt 5 modules (e.g. Qt5Core, Qt5Xml, etc in PkgConfigBR)
Add a new webhook for it, building to package name following the above naming convention
Start hacking using mb to build the new packaging

Build System

Qt 4 and 5 packages *must* be parallel-installable, both for images, and for SDK purposes. This means that you'll need to rename:

Libraries
Binaries
.pc files
... basically anything that gets installed.

For header files, you should send them to different directories. For instance, /usr/include/mlite, /usr/include/mlite5.

Note that you don't need to duplicate or rename:

QML imports or change their name
prf files

They are installed to a different location in Qt 4 and Qt 5.

Use constructs like the following to handle conditionals:

equals(QT_MAJOR_VERSION, 4): TARGET = foo
equals(QT_MAJOR_VERSION, 5): TARGET = foo5

Use QT_VERSION and QT_VERSION_CHECK in code, like this:

#if QT_VERSION >= QT_VERSION_CHECK(5, 0, 0)
# include <QtQml>
# include <QQmlEngine>
# include <QQmlExtensionPlugin>
# define QDeclarativeEngine QQmlEngine
# define QDeclarativeExtensionPlugin QQmlExtensionPlugin
#else
# include <QtDeclarative>
# include <QDeclarativeEngine>
# include <QDeclarativeExtensionPlugin>
#endif

Porting Code

setCodecForCStrings / codecForCStrings

This doesn't exist in Qt 5. Qt 5's locale for C strings is always UTF-8. You'll need to reencode the strings if they aren't in UTF-8, or ifdef the locale forcing if they are, like so:

+#if QT_VERSION < QT_VERSION_CHECK(5, 0, 0)
     QTextCodec::setCodecForCStrings(QTextCodec::codecForName("UTF-8"));
+#endif

toAscii / fromAscii

These are gone. You probably want toLatin1 / fromLatin1. If you were using a custom C codec (see above) then you're probably screwed and will need to use QTextCodec yourself.

QApplication

You should avoid using this. It lives in QtWidgets. Use QGuiApplication from QtGui instead, or - even better - QCoreApplication from QtCore.

Qt 5 porting documentation

Qt 5 Porting Guide http://qt-project.org/doc/qt-5.0/qtdoc/portingguide.html

The Transition from Qt 4.x to Qt 5 http://qt-project.org/wiki/Transition_from_Qt_4.x_to_Qt5

KDAB Porting from Qt 4 to Qt 5 article http://www.kdab.com/porting-from-qt-4-to-qt-5

Qt API changes http://qt.gitorious.org/qt/qtbase/blobs/HEAD/dist/changes-5.0.0

Porting whiteboard

SDK issues

Note that Mer SDK cannot parallel install Qt 4 and Qt 5 yet. Next mer release fixes that.

Note that we need to use %qmake5 (spec) for Qt 5 packaging. Spectacle has been patched to allow qmake5 as builder in yaml, and will be released soon: https://gitorious.org/meego-developer-tools/spectacle/

nemo-qml-plugins

This is going to be split into multiple packages that we can then independently split instead of the current gigantic monster.

contextkit

We hope to not port this, and use statefs instead.

kcalcore

We need to investigate upstream kcalcore vs the MeeGo fork and decide which to use.

libjollasignonuiservice

The library requires X11 for web view embedding unless SIGNON_UI_NO_EMBED_WEBVIEW is defined. Investigate how to achieve the same or is it even needed. Can we use SIGNON_UI_NO_EMBED_WEBVIEW for now?

Things that are not yet/currently being ported

qt-components
nemo-qml-plugin-messages-internal
nemo-qml-plugin-contextkit
buteo-mtp
qmlpinquery
libcommhistory
signon-plugin-oauth2
mthemedaemon
buteo-syncfw
fingerterm
meego-handset-camera
nemo-qml-plugin-grilo
maliit-framework
voicecall
tracker
ssu
commhistory-daemon
qmlnotes
contactsd
lipstick

Ports in progress

Add stuff you're working on to stop someone else picking it.

nemo-qml-plugins (w00t)
timed (PMG)
mapplauncherd (special)
libconnman-qt (lpotter)
sensorfw (lpotter)
qofono (lpotter)
libresourceqt (mjones)
kcalcore (mjones)
mkcal (mjones)
nemo-qml-plugin-calendar (mjones)
libqtsparql (mvogt)
libquillimage (mvogt)
tumbler (mvogt)

Things that have been ported

Move stuff that is already finished here.

libcontentaction (w00t)
libmlite (w00t)
libngf-qt (w00t)
libmlocale (w00t)
libprofile-qt (vesuri)
libaccounts-qt (vesuri)
libbluez-qt (mjones)
quillmetadata (mjones)
libsignon (vesuri)
eventfeed (vesuri)

Things that shouldn't be ported

qtcontacts-tracker (to be replaced with qtcontacts-sqlite)
libqtsparql-tracker-extensions (qtcontacts-tracker dependency only)
libcubi (qtcontacts-tracker dependency only)
libcubi-tracker-ontologies (qtcontacts-tracker dependency only)
libqttracker (no dependencies)
libmeegotouch
contextkit (hopefully replaced by statefs)
meegotouch-compositor

@@ Line 130: / Line 130: @@
 * mthemedaemon
 * buteo-syncfw
-* qmsystem
 * fingerterm
 * meego-handset-camera

Nemo/Qt5Porting