Revision as of 21:53, 9 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) to 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 => libfoo5
• 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
• .prf files
• ... basically anything that gets installed.

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_CHECK_VERSION(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.

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 will soon be patched to allow this too.

nemo-qml-plugins

I think we should seriously split this up at the same time as we port it. One qml-plugins-devel package providing a .prf with sane settings/etc (the .pri we have now), and one repo/package per plugin (nemo-qml-plugin-contacts, etc). It's become a large and rather unwieldy beast in many senses, and that's going to mean that porting the whole thing at once is impossible.

We should handle this in lockstep: introduce the split plugin, change all dependencies to it, remove it from n-q-p, and then do the port of the plugin.

libprofile-qt

Seems to have a (build-only?) dependency on libmeegotouch. Why? Needs removing.

Ports in progress

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

• libmlocale (w00t)

Things that have been ported

Move stuff that is already finished here.

• libmlite (w00t)
• libngf-qt (w00t)