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

Jump to: navigation, search
(11 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Development/Tutorials/KDE4_Porting_Guide}}
+
{{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. }}
  
==소개==
+
 
이 튜트리얼은 Qt3/KDE3 기반의 어플리케이션을 Qt4/KDE4로 포팅하도록 돕는 것을 목적으로 하고 있다.
+
==Introduction==
KD3 기반의 어플리케이션을 포팅하는 것은 어려운 과정이 필요 없다. 이미 도와줄 수 있는 많은 스크립트와 문서의 소스들이 존재한다.
+
 
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.
  
==규정==
+
==Conventions==
튜트리얼에서 이 설명들을 위해, 다음과 같은 약어를 사용할 것이다.
+
For the instructions in this tutorial we use the following shorthand:
:''For the instructions in this tutorial we use the following shorthand:''
+
* {{program|program}} refers to an executable program
 
+
* {{path|path}} refers to a path
 
+
* {{path|file}} refers to a file
* {{program|program}}은 실행할 프로그램을 나타낸다.
+
* $SVN is the fullpath to the location of your KDE subversion checkout
* {{path|path}}은 경로를 나타낸다.
+
* {{path|file}}는 파일을 나타낸다.
+
* $SVN은 당신의 KDE subversion이 checkout한 장소의 전체경로이다.
+
 
+
:'' {{program|program}} refers to an executable program''
+
:'' {{path|path}} refers to a path''
+
:'' {{path|file}} refers to a file''
+
:'' $SVN is the fullpath to the location of your KDE subversion checkout''
+
  
 
==CMake==
 
==CMake==
KDE3과 달리, KDE4 어플리케이션은 [[Development/Tutorials/CMake (ko)| CMake]]의 도움으로 빌드할 수 있다. 당신의 autotolls 시스템을 CMake로 쉽게 포팅하는 방법은 [http://websvn.kde.org/trunk/KDE/kdesdk/ kdesdk] 모듈의 {{path|cmake/scripts}} 디렉토리 안에서 찾을 수 있는 {{program|am2cmake}} 스크립트를 사용하는 것이다. 이것은 당신의 오래된 빌드 시스템 파일와 함께 {{path|CMakeLists.txt}} 파일 시리즈를 생성할 것이다.
+
Unlike KDE3, KDE4 applications will be built with the help of [[Development/Tutorials/CMake | CMake]]. The easiest way to port your autotools system to CMake is with the help of the {{program|am2cmake}} script which can be found in the {{path|cmake/scripts}} directory of the [http://websvn.kde.org/trunk/KDE/kdesdk/ kdesdk] module. This will create a series of {{path|CMakeLists.txt}} files alongside your old buildsystem files.
:''Unlike KDE3, KDE4 applications will be built with the help of [[Development/Tutorials/CMake | CMake]]. The easiest way to port your autotools system to CMake is with the help of the {{program|am2cmake}} script which can be found in the {{path|cmake/scripts}} directory of the [http://websvn.kde.org/trunk/KDE/kdesdk/ kdesdk] module. This will create a series of {{path|CMakeLists.txt}} files alongside your old buildsystem files.''
+
  
예를들어, 만약 당신의 소스코드가 {{path|/path/to/src}}에 위치같다면 다음과 같다.
 
 
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.
  
<tt>--kde4</tt> 플래그가 필요할 필요가 있는지 검사하기 위해, <tt> am2cmake --help</tt>를 실행하라.
+
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:
:''Run <tt> am2cmake --help</tt> to check whether you need the <tt>--kde4</tt> flag.''
+
<syntaxhighlight lang="bash">
 
+
cd /path/to/src
잠재된 문재들을 위하여, {{path|CMakeList.txt}}를 당신의 결과로 보여주는 또 하나의 툴이 있다. 이 툴은 {{path|$SVN/trunk/kde/kdesdk/scripts}} 안에 위치한 {{program|cmakelint.pl}}이다. 이것은 다음과 같이 사용한다.:
+
$SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl CMakeLists.txt
:''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:''
+
</syntaxhighlight>
<code bash>
+
Or, to run it over your entire source directory:
% cd /path/to/src
+
<syntaxhighlight lang="bash">
% $SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl CMakeLists.txt
+
cd /path/to/src
</code>
+
find . -name CMakeLists.txt | xargs $SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl
또는 당신의 전체 소스 디렉토리에 걸쳐서 실행한다.
+
</syntaxhighlight>
:''Or, to run it over your entire source directory:''
+
<code bash>
+
% cd /path/to/src
+
% find . -name CMakeLists.txt | \
+
  xargs $SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl
+
</code>
+
  
 
==Qt4 API==
 
==Qt4 API==
Qt4로 변경하는 Qt3에서 개요는 트롤테크의 [http://www.trolltech.com/products/qt/whatsnew/porting "Qt 3에서 Qt 4로 이동하기"]에서 제공되어진다. 이 문서는 Qt4의 주요 기능 변화에 대한 훌륭한 개요를 제공하며, 매우 추천할만 하다.
+
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://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.
[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.trolltech.com/latest/porting4.html "Qt 4로 포팅하기"] 페이지는 클래스와 함수의 변화 리스트에 따라 놀라울 정도로 포팅 과정 설명을 제공한다.
+
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.
The follow-on [http://doc.trolltech.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.
+
  
이 문서들은 당신의 Qt 코드 부분을 Qt3에서 Qt4로 호환되는 함수를 사용하여 포팅할 수 있으며, 트롤테크이 제공하는 {{program|qt3to4}}도구에 대해 설명한다. {{program|qt3to4}}를 다음과 같이 실행하라.
+
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:''
+
<syntaxhighlight lang="bash">
<code bash>
+
$SVN/trunk/qt-copy/bin/qt3to4 [options] <Infile>, [Infile], ...
% $SVN/trunk/qt-copy/bin/qt3to4 [options] <Infile>, [Infile], ...
+
</syntaxhighlight>
</code>
+
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은 소스파일이나 프로젝트 파일이 될 수 있다. 만약 (.pro 혹은 .pri로 끝나는)프로젝트 파일을 설정했다면, 프로젝트 안에 설정된 모든 파일이 포팅될 것이다.
+
:''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.''
+
  
좀 더 많은 정보를 위해서는 {{program|qt3to4}}를 --help 옵션으로 실행하라. 좀 더 많은 정보를 위해서는,[http://doc.trolltech.com/latest/qt3to4.html "qt3to4-Qt 3를 Qt4로 포팅하는 도구"] 페이지를 방문하라.
+
For more information, run {{program|qt3to4}} with the <tt>--help</tt> option or visit  
:''For more information, run {{program|qt3to4}} with the "--help" option or visit  
+
the [http://doc.qt.nokia.com/latest/qt3to4.html "qt3to4-The Qt 3 to 4 Porting Tool"] page.
the [http://doc.trolltech.com/latest/qt3to4.html "qt3to4-The Qt 3 to 4 Porting Tool"] page.''
+
  
추가적으로  당신을 위해 반대되는 Qt3의 많은 것들을 검색하거나 대신할 {{module|kdesdk}} 모듈 안의 {{program|remove-qt3-support.pl}}라고 불리는 프로그램이 존재한다. 이 프로그램은 소스 디렉토리 안에서 어떤 옵션 없이 간단히 실행된다.
+
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.''
+
<syntaxhighlight lang="bash">
<code bash>
+
$SVN/trunk/KDE/kdesdk/scripts/qt4/remove-qt3-support.pl
% $SVN/trunk/KDE/kdesdk/scripts/qt4/remove-qt3-support.pl
+
</syntaxhighlight>
</code>
+
 
 +
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==
포팅시도의 대부분은 간단히 다시 이름 붙여진 클래스 이름과 헤더파일을 구성한다. 수동으로 이 모든 것을 변화시키는 것은 약간 지루할 것이므로, {{module|kdesdk}}의 {{path|scripts/qt4}}안에 다루기 쉬운 {{program|adapt-to-kde4-api.pl}}라는 스크립트가 존재한다. 이것은 당신의 파일을 모두 검사할 것이고, 당신의 코드를 패치하는 데 사용될 수 있는 {{program|diff}} 출력을 만들어 낼 것이다.
+
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.
:''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.''
+
  
간단한 코드 변경은 수행되었다.. 당신은 아직도 당신의 코드를 포팅하도록 해야할 것이다.(예를 들어 새로운 <tt>KAction</tt> API와 같은 것들..) 모든 API 변화에 대한 문서는 {{module|kdelibs}}에[http://websvn.kde.org/*checkout*/trunk/KDE/kdelibs/KDE4PORTING.html KDE4PORTING.html]에 보관되어 있다.
+
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.
:''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.''
+
  
==Qt 디자이너 UI 파일==
+
==Qt Designer UI Files==
Qt3를 사용하여 생성된 Qt 디자이너 ".ui"파일은 새로운 Qt4 포맷으로 변환되어야 한다. 이것은 당신의 Qt4 설치 버전에서 사용 가능한 {{program|uic3}} 프로그램을 사용하여 수행될 수 있다.
+
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>
  
또는 그래픽 도구를 원한다면, Qt4의 디자이너 프로그램을 사용할 수 있다.
+
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.}}
 
+
You should also run the {{program|fixuifiles}} program from the {{module|kdesdk}} module, it performs cleanups and sanity checks:
{{Warning|변환 과정 중에 어떠한 커스텀 슬롯들, 테이블, 그 밖의 것을 잃어버리는 것에 대해 주의해라. 당신은 수동으로 몇몇 재료들을 넣어야 할 수도 있다.}}
+
<syntaxhighlight lang="cpp-qt">
:''Warning|Beware, the conversion process loses any custom slots, table columns, etc.  So, you may need to put some stuff back by hand.''
+
$SVN/trunk/KDE/kdesdk/scripts/fixuifiles
 
+
</syntaxhighlight>
당신은 {{module|kdesdk}} 모듈에서 {{program|fixuifiles}}프로그램을 실해야할 한다. 이것은 청소(cleanup)완전성 검사(sanity checks)를 수행한다.
+
:''You should also run the {{program|fixuifiles}} program from the {{module|kdesdk}} module, it performs cleanups and sanity checks:''
+
<code bash>
+
% $SVN/trunk/KDE/kdesdk/scripts/fixuifiles
+
</code>
+
  
 
==D-Bus==
 
==D-Bus==
DCOP in KDE3 대신, KDE4에서는 이제 IPC를 위해 D-Bus를사용한다. DCOP에서 D-Bus로 포팅하는 것은 [[Development/Tutorials/Porting_to_D-Bus (ko)|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 [[Development/Tutorials/Porting_to_D-Bus|Porting to D-Bus tutorial]].
:''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 [[Development/Tutorials/Porting_to_D-Bus (ko)|Porting to D-Bus tutorial]].''
+
 
+
좀더 세부적인 정보는, [[Development/Tutorials (ko)#D-Bus|D-Bus 튜트리얼]]를 살펴 보라.
+
:''For more information, please see all our [[Development/Tutorials#D-Bus|D-Bus tutorials]].''
+
  
==아이콘==
+
For more information, please see all our [[Development/Tutorials#D-Bus|D-Bus tutorials]].
KDE는 아이콘 이름을 위해 [http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html freedesktop.org icon naming specification]를 기초로 사용한다. 이것은 KDE4(Oxygen)에서 사용되는 아이콘과 아이콘을 사용하는 kdelibs 컴포넌트 둘 다 이 명세에 따른다는 것을 의미한다.
+
:''KDE4 uses the [http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html 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.''
+
  
당신의 어플리케이션을 KDE3에서 사용되는 아이콘 이름에서 KDE3가 사용하는 것으로 포팅하는 것은 루트 디렉토리에서 [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/qt4/adapt-to-icon-spec.py adapt-to-icon-spec.py]를 실행하고 화면의 설명에 따르기만 하면 되기 때문에 쉽다.
+
==Icons==
 +
KDE4 uses the [http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html 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 [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/qt4/adapt-to-icon-spec.py adapt-to-icon-spec.py] script from the root directory of your project and follow the instructions on screen. ''
+
Porting your app from the icon names used in KDE3 to the ones used in KDE4 is as easy as running the [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/qt4/adapt-to-icon-spec.py adapt-to-icon-spec.py] script from the root directory of your project and follow the instructions on screen.  
  
자동적으로 확실한 긍정을 변환하고(예를 들어,  KIcon 혹은 KIconLoader의 사용), 확실한 부정은 유지하며, 가능한 긍적이 무엇인지 알려준다. 이것을 원하거나 만들 것인지에 대한 추가적인 내용들을 나중에 보여주며, 포팅을 완료하기 위해 'y'나 'n'을 누르는 간단한 것으로 만든다.
+
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.
:''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.''
+
  
==국제화(I18N)==
+
==Internationalization==
 
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 138: 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 NOT use the old-style socket classes.   
 
* Do NOT use the old-style socket classes.   
 
* Do NOT use {{qt3|QPtrList}}, and in general, setAutoDelete()   
 
* Do NOT use {{qt3|QPtrList}}, and in general, setAutoDelete()   
Line 159: 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