This tip pre-assumes that you already have a basic knowledge about the Qt 4 framework. I have only described the technical requirements for making a Qt 4 project runnable on Qt 5, but there are still several runtime bugs - You can look up most of them at KDAB.
This article gives you an idea of the difficulties you encounter if you convert a Qt 4 project to Qt 5.
The first version of Qt 4 was released in 2005, since 2012 is the currently (17-MAR-2013) newest version of Qt (5.0.1) available.
I have searched the web for many hours to find and summarize the traps one can struggle into during the porting process - A non-comfortable work which requires a lot of endurance. The main thought behind this article is to ease the searching process of other developers facing the same problem (there is a lot of information spread across many websites) and help them to get all the information they need at one central point, listed in a reliable way.
None of the changes are actually "real" code changes. Most of them need to be done by changing the Qt project file and some
#include directives. Therefore the change is quite easy if you are following the steps in this doc.
The effort is still non-zero.
Changes in the *.pro File
The only change in the *.pro file is that
QtWidgets is now a separate module. If you are using
QtWidgets somewhere in your project, you have to add the following line to the projects' *.pro file:
QT += widgets
Fixing the #include Directives
In the <qtroot>/qtbase/bin/ is located a Perl script file named fixqt4headers.pl . You can run it on the source code which you need to modify. The Perl file changes the
#include directives from Qt 4 to Qt 5 and also considers the module names.
The most known change which is fixed by the Perl script is that all
QtWidgets controls' specific source code is now located in the sub directory "
Changes in the Qt Macros
With Qt 5, there are some changes in its macro functionality coming up. The following macros have been deprecated and are now replaced with the better
Q_PLUGIN_METADATA macro is included near to the
Q_OBJECT macro in the class which is derived from
QObject and returned when loading the plugin.
Digia claims that the new
Q_PLUGIN_METADATA macro improves the performance and reliability of the plugin system because a plugins' DLL has not to be opened anymore to get the plugin metadata:
"The advantage of the new system is that it allows Qt to query the
metadata for the plugin without actually dlopen’ing it. This greatly
improves performance and reliability of the plugin system." - Digia
Another significant change is that the
QSKIP macro of the
QTestLib class accepted two arguments in Qt 4 - now in Qt 5, it does only accept one argument. A workaround for this can be a macro wrapper which takes two arguments and silently discards one when running under Qt 5. Be cautious when using this workaround!
Preprocessor Macro Changes
The platform definition macros of the preprocessor have also changed. Instead of
Q_WS_* as you did it in Qt 4, the new macro to be used is
QtQuick version which was available for Qt 4 is still available but it is part of a separate
QtDeclarative add-on module for compatibility purposes. Digia strongly recommends to use the new QtQuick 2.0 to avoid future binary breaks.
Qt 3 Support
Qt3Support module is not available for Qt 5. This basically means an official support for Qt 3 is not granted within Qt 5. If you want to port a Qt 3 project to Qt 5, you have to convert the Qt 3 project first to Qt 4.x and then from Qt 4.x to Qt 5.
Symbian and Meego
Meego and Symbian specific code has been removed from the codebase with the release of Qt 5.
The QWS system is not a part of Qt 5 and its APIs have been removed.
Points of Interest
I was surprised at how much effort the porting process takes. Without a deep Google search, it is nearly impossible to finish the porting process without a ton of luck or banging your head against a wall multiple times (including several annoying Google searches to resolve the errors) before it all works.
In the end, I can proudly say that you can port your project easily when you recognize all the difficulties written down in this article.
- 17-MAR-2013 Initial release
- 18-MAR-2013 Changed to Tip/Trick