Note: This is documentation for KDElibs3. KDElibs 4 documentation will be available after its first release.
Currently, KDElibs/win32 is not too easy to install: there is no single command to install it. This probably will be available later. Below you can learn required and optional steps resulting in KDElibs/win32 development environment.
ye
Recent Changes
2005-08-26
* Section about CVS replaced with section about Subversion
* Added information about a need for appending
$QTDIR/plugins to Qt Designer plugins path to make
kdewidgets plugin work
* Added various notes about paths for "Set environment
variables related to KDElibs/win32" section
Compiler
- Unfortunately, only currently supported is Microsoft Visual C++ 7.0 or later (will be refered as msvc7). Microsoft Visual C++ 6.0 is not supported because of lack of standard c++ features that KDElibs use. Note: depending on popularity, gcc (mingw), borland c++, and intel c++ compilers will be tested and then support officially.
- You may either use command line compiler's tools (nmake for msvc, make for other compilers) or use IDE (http://en.wikipedia.org/wiki/Integrated_development_environment) shipped with your compiler toolset. Instructions given here are mostly not dependent on whether you're using command line or IDE.
Qt3/win32 installation
- You can use following sources of Qt for windows:
- Commercial (http://www.trolltech.com/purchase/alternative.html) version; allows to develop both closed and open source applications. Only this option is currently supported by KDElibs/win32.
- Evaluation/Educational (http://www.trolltech.com/download/qt/evaluate.html?cid=20) version; the disadvantage is that you will receive precompiled Qt binaries only, and evaluation is limited in time. Note: currently, this option is not officially supported for KDElibs/win32.
-
GPL (http://kde-cygwin.sourceforge.net/qt3-win32/) version; for applications released under the GPL (http://www.gnu.org/licenses/licenses.html#GPL) or LGPL (http://www.gnu.org/licenses/licenses.html#LGPL). Note: this option is not supported.
- Select proper version of Qt
Newest is better rule applies here, exactly like e.g. on Linux. KDE/win32 is currently based on prerelease version of KDE 3.4, so requirement for Qt version is 3.3.x. Version 3.2.x will may work too, but nobody knows how long. Owners of Qt Proffesional (as opposed to Enterprise) are probably in trouble :( , since there are requirements for Qt modules not available in this edition (see below).
- For msvc compilers only: Patch Qt source code. (Trolltech said they this is a bug in Qt version 3.x but it will be fixed only for Qt4). So, using cygwin bash shell, go to your $QTDIR/include/ directory, download this patch (http://www.kdelibs.com/patches/operators.patch) and apply it using command: patch < operators.patch to avoid compilation errors caused by ambiguity when using operator[]( int i ) for QChar, QCharRef, QString and QGArray's derivatives.
Notes:
- The patch keeps binary compatibility by using inlined methods, but msvc generates at least one symbol for QMemArray::operator[](uint), so you need to apply this patch before Qt compilation.
- If you're using the same Qt source code with other (Borland?) compilers in parallel, you may want to #ifdef out changes made with this patch for non-msvc compilers (e.g. use #ifdef Q_CC_MSVC).
- Configure and install Qt as is required by your Qt package.
If you are planning to compile Qt, you can use either GUI installer shipped with Qt or select "Skip Build Step" (in the 4th Step of the installer) and after installation finished -- compile Qt by hand using build.bat script. Refer to 'Install' files installed in your Qt directory.
Notes:
- Step 4 ("Choose options"): By default, GUI installer proploses C:\Qt\3.3.3 as Qt destination path. You can change this but don't use spaces in the path, otherwise you will encounter ugly problems later. You need to choos your favourite directory with enough space, because you won't be able to easily move it to other location (without digging into Registry).
- Step 6 ("Configure Qt"): In any case, you will need to set following settings: ##todo something else??
- Library: Shared
- Threading: Threaded
- Modules: at least Iconview, Workspace, Xml, Canvas, Network
- Turn on RTTI option (Runtime Type Information) - this allows to use things like <dynamic_cast>; frequently used in KDElibs; otherwise your binaries will crash
- It's also preferred to set Build to Debug (you can also build release version later)
- You can leave all options in General tab as proposed by the installer
- Finally, after configuration you will end up with settings saved in qmake.cache and .qtwinconfig files in your $QTDIR. .qtwinconfig is a file that is included by qmake by default. My .qtwinconfig contain settings:
CONFIG+= shared thread debug exceptions rtti
- If you're configuring and compiling Qt using command line, do not use Cygwin bash shell (you can use it for later developemnt, but not this time, because Qt compilation depends on win32's way of handling path names)
Required steps after Qt installation
- Update plugins paths for Qt Designer. By default Qt Designer has only set plugins path to $QTDIR/bin. To handle KDE widgets by Qt Designer and by uic, you need to add $QTDIR/plugins directory to the list. To do so, run Qt Designer, click Edit->Preferences in menu, in General tab append $QTDIR/plugins line in 'Plugin Paths' text box (replace $QTDIR with proper value) and click OK. After succesful KDElibs compilation, kdewidgets plugin will be added. Then, start Qt Designer again and you should see Display(KDE), Buttons(KDE) and similar tabs visible in the Toolbox.
- Note that if Qt Designer and uic couldn't see kdewidgets plugin, compiling code using .ui files containing KDE widgets won't work.
- Install Cygwin (http://www.cygwin.com/) toolset: Linux-like environment for Windows. Install at least bash, grep and sh-utils. Working on command line is far more comfortable using bash, comapred to cmd.exe :). Notes:
- Cygwin is currently required on compile time for KDElibs/win32 and for development using it, but _not to run applications using KDElibs/win32_. No cygwin's source code is used in KDElibs/win32, so there're no licensing issues.
- Using MSYS (http://www.mingw.org/msys.shtml) instead of Cygwin is probably possible, but not extensively tested.
Optional steps after Qt installation
After Qt installation, you can perform following optional steps to make development more comfortable:
- For msvc compilers only: disable ugly LNK4006 (http://h18009.www1.hp.com/fortran/docs/vf-html/rterr/rtlnk6.htm) and LNK4088 (http://h18009.www1.hp.com/fortran/docs/vf-html/rterr/rtlnk8.htm) linker warnings. There no simple switch we can add. Following is my add-once-and-forget solution:
- create 'link.sh' shell script file, containing:
link.exe $* | grep -v LNK4006 | grep -v 4088
- save 'link.sh' to a directory that is listed in your search path
- locate qmake.conf file in your $QMAKE/mkspecs/$QMAKESPEC directory ($QMAKESPEC is msvc.net for msvc7 compiler, other are win32-borland, win32-g++ and win32-icc, see PLATFORMS file in your Qt directory)
- edit this file, replacing following line:
QMAKE_LINK = link
with:
QMAKE_LINK = bash.exe link.sh
- now, on every link time (assuming you are using QMake-generated Makefiles), the warnings will be filtered out.
@ TODO
Using Subversion repository
Note: KDE project no longer uses CVS (https://www.cvshome.org/) version control system. Subversion is used instead, often mentioned as SVN, in short.
It's suggested that you should use Subversion for your own projects to stay platform-agonstic. To retrieving, updating (and even sending) a code to Subversion server, you will need a Subversion client program.
You can get win32 binary here:
http://subversion.tigris.org/project_packages.html#binary-packages
Using Subversion client is quite similar to use CVS, just replace 'cvs' with 'svn'. See ((KDE Subversion HOWTO)) for information how to use it.
Note: If you have a KDE Subversion account you will have to specify a user name using it, eg.
svn --username=myname ci
This can be inconvenient, so there's a hack: add
alias svn='svn --username=myname'
to your .bashrc file in $HOME directory. Note that commands like 'svn add foobar' will not work in such situation, so you may want to type 'svn.exe add foobar' instead.
See also: Anonymous SVN info (http://developer.kde.org/source/anonsvn.htm), KDE SVN Tutorial (http://developer.kde.org/documentation/tutorials/subversion/) and this faq section (http://developer.kde.org/documentation/other/developer-faq.html#q1.5.2).
Useful tweaks for compilers
- msvc7+ only: Make sure you've set Unix line endings if you're using msvc's code editor: go to File->Advanced Save Options; set Line Endings as "Unix (LF)".
- Note1: "Current settings" is the default and works either for your KDE applications and strict-windows -based sources (line endings are preserved) but newly created files have windows line endings :(.
- Note2: this is not available for msvc6 (but we're not using this, right?).
- Note3: always use Unix (LF) line endings for KDE applications, especially if you're using CVS. This is a portability requirement.
- @todo: what about other compilers, eg. Borland?
- msvc only: How to Not Step Into Functions using the msvc Debugger (http://weblogs.asp.net/andypennell/archive/2004/02/06.aspx)
Get KDElibs/win32 source code
Currently the only solid way to prepare build environment for KDE applications development is to get source code and compile it. This will probably change in the future and you will be able to download precompiled binaries.
Most of KDElibs/win32 source code is shared with all other targets (UNIX and, in the near future, MAC OS X).
Using cvs tool (preferably - command line), download kdelibs source code as described here (http://developer.kde.org/source/anoncvs.html). of course, use your own KDE CVS account if you have one.
Note1: alternatively, you can download and extract a source tarball with recent KDElibs/win32 files (NOT AVAILABLE YET).
Note2: better put KDElibs source code in a dir which has no space (" ") within its path name.
Get KDE runtime files
Currently, KDElibs/win32 does not install all files needed in your $KDEDIR. You need to download a tarball:
http://www.kdelibs.com/files/kde_runtime.tar.bz2
(containing necessary .desktop, .rc and .la files copied from my Linux partition) and extract it to a directory of your choice. Choosing top directory, like C:\ is recommended. For example, if you picked C:\, in the documentation below we will refer to C:\KDE as $KDEDIR.
After getting $KDEDIR files you can find there:
kde/lib/
kde/lib/kde3/
kde/lib/kde3/plugins/
kde/lib/kde3/plugins/styles/
kde/lib/kde3/plugins/designer/
kde/share/
- .la files in $KDEDIR/lib/kde3/ needed by loadable module manager (e.g. kgzipfilter.la points to kgzipfilter_d.dll module). Note: it's planned to drop .la files dependency on win32 in the near future.
Note that there's no kde/include/ directory. Header files are kept within KDElibs source code tree.
Set environment variables related to KDElibs/win32
1. Most important environment variables
In source code tree you just downloaded: Go to kdelibs/win/tools directory and copy kde_env_custom.template to kde_env_custom. This file will contain your global settings file. Edit kde_env_custom file:
- change $MSVC to MSVC instalation directory, eg. MSVC="c:\\vs7"
- change $KDEDIR - top KDE Directory - target of your compilation. eg. KDEDIR=c:\\kde
- change $KDEWIN to KDElibs/win32 your KDE directory with source codes (note: this is not $KDEDIR!)
Note1: kde_env_custom script is included by kde_env script, so having kde_env_custom adjusted to you needs as described above, kde_env script will automatically set KDELIBS="$KDEWIN\\kdelibs" for you.
Note2: You may also need to add more environment variables here if you wish. E.g., for KEXI development, I am exporting KOFFICE="$KDEWIN\\koffice" and KEXI="$KOFFICE\\kexi" variables. Note that we need to use double "\\" characters and win32-like driver letters, eg. "c:\\blah" as both cygwin and QMAKE (http://doc.trolltech.com/3.3/qmake-manual.html) will recognize that.
Note3: build_kdelibs_dbg or build_kdelibs_rel scripts you will use later to build kdelibs, are running special .copy_missing_headers script. It is used to copy: ctype.h, signal.h, stdlib.h, string.h header files from your compiler's include/ directory to your $KDELIBS/win/msvc directory and copy fcntl.h, sys/stat.h, sys/types.h to your $KDELIBS/win/sys/msvc directory (it will be extended for Borland compiler in the future as well). That's weird but required to transparently patch these files (and yes, win32 still has no symlinks!).
2. Use windows' "System properties" GUI dialog window to update your global environment variables. This dialog is available within the Control Panel > System. Go to "Advanced" tab of the window and click "Environment variables.." button.
2.1. In "Environment variables" dialog window update PATH environment variable. This is PATH environment variable available globally in your system. You want to update it to be able to run your KDE applications by just clicking on .exe files. It's especially important that you set PATH variable - setting it within cygwin can be broken.
- Add there a full path to your kdelibs\win\tools directory (this will provide you global acces to KDElibs/win32 helper scripts). Note1: Don't use % KDEWIN % in this path unless you've defined KDEWIN variable using the GUI as well! Note2: use "\" here, not "/".
- Add there a full path to your $KDEDIR\bin and $KDEDIR\lib directory, what enables you to run kde apps and use KDE libraries. See Note1 and Note2.
Note:: Don't use variables inside values in "System properties" GUI , i.e. adding %KDEDIR%\lib to path won't work well, at least in Windows 2000. Replace %KDEDIR% with actual value of this variable, adding eg. "D:\kde\lib".
Note2:: Use ";" as paths separator for PATH, LIB or INCLUDE variables in "System properties" GUI, not ":".
2.2. In "Environment variables" dialog window add "KDEDIR" environment variable to the value you defined it previously. See Note1 and Note2.
3. Note for hackers: Later you may want to create more versions of setting scripts, to alter some of your settings, eg. while using different versions of KDElibs - you can then easily jump from one set of settings to another by just running another bash shell and type "source mycustomscript".
4. Test your environment.
Run a new instance of cygwin bash shell and type:
$ . kde_env
or
$ source kde_env
this will set required environment variables to values you defined above. You need to perform this step everytime you're running a new instance of cygwin bash shell.
Note: (making you life easier) you may want to add ". kde_env" line to your .bash_profile file (create one if it doesn't exist) in you win32 home directory, e.g. in c:\documents and settings\yourloginname\. Cygwin bash shell will invoke this script everytime you 're running a new instance of it.
To test if there's nothing bad with your configuration, type:
$ kmoc
This shouldn't show any error - just should return immediately. You can also use .check_kde_env internal script to check if you have environment variables correctly defined (.check_kde_env should output nothing in case of success).
Adding 3rd-party libraries
1. zlib. Currently, kio and gzip kioslave depends on [zlib library|http://www.zlib.net/]. You have three possibilities to meet this requirement:
- Typical: use zlib bundled with Qt, if you compiled in zlib support there. If you still have Qt source code available, $QTDIR/src/3rdparty/zlib/ contains zlib source code. All you need are zlib.h aand zconf.h headers.
- Download fresh zlib source code from http://www.zlib.net/, unpack it to $KDELIBS/win/3rdparty/zlib/ (so $KDELIBS/win/3rdparty/zlib/zlib.h should exist) and compile it here. MSVC makefile is prepared as win32/Makefile.msc).
- Download fresh zlib binaries. Copy:
- zlib1.dll and lib/zdll.lib to $KDEDIR/lib/
- include/zconf.h and include\zlib.h to $KDELIBS/win/3rdparty/zlib/
2. bzip2. It's needed for bzip2 kioslave. Get the sources or binaries from http://sources.redhat.com/bzip2/#bzip2-latest , unpack to $QTDIR/src/3rdparty/bzip2/ and analogically as you've done with zlib, copy:
- libbz2.dll and libbz2.lib to $KDEDIR/lib/
- bzlib.h to $KDELIBS/win/3rdparty/zlib/
Building KDElibs
Within your cygwin bash shell window, go to your KDEWIN/kdelibs/ directory by entering (substitiute PATH-TO-KDEWIN with your kdelibs source path):
$ cd $KDELIBS
Type:
$ build_kdelibs_dbg
This should build a debug version of kdelibs/win32 . Please report any problems.
Using debug version of KDElibs/win32 is highly recommended at this stage, however if you want, use build_kdelibs_rel for release version.
What do we have after compilation?
- debug version of a library file is compiled in a form of xxxx_dvvvv.dll where xxxx is a base name, vvvv is detailed version number; examples: kdecore_d340.dll, dcop_d340.dll
- release version of a library file is compiled in a form of xxxx_vvvv.dll; examples: kdecore_340.dll, dcop_340.dll
- debug version of a loadable module is compiled in a form xxxx_d.dll, i.e without version number.
- release version of a loadable module is compiled in a form xxxx.dll, i.e without version number.
Notes:
- Don't mix debug and release version of your libraries - this will lead to unrecognizable errors on link- and runtime.
Installing KDElibs
There's no install stage for kdelibs/win32.
- shared libraries are just compiled to $KDEDIR/lib/ directory
- loadable KDE modules are compiled to $KDEDIR/lib/kde3/ directory
- applications are compiled to $KDEDIR/bin/ directory
You've previously added values of $KDEDIR/bin and $KDEDIR/lib to global system PATH environment variable, so libraries and binaries should be properly found "out of the box".
{Re}building system configuration cache (KBUILDSYCOCA)
KBUILDSYCOCA is an application that asks KDE System Configuration (KSyCoCa) system to rebuild information about current system configuration, including services (eg. plugins, extenstions, supported image formats, virtually everything that is built as a KDE module and resides in $KDEDIR/lib/kde3/ directory), available settings, etc. On linux, updates are performed by a special daemon, on win32 we've not ported it and thus you need to remember that:
- set the following option in $KDEDIR/share/config/kdeglobals file, to avoid error messages when KSyCoCa tries to use network:
[General]
ignoreDCOPFailures=true
- after successfull kdelibs build, you have kbuildsycoca.exe command-line application (in debug mode it prints lots of cypring debugging information) and kbuildsycocaw.exe (notice "w" at the end - this is GUI version of kbuildsycoca.exe, which kindly asks if you really want to refresh KDE configuration cache, then performs the action and displays a confirmation dialog). kbuildsycocaw.exe is recommended to use most of the time, since it's easier to see if everything went ok.
- You need to run kbuildsycoca (or kbuildsycocaw.exe) every time you want to reload your configuration. Don't forget to run it:
- after fresh compilation (or recompilation) of kdelibs
- when you've just compiled (or copied/downloaded a binary of) a new KDE module that needs to be visible for KDElibs
Compiling test applications
Now you have your fresh KDE libraries but no GUI apps were compiled (except trivial KBUILDSYCOCA) so you're probably still hungry (:smile:).
Your first test could be small to compile KFind and KTip apps from kdebase. Download them as a kdebase tarball (http://download.kde.org/download.php?url=snapshots/kdebase.tar.bz2) or from the Subversion repository (kdebase/ module). You won't get .pro files for them within CVS nor tarball, but you can find them here (save them to appropriate directories):
kdebase/kfind/kfind.pro (http://www.kdelibs.com/files/kdebase/kfind/kfind.pro)
kdebase/ktip/ktip.pro (http://www.kdelibs.com/files/kdebase/ktip/ktip.pro)
kdebase/common.pro (http://www.kdelibs.com/files/kdebase/common.pro)
KFind is currently not fully functional due to network and kioslaves problems (this needs some work). KTip should work perfectly.
Looking at these .pro files you can learn how to build you own KDE apps.
Support for KDE Widgets in Qt Designer
After succesful compilation of kdelibs, kdewidgets.dll should be visible within $QTDIR/plugins/designer directory. Note that this widget factory is needed to when you compile code containing .ui files that use KDE classes. Without the factory, #include <somekdewidget.h>will not work.
Have fun!
Jaros??aw Staniek
