Revision as of 20:53, 9 April 2013

Introduction

Nemo needs to be ready for Qt 5. This page attempts to document some information on how we're approaching 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.

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

QApplication

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

Ports in progress

• libmlocale (w00t)

Things that have been ported

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