Gentoo Logo

Gentoo KDE Guide

Content:

1.  KDE 3

Introduction

KDE 3 is no longer maintained by upstream, with 3.5.10 being their last release. Also, most KDE 3 applications aren't maintained any more, as they already have been or are currently being ported to KDE 4. The Gentoo KDE Team, provides both KDE 3 and KDE 4 ebuilds for the base KDE and for various applications, and supports a side by side full desktop installation of KDE 3 and 4, including misc KDE applications. Our advice is for you to install and use by default a full KDE 4 desktop, and use only the KDE 3 applications that you feel have yet to be propperly ported to KDE 4 (due to missing features, random crashes etc).

Warning: Keep in mind that since KDE 3 isn't maintained by upstream any more, it is possible and likely that bug reports concerning KDE 3 applications may not be fixed, but rather closed as WONTFIX / CANTFIX / UPSTREAM, or instead kept open for a long time until a fix (patch) is provided.

KDE 3 Stabilization

Currently 3.5.9 is marked stable on all architectures (with stable keywords), while 3.5.10 is in the process of stabilization (see bug 271889) - it is already stable on the amd64 and x86 arches.
KDE 3.5.10 uses only split ebuilds, meaning that users of monolithic ebuilds (like kdebase, kdepim, kdegames etc) must unemerge them manually and then proceed with the installation of KDE 3.5.10 as described below. KOffice 1.6.3 is also in the progress of stabilization, and the last version includes only split ebuilds. So, users of monolithic KOffice should also unemerge it manually and emerge koffice-meta-1.6.3_p20090204.

The team is also cleaning up the various KDE 3 applications, either by removing them from the tree, if they are too old, broken and unmaintained, or by stabilizing the latest version after moving the SLOT to :3.5. (bug 270945), and dropping arts support (with major help from Media/Video teams). When this task is finished, we are going to drop arts from base KDE 3 as well.

KDE 3.5.10 Installation

The installation of KDE 3 can be done either by using the meta packages (kdebase-meta, kdepim-meta, kde-meta) or by using the sets. As stated before, users of monolithic 3.5.9 ebuilds that want to update to 3.5.10 and get strange blocks, should manually unemerge monolithic 3.5.9 ebuilds (kdebase, kdepim, kdegames etc) and emerge 3.5.10 as explained below. For installation using meta packages:

Code Listing 1.1: Installation of KDE 3 using meta packages

# emerge -av kde-meta:3.5 (contains all of KDE modules)
# emerge -av kdebase-meta:3.5 kdegames-meta:3.5 (installation of chosen modules only)

Note: Installation of KDE 3 can be done in parallel with KDE 4, because both use different eclasses, thus different slotting and prefix, so they don't affect each other. kdeprefix USE Flag for KDE 4 (explained later) has nothing to do with KDE 3/4 mixed installations.

For installation using sets check the Using Sets section.

In case KDE 3.5.10 isn't marked stable in your architecture yet (or you are using ~mips or ~x86-fbsd, that don't provide stable keywords any more), we provide a package.keywords file in kde-testing overlay under Documentation/package.keywords directory.

Code Listing 1.2: Adding the file to the package.keywords file

# cd /etc/portage/
# cat /path/to/kde-3.5.keywords/file >> package.keywords

Code Listing 1.3: Adding the file to the package.keywords directory

# cd /etc/portage/package.keywords
# cp /path/to/kde-3.5-keywords/file .

Installation of KDE 3 Applications

As stated before, KDE 3 Applications are slotted as :3.5, which allows users to have them installed along with the KDE 4 equivalents, just like in the base applications. For better administration of your system, you could take full advantage of slots and use slotted package selections in your package.keywords and world file. For example:

Code Listing 1.4: Installation of KDE 3 application

# echo "app-cat/application:3.5" >> /etc/portage/package.keywords[/<file>]
(in case the KDE 3 application is still keyworded as testing)
# emerge -av application:3.5

The same rules apply for KDE 4 applications, which are slotted as :4. This way, the emerge and removal of an application can be easily done without conflicts, blocks, or unwanted removals.

2.  KDE 4

Introduction

KDE 4 is the current KDE version supported by upstream. The current KDE 4 version available through portage is 4.2.4 (this version is considered stable by upstream). In addition, KDE upstream provides weekly snapshots, and a live SVN tree. The Gentoo KDE team provides the snapshots, trunk and latest branch live ebuilds, through the kde-testing overlay. To enable this, the user can have multiple parallel KDE 4 installations, with the use of the kdeprefix USE flag.

Choose what KDE version is most appropriate for you:

KDE from Portage (currently 4.2.4)
KDE snapshots (currently 4.2.X)
KDE live ebuilds

The kdeprefix USE flag

Warning: The kdeprefix USE flag is currently masked. It's unsupported and shouldn't be used by users in any way. Use at your own risk. Read bellow for the reasons that led to the masking of the USE flag.

The kdeprefix USE flag allows users to choose between an FHS compliant install (-kdeprefix) or a slotted install in the KDE prefix (+kdeprefix).

If kdeprefix is disabled (default) KDE is installed into the FHS compliant location, i.e. /usr. That means that all of the files are put under /usr. This is the desired behaviour for most users. The drawback of the FHS compliant install is that it will not be possible to have more than one minor version of KDE side by side (previous behaviour), e.g. KDE 4.2 and 4.3.

Note: This restriction does not apply to KDE 3 (which uses different prefix (/usr/kde/3.5)). You can have KDE 3.5 with either -kdeprefix or kdeprefix KDE 4.X in the same system.

Warning: Mixing a +kdeprefix and a -kdeprefix KDE installation is not supported, nor recommended. If you really want kdeprefix in your system, you'll have to unmask it and put it globally in /etc/make.conf

If kdeprefix is enabled then KDE is installed into /usr/kde/${SLOT}, which allows you to install KDE 4.2, 4.3, live etc. in /usr/kde/4.2, /usr/kde/4.3, and /usr/kde/live for example.

Warning: If you want to move between kdeprefix and -kdeprefix (or vice-versa), it is recommended that you unmerge all KDE packages and then emerge it with the modified flag. If this is not done, KDE installations can have trouble finding certain libraries/plugins. Check Cleaning Up KDE for more details.

Recently kdeprefix got masked by default, as it caused many problems, like collisions between the same packages when having two or more KDE installations, or strange behaviour even when only one +kdeprefix KDE installation was present in the system. Great examples of packages with such problems are pykde4 and amarok. Since the Gentoo KDE Team decided to proceed with the stabilization of KDE 4 (KDE 4.2.4 being the best candidate at this moment), those issues needed to be resolved first. As it was difficult to fix them, we decided to mask the use flag instead. If you really know what you are doing and you are sure that you want kdeprefix unmasked and enabled in your system, please read the portage manpage to unmask it, and add it globally to /etc/make.conf.

Installing KDE 4.2.4 (from Portage)

KDE 4.2.4 is the KDE 4 version that Gentoo has in Portage - it's considered by upstream as the latest stable. Currently it's in the testing branch in Portage, but in June's meeting the Gentoo KDE Team decided to move forward with KDE 4 stabilization - 4.2.4 being the best candidate.

Note: In order to minimize issues it is recommended to start with a clean environment. Read more in Cleaning Up KDE section.

Users with stable systems have to keyword the packages to proceed. We provide a package.keyword file in kde-testing overlay under Documentation/package.keywords/ directory.

Code Listing 2.1: Adding the file to the package.keywords file

# cd /etc/portage/
# cat /path/to/kde-4.2.keywords/file >> package.keywords

Code Listing 2.2: Adding the file to the package.keywords directory

# cd /etc/portage/package.keywords
# cp /path/to/kde-4.2.keywords/file .

The installation can be done either by using the meta packages or by using sets.

Code Listing 2.3: Installation of KDE 4.2.4 using meta packages

# emerge -av kde-meta:4.2 (contains all of KDE modules)
# emerge -av kdebase-meta:4.2 kdegames-meta:4.2 (installation of chosen modules only)

For installation using sets check the Using Sets section.

Installing KDE 4.2.X snapshots (from kde-testing overlay)

Warning: KDE snapshots are bleeding edge. Use at your own risk.

KDE upstream provides weekly snapshots taken from the SVN trunk tree. KDE now provides 4.2.X snapshot series, and after 4.3 release they are going to start with 4.3.60. Beta and Release Candidate KDE releases are following the snapshot model bellow:

Snaphot version KDE Version
4.X.85 KDE 4.X Beta 1
4.X.90 KDE 4.X Beta 2
4.X.95 KDE 4.X Release Candidate

Note: In order to minimize issues it is recommended to start with a clean environment. Read more in Cleaning Up KDE section.

Note: You'll need portage-2.2_rc*, so please add ~sys-apps/portage-2.2 entry to your /etc/portage/package.unmask[/*] file.

Snapshots are only available through kde-testing overlay, so you first need to add it:

Code Listing 2.4: Installing kde-testing overlay from layman

# layman -f -a kde-testing
For more information regarding overlays, please read the Overlay Guide

If you're used to git repos, don't want to use layman and rather do all the sync work yourself, you can install the repo directly:

Code Listing 2.5: Installing kde-testing overlay directly

# mkdir /<repo-base-dir>
# cd /<repo-base-dir>
# git clone git://git.overlays.gentoo.org/proj/kde.git

Users with stable systems have to keyword the packages to proceed. We provide a package.keyword file in kde-testing overlay, which we'll have to symlink to our package.keywords directory:

Code Listing 2.6: Creating symlink of the kde-4.3.keywords file

# cd /etc/portage/package.keywords
# ln -s /path/to/overlay/kde-testing/Documentation/package.keywords/kde-4.3.keywords .

Finally, to install them you'll have to use sets, as we don't provide meta packages for snapshots.

Code Listing 2.7: Installation of KDE snapshots using sets

# emerge -av @kde-4.3 (contains all of KDE modules)
# emerge -av @kdebase-4.3 @kdegames-4.3 (installation of chosen modules only)
See the Using Sets section for more information.

Installing KDE live ebuilds (from kde-testing overlay)

Warning: KDE live ebuilds are bleeding edge. Use at your own risk.

KDE is Open Source, with its code being available for browsing throughKDE Websvn, and for public checkout through an anonymous (anonsvn) account. Gentoo, as a source based distro, has the ability to provide live ebuilds that checkout the code either from the latest branch or from trunk. Currently, we provide 4.2.9999 ebuilds from 4.2 branch and 4.3.9999 ebuilds from 4.3 branch, as both are alive. We are going to drop 4.2.9999 ebuilds when 4.3 gets released officially.

Ebuilds version KDE Version
4.2.9999 KDE 4.2 Branch
4.3.9999 KDE 4.3.Branch
9999 KDE 4 Trunk (currently 4.4)

Note: In order to minimize issues it is recommended to start with a clean environment. Read more in Cleaning Up KDE section.

Note: You'll need portage-2.2_rc*, so please add ~sys-apps/portage-2.2 entry in your /etc/portage/package.unmask file.

Live ebuilds are only available through kde-testing overlay, so first thing is to install it:

Code Listing 2.8: Installing kde-testing overlay

# layman -f -a kde-testing
For more information regarding overlays, please read the Overlay Guide

Users with stable systems have to keyword the packages to proceed. We provide a package.keyword file in kde-testing overlay, which we'll have to symlink to our package.keywords directory:

Code Listing 2.9: Creating symlink of the kde-4.X.9999.keywords or kde-live file

# cd /etc/portage/package.keywords
# ln -s /path/to/overlay/kde-testing/Documentation/package.keywords/kde-4.2.9999.keywords .(for 4.2 Branch)
# ln -s /path/to/overlay/kde-testing/Documentation/package.keywords/kde-4.3.9999.keywords .(for 4.3 Branch)
# ln -s /path/to/overlay/kde-testing/Documentation/package.keywords/kde-live.keywords .(for KDE 4.4 Trunk)

Finally, to install them you'll have to use sets, as we don't provide meta packages for live ebuilds.

Code Listing 2.10: Installation of KDE live ebuilds using sets

(For KDE 4.2 Branch:)
# emerge -av @kde-4.2 (contains all of KDE modules)
# emerge -av @kdebase-4.2 @kdegames-4.2 (installation of chosen modules only)
(For KDE 4.3 Branch)
# emerge -av @kde-4.3 (contains all of KDE modules)
# emerge -av @kdebase-4.3 @kdegames-4.3 (installation of chosen modules only)
(For KDE 4.4 Trunk)
# emerge -av @kde-live (contains all of KDE modules)
# emerge -av @kdebase-live @kdegames-live (installation of chosen modules only)
See the Using Sets section for more information.

Note: You may be interested for Qt live ebuilds as well. Check the Qt Guide (TODO) for installation instructions.

Installation of KDE 4 Applications

KDE 4 Applications are slotted in :4, which allows the users to have them installed along with the KDE 3 equivalents, just like in the base applications. For better administration of your system, you could take full advantage of slots and use slotted package selections in your package.keywords and world file. For example:

Code Listing 2.11: Installation of KDE 4 application

# echo "app-cat/application:4" >> /etc/portage/package.keywords
# emerge -av application:4

The same rules apply for KDE 3 applications, which are slotted in :3.5. This way, the emerge and removal of an application can be easily done without conflicts, blocks, or unwanted removals.

In kde-testing you may find live ebuilds of KDE 4 applications. These are slotted in :4 as well, but they can not be installed in parallel with normal ones. You are free though to use live KDE 4 applications with KDE 4 from portage, or to use portage KDE 4 applications with your live KDE.

Note: There is also a set with live KDE 4 applications, @kde-extras-live, in kde-testing and a set with Qt live applications, @qt-extras-live, in qting-edge overlay.

3.  Additional Installation/Removal Information

Using Sets

Warning: Portage 2.2_rcX is currently masked to allow 2.1.6 getting stable asap. So if you want to use sets please unmask ~sys-apps/portage-2.2.

One of the new features provided by Portage 2.2 is sets.

Sets allow the KDE team to provide a complete replacement for the monolithic packages, with the added bonus that users may choose to remove from the default sets any packages they do not want. There is still some discussion going on before we can put sets in the Portage tree. Thus, grab the sets from the kde-testing overlay sets directory or grab them as a tar.bz2 archive and put the ones you like in /etc/portage/sets -- you can browse the list of sets provided by the KDE team in the overlay by using the first link.

Note: In case you are using kde-testing overlay you can use sets directly instead of copying them to /etc/portage/sets.

Amongst others, there are sets for each KDE tarball - @kdeaccessibility, @kdeadmin, @kdeartwork, @kdebase, @kdeedu, @kdegames, @kdegraphics, @kdemultimedia, @kdenetwork, @kdepim, @kdesdk, @kdetoys, and @kdeutils. There is also a set of sets (the equivalent to the old kde-meta package) @kde, and the same for specific versions @kde-3.5 and @kde-4x, a set for KDE deps @kdedeps, a set for optional packages @kdeoptional and a set for the split qt packages @qt-split.

One can install the complete KDE by running emerge -av @kde. The specific version equivalents are very useful to uninstall an old version, e.g. emerge -C @kde-3.5, or to reinstall all packages from a specific version, e.g. emerge -av1 @kde-4x. Advanced features, like removing any unwanted packages from a set, will be supported in a future release of Portage -- you can read more about it in Marius Mauch's (genone) blog. Part of this code has now been released in portage-2.2_rc12 and so you can reinstall all installed packages of a set with emerge -av @<set>/@installled or to have a /etc/portage/sets/kdebase-unwanted set and then run emerge -av @kdebase-@kdebase-unwanted.

We strongly recommend that you install the kdebase set in order to get a full KDE 4 session. The example below would install the kdebase set and the kdegames set.

Code Listing 3.1: Installing KDE

# emerge @kdebase @kdegames

Note: If you want to check the list of sets known to Portage run the following: emerge --list-sets

Note: All >= KDE 4.1 ebuilds require sys-apps/portage-2.1.6 or greater, which has implemented everything in the new EAPI 2 specification used in these ebuilds (>=sys-apps/portage-2.2_rc12 is required to use sets).

Cleaning Up KDE

In order to minimize issues, it is best to begin with a clean environment. This is recommended for the following cases:

  • Moving from +kdeprefix to -kdeprefix (and vice versa)
  • Downgrading KDE (eg. from snapshots/live ebuilds to portage version)
  • Fully upgrading from KDE 3 to KDE 4 (and vice versa)
  • Moving from an old overlay

Two possible ways of removing old KDE installations are:

Code Listing 3.2: Unmerging commands

# emerge -C @kde-4.X @kdebase-4.X @kde-3.5(using the typical sets)
# emerge -C $(qfile -C -q -e /usr/kde/%PREFIX%) (replace %PREFIX% with your KDE version, eg. 3.5, 4)

Code Listing 3.3: Unmerging commands (only applicable if you are moving from an overlay)

# cd /path/to/overlay/
# emerge -C $(find ./ -name \*.ebuild |sed -e "s:.ebuild::" -e "s:./::" |awk -F'/' '{print "="$1"/"$3}')

As a final step you should remove the old overlay so that there are no conflicts with the KDE ebuilds. You should remove the old unmask and/or keyword data, too.

Note: Don't forget to run depclean in order to uninstall any dependant packages.

Rebuilding the application database

To rebuild the KDE application database run:

Code Listing 3.4: kbuildsycoca command

# kbuildsycoca --noincremental (for KDE 3)
# kbuildsycoca4 --noincremental (for KDE 4)

Localization/Internationalization

With new KDE there is new translators effort in Localization instead of Internationalization. This cause some confusion but dont worry your translation is shiped to you, just name has been changed so now for getting translations use theese comands.

Code Listing 3.5: emerge commands for translations

For KDE 4 and KOffice 2:
# emerge kde-l10n
# emerge koffice-l10n
For KDE 3 and KOffice 1.6.3:
# emerge kde-i18n
# emerge koffice-i18n

Configuration of ~/.kde Directory

KDE stores its configuration files in the ~/.kde directory by default. In the Gentoo ebuilds this has been changed in KDE 4.1 and later to allow for better integration of KDE 3.5 and 4.X when using the same user account. If you export $KDEHOME this behaviour will be overridden. It is strongly recommended that you do not do this. $KDEHOME will make KDE 3.5 and 4.X use the same configuration directory which is usually not desired.

KDE 3.5 uses ~/.kde and the default FHS (-kdeprefix) KDE 4.X uses ~/.kde4. If you install KDE 4.1 using the kdeprefix USE flag then the configuration directory will default to ~/.kde4.1, for KDE 4.2 it will be ~/.kde4.2 and so on. The advantage of this is that KDE 3.5 and 4.X can be run from the same user account without clobbering settings. Moving backwards in version, i.e. 4.X to 3.5, is not supported.

Settings are not migrated by default. If you want to attempt to migrate your settings you should copy your old configuration directory to the new location before logging in. For example:

Code Listing 3.6: Copying the configuration directory

$ cp -r ~/.kde ~/.kde4

If this is successful, then your settings should all be migrated. If not, it is possible to log out and remove the new configuration directory to start with a clean configuration directory.

4.  Hints and Troubleshooting

Plasmoids

Plasmoids are new plasma tools which can enhance your desktop experience to brand new level. Many plasmoids are available in kde-misc/ category, on which we get our nasty hands and find it workable enought. If you find out that your favorite one is missing create bug and somebody might create it for you. If you are plasma person "want them all can't live without them" we have set @plasmoids which contains all plasmoids currently availible.

Note: Mostly all plasmoids are currently placed on kde-testing overlay.

x11-themes/plasma-themes

This ebuild contains various plasma themes. The procedure for requesting additional themes is the same as that for plasmoids.

x11-themes/gtk-engines-qt

This ebuild should be used if you want your GTK applications to use a theme similar to the Qt/KDE applications. Configuration can be found in systemsetings->Appearance->GTK Styles and Fonts. For KDE-4.2 you need at least gtk-engines-qt-1.1-r1.

x11-themes/gtk-engines-qtcurve

This is another approach to making GTK/Qt 3/Qt 4 applications looks the same. You must also install x11-themes/qtcurve-qt4 for this to work with Qt 4/KDE 4 applications.

Flash in Konqueror

If you are interested in getting flash working in konqueror point your mind to guide which describes necessary steps for getting it done. Latest www-plugins/adobe-flash (both 32 and 64-bit) should work flawlessly though, maybe you'll need to Scan for Plugins under Konqueror->Settings->Plugins.

Akonadi Complains about the MySQL Config

Start by checking the permissions in /usr/share/config and if you're using +kdeprefix in $(kde4-config -prefix)/share/config. If they're 700, you need to update them to 755.

Code Listing 4.1: updating /usr/share/config permissions

# ls -l /usr/share/config
# chmod 755 /usr/share/config

If that doesn't solve the error, you need to open the akonadi configuration and change the default mysql config. If you don't have the tray running, start akonaditray, select "Akonadi Server Configuration", activate "Use internal MySQL server" and then press the test button. If you want to use the mysql server and not the embbeded executable, you'll need to ensure that mysql is running.

KDM fails to start

Start by checking the permissions in /usr/share/config and if you're using +kdeprefix in $(kde4-config -prefix)/share/config. If they're 700, you need to update them to 755. Check previous section. If that doesn't solve the error, check the following notice in the kdm ebuild:

Code Listing 4.2: kdm notice

If when you restart xdm, kdm fails to start with a message like "gentoo kdm[2116]: X
server startup timeout, terminating" in /var/log/messages, uncomment the ServerTimeout
line in "grep kdmrc /var/db/pkg/kde-base/kdm-4.2.0/CONTENTS | cut -f2 -d " ""
and be sure to increase the timeout - 60 should work

Also be sure that the following services are started:

Code Listing 4.3: checking and starting services

# /etc/init.d/dbus status
# /etc/init.d/hald status
# /etc/init.d/consolekit status

If not, enable them by replacing status with start, and use the command rc-update add dbus default for every one of them to add them to default runlevel.

Finally, KDM could fail due to errors in xorg.conf. Take a look in logs: /var/log/Xorg.0.log and /var/log/kdm.log and fix xorg.conf accordingly. For additional help you can find us in IRC (#gentoo-kde at Freenode).

The battery applet or solid notifications don't show the relevant info

So that the battery applet or other solid notifications can show the relevant info, you need dbus and hald running.

Code Listing 4.4: checking and starting dbus and hald

# /etc/init.d/dbus status
# /etc/init.d/hald status
# /etc/init.d/dbus start
# /etc/init.d/hald start


Print

Updated June 26, 2009

Summary: This guide demonstrates how to setup KDE using the ebuilds in the tree. Some tools from the KDE team's git overlay (kde-testing) will be used.

Theo Chatzimichos
Author

Tomas Chvatal
Author

Jorge Manuel B. S. Vicetto
Author

Marcus D. Hanwell
Author

Tobias Heinlein
Editor

Donate to support our development efforts.

Support OSL
Gentoo Centric Hosting: vr.org
Tek Alchemy
SevenL.net
Global Netoptex Inc.
Bytemark
Online Kredit Index
Copyright 2001-2009 Gentoo Foundation, Inc. Questions, Comments? Contact us.