Difference between revisions of "Development/Tutorials/KDE4 Porting Guide"

Jump to: navigation, search
(CMake)
(18 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 +
{{warning|This page is yet to be reviewed for changes required by the migration to Git.  Information and commands on this page may no longer be valid and should be used with care. Please see the [[Development/Git|KDE Git hub page]] for more details. }}
 +
 +
 
==Introduction==
 
==Introduction==
 
A tutorial intended to help developers port their Qt3/KDE3 based applications to Qt4/KDE4.  Porting a KDE3 based application needn't be a difficult process. Already, there are many scripts and sources of documentation which can help.
 
A tutorial intended to help developers port their Qt3/KDE3 based applications to Qt4/KDE4.  Porting a KDE3 based application needn't be a difficult process. Already, there are many scripts and sources of documentation which can help.
Line 13: Line 16:
  
 
For example, if your source code is located in {{path|/path/to/src}} then:
 
For example, if your source code is located in {{path|/path/to/src}} then:
<code bash>
+
<syntaxhighlight lang="bash">
% cd /path/to/src
+
cd /path/to/src
% $SVN/trunk/KDE/kdesdk/cmake/scripts/am2cmake --kde4
+
$SVN/trunk/KDE/kdesdk/cmake/scripts/am2cmake --kde4
</code>
+
</syntaxhighlight>
Run <tt> am2cmake --help</tt> to check whether you need the <tt>--kde4</tt> flag.
+
Run <tt>am2cmake --help</tt> to check whether you need the <tt>--kde4</tt> flag.
  
 
There is also a tool that looks in your resulting {{path|CMakeList.txt}} files for potential problems.  This tool called {{program|cmakelint.pl}} is located in {{path|$SVN/trunk/kde/kdesdk/scripts}}.  Use it like so:
 
There is also a tool that looks in your resulting {{path|CMakeList.txt}} files for potential problems.  This tool called {{program|cmakelint.pl}} is located in {{path|$SVN/trunk/kde/kdesdk/scripts}}.  Use it like so:
<code bash>
+
<syntaxhighlight lang="bash">
% cd /path/to/src
+
cd /path/to/src
% $SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl CMakeLists.txt
+
$SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl CMakeLists.txt
</code>
+
</syntaxhighlight>
 
Or, to run it over your entire source directory:
 
Or, to run it over your entire source directory:
<code bash>
+
<syntaxhighlight lang="bash">
% cd /path/to/src
+
cd /path/to/src
% find . -name CMakeLists.txt | \
+
find . -name CMakeLists.txt | xargs $SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl
  xargs $SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl
+
</syntaxhighlight>
</code>
+
  
 
==Qt4 API==
 
==Qt4 API==
 
An overview of the Qt3 to Qt4 transition is provided in Trolltech's  
 
An overview of the Qt3 to Qt4 transition is provided in Trolltech's  
[http://www.trolltech.com/products/qt/whatsnew/porting "Moving from Qt 3 to Qt 4"] paper.  This document provides an excellent overview into the major functionality changes with Qt4 and is highly recommended.
+
[http://doc.qt.nokia.com/latest/porting4-overview.html "Moving from Qt 3 to Qt 4"] paper.  This document provides an excellent overview into the major functionality changes with Qt4 and is highly recommended.
  
The follow-on [http://doc.trolltech.com/4.2/porting4.html "Porting to Qt 4"] page gives an amazingly detailed description of the porting process, along with a list of the changes in the classes and functions.
+
The follow-on [http://doc.qt.nokia.com/latest/porting4.html "Porting to Qt 4"] page gives an amazingly detailed description of the porting process, along with a list of the changes in the classes and functions.
  
 
These documents describe a tool provided by Trolltech called {{program|qt3to4}} that can help port the Qt parts of your code from Qt3 to Qt4, using compatibility functions.  Run {{program|qt3to4}} as follows:
 
These documents describe a tool provided by Trolltech called {{program|qt3to4}} that can help port the Qt parts of your code from Qt3 to Qt4, using compatibility functions.  Run {{program|qt3to4}} as follows:
<code bash>
+
<syntaxhighlight lang="bash">
% $SVN/trunk/qt-copy/bin/qt3to4 [options] <Infile>, [Infile], ...
+
$SVN/trunk/qt-copy/bin/qt3to4 [options] <Infile>, [Infile], ...
</code>
+
</syntaxhighlight>
 
Infile can be a source file or a project file. If you specify a project file, ending with '.pro' or '.pri', {{program|qt3to4}} will port all files specified in that project.
 
Infile can be a source file or a project file. If you specify a project file, ending with '.pro' or '.pri', {{program|qt3to4}} will port all files specified in that project.
  
For more information, run {{program|qt3to4}} with the "--help" option or visit  
+
For more information, run {{program|qt3to4}} with the <tt>--help</tt> option or visit  
the [http://doc.trolltech.com/4.2/qt3to4.html "qt3to4-The Qt 3 to 4 Porting Tool"] page.
+
the [http://doc.qt.nokia.com/latest/qt3to4.html "qt3to4-The Qt 3 to 4 Porting Tool"] page.
  
 
Additionally, there is a program called {{program|remove-qt3-support.pl}} in the {{module|kdesdk}} module that will search and replace lots of deprecated Qt3 stuff for you. Simply run this program without any options in the source directory.
 
Additionally, there is a program called {{program|remove-qt3-support.pl}} in the {{module|kdesdk}} module that will search and replace lots of deprecated Qt3 stuff for you. Simply run this program without any options in the source directory.
<code bash>
+
<syntaxhighlight lang="bash">
% $SVN/trunk/KDE/kdesdk/scripts/qt4/remove-qt3-support.pl
+
$SVN/trunk/KDE/kdesdk/scripts/qt4/remove-qt3-support.pl
</code>
+
</syntaxhighlight>
 +
 
 +
Chances are that some Qt3 classes will still remain in the code, so make sure your top-level CMakeLists.txt file defines the QT3_SUPPORT and QT3_SUPPORT_WARNINGS macros for the Qt headers, like so:
 +
<pre>
 +
add_definitions (-DQT3_SUPPORT -DQT3_SUPPORT_WARNINGS)
 +
</pre>
  
 
==KDE4 API==
 
==KDE4 API==
Much of the porting effort consists of simply renaming class names and header files. Since it would be rather tedious to change all these by hand, there is a handy script in the {{path|scripts/qt4}} directory of {{module|kdesdk}} called {{program|adapt-to-kde4-api.pl}}. This will scan all your files and create a {{program|diff}} output which can then be used to patch your code.
+
Much of the porting effort consists of simply renaming class names and header files. Since it would be rather tedious to change all these by hand, there is a handy script in the {{path|scripts/qt4}} directory of {{module|kdesdk}} called {{program|adapt-to-kde4-api.pl}}. This will update all your files and output a {{program|diff}} so you can see what changes were made.
  
Once that simple code substitution has been done, you will still have to go through your code to port to, for example, the new <tt>KAction</tt> API. Documentation about all API changes is kept in the [http://websvn.kde.org/*checkout*/trunk/KDE/kdelibs/KDE4PORTING.html KDE4PORTING.html] file in the {{module|kdelibs}} module.
+
Once that simple code substitution has been done, you will still have to go through your code to port to, for example, the new <tt>KAction</tt> API. Documentation about all API changes is kept in the [https://projects.kde.org/projects/kde/kdelibs/repository/revisions/master/raw/KDE4PORTING.html KDE4PORTING.html] file in the {{module|kdelibs}} module.
  
 
==Qt Designer UI Files==
 
==Qt Designer UI Files==
 
Qt designer ".ui" files created using Qt3 must be converted to the new Qt4 format.  This can be done using the {{program|uic3}} program available from your Qt4 installation.
 
Qt designer ".ui" files created using Qt3 must be converted to the new Qt4 format.  This can be done using the {{program|uic3}} program available from your Qt4 installation.
  
<code bash>
+
<syntaxhighlight lang="bash">
% $SVN/trunk/qt-copy/bin/uic3 -convert file.ui > foo.ui
+
$SVN/trunk/qt-copy/bin/uic3 -convert file.ui > foo.ui
% mv foo.ui file.ui
+
mv foo.ui file.ui
</code>
+
</syntaxhighlight>
  
 
Or, if you prefer a graphical tool, you can use Qt4's designer program
 
Or, if you prefer a graphical tool, you can use Qt4's designer program
  
<code bash>
+
<syntaxhighlight lang="bash">
% $SVN/trunk/qt-copy/bin/designer file.ui
+
$SVN/trunk/qt-copy/bin/designer file.ui #you can save file.ui over top itself, or save to a new file
(you can save file.ui over top itself, or save to a new file)
+
</syntaxhighlight>
</code>
+
 
{{Warning|Beware, the conversion process loses any custom slots, table columns, etc.  So, you may need to put some stuff back by hand.}}
 
{{Warning|Beware, the conversion process loses any custom slots, table columns, etc.  So, you may need to put some stuff back by hand.}}
You should also run the {{program|fixuifiles}} program from the {{module|kdesdk}} module:
+
You should also run the {{program|fixuifiles}} program from the {{module|kdesdk}} module, it performs cleanups and sanity checks:
<code bash>
+
<syntaxhighlight lang="cpp-qt">
% $SVN/trunk/KDE/kdesdk/scripts/fixuifiles
+
$SVN/trunk/KDE/kdesdk/scripts/fixuifiles
</code>
+
</syntaxhighlight>
  
 
==D-Bus==
 
==D-Bus==
Line 91: Line 97:
 
To create your ".pot" file, copy the commands from the 'messages' rule in your projects {{path|Makefile.am}} to a shell script called {{path|Messages.sh}}.  You may assume the same variables ($PREPARETIPS, $XGETTEXT, $podir, etc.) still exist, but keep in mind the differences between Makefile and shell script syntax.
 
To create your ".pot" file, copy the commands from the 'messages' rule in your projects {{path|Makefile.am}} to a shell script called {{path|Messages.sh}}.  You may assume the same variables ($PREPARETIPS, $XGETTEXT, $podir, etc.) still exist, but keep in mind the differences between Makefile and shell script syntax.
  
Also be careful that if you use the -k parameter with $XGETTEXT, you will need to explicitely list all variants that you use.
+
Also be careful that if you use the -k parameter with $XGETTEXT, you will need to explicitly list all variants that you use.
  
 
For example, the 'messages' creation rule:
 
For example, the 'messages' creation rule:
<code>
+
<pre>
 
messages: rc.cpp
 
messages: rc.cpp
 
         rm -f tips.cpp
 
         rm -f tips.cpp
Line 100: Line 106:
 
         $(XGETTEXT) -ktranslate *.cpp *.h -o $(podir)/kmail.pot
 
         $(XGETTEXT) -ktranslate *.cpp *.h -o $(podir)/kmail.pot
 
         rm -f tips.cpp
 
         rm -f tips.cpp
</code>
+
</pre>
 
becomes the following {{path|Messages.sh}} script:
 
becomes the following {{path|Messages.sh}} script:
<code bash>
+
<syntaxhighlight lang="bash">
 
#! /usr/bin/env bash
 
#! /usr/bin/env bash
 
$PREPARETIPS > tips.cpp
 
$PREPARETIPS > tips.cpp
 
$XGETTEXT -ktranslate:1,1t -ktranslate:1c,2,2t *.cpp *.h -o $podir/kmail.pot
 
$XGETTEXT -ktranslate:1,1t -ktranslate:1c,2,2t *.cpp *.h -o $podir/kmail.pot
 
rm -f tips.cpp
 
rm -f tips.cpp
</code>
+
</syntaxhighlight>
  
 
==Do's and Don'ts==   
 
==Do's and Don'ts==   
Line 121: Line 127:
 
===Documentation===   
 
===Documentation===   
 
* [http://doc.trolltech.com/4.3 Qt4.3 Reference]   
 
* [http://doc.trolltech.com/4.3 Qt4.3 Reference]   
* [http://developer.kde.org/documentation/library/svn-api.php KDE4 API Reference]   
+
* [http://api.kde.org/ KDE4 API Reference]   
 
* [http://www.cmake.org/HTML/Documentation.html CMake Cross Platform Make]   
 
* [http://www.cmake.org/HTML/Documentation.html CMake Cross Platform Make]   
* [http://websvn.kde.org/*checkout*/trunk/KDE/kdelibs/KDE4PORTING.html KDE4PORTING.html]
+
* [https://projects.kde.org/projects/kde/kdelibs/repository/revisions/master/raw/KDE4PORTING.html KDE4PORTING.html]
  
 
===Other Help===   
 
===Other Help===   
* #kde4-devel on irc.freenode.net   
+
* #kde-devel on irc.freenode.net   
  
 
[[Category:KDE4]]
 
[[Category:KDE4]]

Revision as of 16:35, 13 July 2012

noframe
 
Warning
This page is yet to be reviewed for changes required by the migration to Git. Information and commands on this page may no longer be valid and should be used with care. Please see the KDE Git hub page for more details.


Contents

Introduction

A tutorial intended to help developers port their Qt3/KDE3 based applications to Qt4/KDE4. Porting a KDE3 based application needn't be a difficult process. Already, there are many scripts and sources of documentation which can help.

Conventions

For the instructions in this tutorial we use the following shorthand:

  • program refers to an executable program
  • path refers to a path
  • file refers to a file
  • $SVN is the fullpath to the location of your KDE subversion checkout

CMake

Unlike KDE3, KDE4 applications will be built with the help of CMake. The easiest way to port your autotools system to CMake is with the help of the am2cmake script which can be found in the cmake/scripts directory of the kdesdk module. This will create a series of CMakeLists.txt files alongside your old buildsystem files.

For example, if your source code is located in /path/to/src then:

cd /path/to/src
$SVN/trunk/KDE/kdesdk/cmake/scripts/am2cmake --kde4

Run am2cmake --help to check whether you need the --kde4 flag.

There is also a tool that looks in your resulting CMakeList.txt files for potential problems. This tool called cmakelint.pl is located in $SVN/trunk/kde/kdesdk/scripts. Use it like so:

cd /path/to/src
$SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl CMakeLists.txt

Or, to run it over your entire source directory:

cd /path/to/src
find . -name CMakeLists.txt | xargs $SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl

Qt4 API

An overview of the Qt3 to Qt4 transition is provided in Trolltech's "Moving from Qt 3 to Qt 4" paper. This document provides an excellent overview into the major functionality changes with Qt4 and is highly recommended.

The follow-on "Porting to Qt 4" page gives an amazingly detailed description of the porting process, along with a list of the changes in the classes and functions.

These documents describe a tool provided by Trolltech called qt3to4 that can help port the Qt parts of your code from Qt3 to Qt4, using compatibility functions. Run qt3to4 as follows:

$SVN/trunk/qt-copy/bin/qt3to4 [options] <Infile>, [Infile], ...

Infile can be a source file or a project file. If you specify a project file, ending with '.pro' or '.pri', qt3to4 will port all files specified in that project.

For more information, run qt3to4 with the --help option or visit the "qt3to4-The Qt 3 to 4 Porting Tool" page.

Additionally, there is a program called remove-qt3-support.pl in the kdesdk module that will search and replace lots of deprecated Qt3 stuff for you. Simply run this program without any options in the source directory.

$SVN/trunk/KDE/kdesdk/scripts/qt4/remove-qt3-support.pl

Chances are that some Qt3 classes will still remain in the code, so make sure your top-level CMakeLists.txt file defines the QT3_SUPPORT and QT3_SUPPORT_WARNINGS macros for the Qt headers, like so:

add_definitions (-DQT3_SUPPORT -DQT3_SUPPORT_WARNINGS)

KDE4 API

Much of the porting effort consists of simply renaming class names and header files. Since it would be rather tedious to change all these by hand, there is a handy script in the scripts/qt4 directory of kdesdk called adapt-to-kde4-api.pl. This will update all your files and output a diff so you can see what changes were made.

Once that simple code substitution has been done, you will still have to go through your code to port to, for example, the new KAction API. Documentation about all API changes is kept in the KDE4PORTING.html file in the kdelibs module.

Qt Designer UI Files

Qt designer ".ui" files created using Qt3 must be converted to the new Qt4 format. This can be done using the uic3 program available from your Qt4 installation.

$SVN/trunk/qt-copy/bin/uic3 -convert file.ui > foo.ui
mv foo.ui file.ui

Or, if you prefer a graphical tool, you can use Qt4's designer program

$SVN/trunk/qt-copy/bin/designer file.ui #you can save file.ui over top itself, or save to a new file
noframe
 
Warning
Beware, the conversion process loses any custom slots, table columns, etc. So, you may need to put some stuff back by hand.

You should also run the fixuifiles program from the kdesdk module, it performs cleanups and sanity checks:

$SVN/trunk/KDE/kdesdk/scripts/fixuifiles

D-Bus

Instead of DCOP in KDE3, KDE4 now uses D-Bus for its interprocess communication. Porting from DCOP to D-Bus is a large topic that is covered in great detail in the Porting to D-Bus tutorial.

For more information, please see all our D-Bus tutorials.

Icons

KDE4 uses the freedesktop.org icon naming specification as the basis for icon names. This means that both the icons that ship with KDE4 (Oxygen) as well as components in kdelibs that use icons follow this specification.

Porting your app from the icon names used in KDE3 to the ones used in KDE4 is as easy as running the adapt-to-icon-spec.py script from the root directory of your project and follow the instructions on screen.

The script automatically converts confirmable positives (e.g. uses of KIcon or KIconLoader), skips confirmable negatives and prompts for what to do with possible positives. It shows the latter with additonal context if desired and makes it a simple matter of pressing 'y' or 'n' for the possible hits to complete the porting.

Internationalization

To create your ".pot" file, copy the commands from the 'messages' rule in your projects Makefile.am to a shell script called Messages.sh. You may assume the same variables ($PREPARETIPS, $XGETTEXT, $podir, etc.) still exist, but keep in mind the differences between Makefile and shell script syntax.

Also be careful that if you use the -k parameter with $XGETTEXT, you will need to explicitly list all variants that you use.

For example, the 'messages' creation rule:

messages: rc.cpp
        rm -f tips.cpp
        $(PREPARETIPS) > tips.cpp
        $(XGETTEXT) -ktranslate *.cpp *.h -o $(podir)/kmail.pot
        rm -f tips.cpp

becomes the following Messages.sh script:

#! /usr/bin/env bash
$PREPARETIPS > tips.cpp
$XGETTEXT -ktranslate:1,1t -ktranslate:1c,2,2t *.cpp *.h -o $podir/kmail.pot
rm -f tips.cpp

Do's and Don'ts

  • Do NOT use the old-style socket classes.
  • Do NOT use QPtrList, and in general, setAutoDelete()
  • Do NOT make use of raster operations.
  • Do NOT do code painting on widgets outside paint events.
  • Try not to use QHBox, QVBox, QGrid. Prefer layouts instead.
  • Do NOT play with frames of groupboxes, labels, or lineedits to fake a different widget. Use the appropriate widget instead. e.g., instead of setting a label to have a sunken lineedit border, how about using a readonly KLineEdit instead? And instead of using a KLineEdit without a border for a copyable widget, use KActiveLabel.
  • Do NOT use a groupbox without border to group widgets! Just use a layout.

Resources

Documentation

Other Help

  • #kde-devel on irc.freenode.net

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal