Gentoo KDE Guide

1.  KDE 3

Quick Information

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.

In Gentoo, KDE 3 ebuilds have been removed from the Portage tree, and they have been moved to the user-maintained overlay called kde-sunset (available in layman). Keep in mind that this overlay is user-maintained only, and current KDE team members have no responsibility for its content. If you are interested in co-maintaining it, you can send an email to overlays asking for commit access. If you want to report a bug about this overlay, please don't file a bug in Gentoo's Bugzilla. Instead, use the gentoo-desktop mailing list. Instructions on how to subscribe can be found here.

2.  KDE SC 4

Introduction

KDE SC 4 is the current KDE version supported by upstream. In Portage there is a stable version, and there might be one (or more) non-stable versions. Under normal conditions new versions get in stabilized after a month. In addition, KDE upstream provides live git source repositories. The Gentoo KDE team provides trunk and latest branch live ebuilds through the kde overlay.

Choose what KDE SC version is most appropriate for you:

3.  Prerequisites

Desktop profile and subprofiles

Desktop profile has been split to KDE and GNOME subprofiles. This means that KDE and GNOME specific USE flags have been stripped from the basic desktop profile and have been migrated to the subprofiles. Choosing a subprofile doesn't restrict you to use only the equivalent DE. In order to choose the profile that suits you, run eselect profile list to get the profiles' list, and eselect profile set X, where X is the appropriate number.

Use flags

Before you install KDE SC it is recommended that you set several useflags. Part of that is done automatically if you use a desktop/kde or desktop profile. In detail you should use:

Note that other combinations may technically be possible, but may be unsupported, untested, or lead to unexpected loss of functionality.

If you changed any global useflags, you should later include the -N flag when running the actual emerge command which updates your system, e.g.

# emerge -uDNav world

Kernel settings

If you are rolling your own kernel, you'll want to install a new one with the following options:

CONFIG_USB_SUSPEND=y
CONFIG_IDE=n
CONFIG_AUDITSYSCALL=y

4.  Installing KDE SC from Portage

KDE SC 4.7

KDE SC 4.7.4 is the current stable release for amd64, ppc and x86.

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

KDE SC 4.8

KDE SC 4.8.1 is under stabilization and already stable for amd64 and x86. KDE SC 4.8.3 is in portage, currently as ~testing, but stabilization is planned for the near future.

Users with stable systems need to put this keywords file in /etc/portage/package.keywords.

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

5.  Installing KDE SC from Overlay

Prerequisites

Installing snapshots and live ebuilds are only available through kde overlay, so first thing is to install it:

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

Installing KDE SC snapshots

During testing phases KDE upstream provides snapshots taken from the git source repositories. Beta and Release Candidate KDE releases are following the snapshot model below:

Installing KDE SC live ebuilds

KDE SC is Open Source, with its code being available for browsing through KDE QuickGit, and for public checkout. 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.8.49.9999 ebuilds from 4.8 branch and 9999 ebuilds from trunk.

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

# cd /etc/portage/package.keywords
# ln -s /path/to/overlay/kde/Documentation/package.keywords/kde-4.8.49.9999.keywords .(for 4.8 Branch)
# ln -s /path/to/overlay/kde/Documentation/package.keywords/kde-live.keywords .(for KDE Trunk)

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

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

(For KDE SC 4.8 Branch)
# emerge -av @kde-4.8 (contains all of KDE modules)
# emerge -av @kdebase-4.8 @kdegames-4.8 (installation of chosen modules only)
(For KDE SC 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.

6.  Additional Installation/Removal Information

Using Sets

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 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.

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, so you can reinstall all installed packages of a set with emerge -av @<set>/@installed 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.

# emerge @kdebase @kdegames

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 the Portage version)
• Fully upgrading from KDE 3 to KDE 4 (and vice versa)
• Moving from an old overlay

A possible way of completely removing an old KDE installation in this case is:

# emerge -ac kde-base/kdelibs $(qlist -IC 'kde-base/*') \
             $(for name in $(qlist -IC|grep -v '^kde-base/') ; do (  qdepends -C $name | grep -q kdelibs )  && echo $name  ; done)

Note that this will remove not just kde but also all other packages depending on it, as e.g. libreoffice[kde].

Using portage-2.2 you can also do the following:

# emerge -C @kde-4.X @kdebase-4.X @kde-3.5(using the typical sets)

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

Localization/Internationalization

With new KDE there is new translators effort in Localization instead of Internationalization. This cause some confusion, but don't worry; just the name has been changed.

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

Migrating configs from 3.5 to 4.X

KDE stores its configuration files in the ~/.kde directory by default. In the Gentoo ebuilds this has been changed in KDE 4.X 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.

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:

$ 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.

7.  Hints and Troubleshooting

Get rid of the KResource Migration Tool popup

There have been reports that the KResource Migration Tool pops up on every login. There is no proper solution yet for this, but you can see a workaround in bug 353200.

Rebuilding the application database

If your KMenu lacks any application or the whole application list, you probably need to rebuild the KDE application database. It is also a possible fix for any KMenu related issues, like missing icons.

# kbuildsycoca4 --noincremental

Make GTK applications look like Qt 4 ones

There are two themes available which look the same under both toolkits (GTK/Gnome and Qt/KDE): "QtCurve" is provided via packages gtk-engines-qtcurve and x11-themes/qtcurve-qt4, "Oxygen" is part of KDE 4.x, its GTK counterpart is provided via package x11-themes/oxygen-gtk. KDE themes can be configured via KDE's System Settings under "Appearance" in tab "Style". In order to configure the theme of GTK applications from within KDE's System Settings, install kde-misc/kde-gtk-config to get a new tab "Gtk Config" under "Appearance".

Akonadi complains about the MySQL config

Start by checking the permissions in /usr/share/config and /usr/share/kde4. If they're 700, you need to update them to 755 recursively.

# chmod -R 755 /usr/share/{config,kde4}

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 embedded executable, you'll need to ensure that mysql is running.

Make KDE start on boot

There are two ways to make KDE start on boot. The easiest way is by using the KDM, which is available at kde-base/kdm. First we edit the Xorg Configuration file, so that DISPLAYMANAGER is set to "kdm":

# What display manager do you use ?  [ xdm | gdm | kdm | kdm-4.3 | gpe | entran$
# NOTE: If this is set in /etc/rc.conf, that setting will override this one.
#
# KDE-specific note:
# - If you are using kdeprefix go with "kdm-4.Y", e.g. "kdm-4.3".
#     You can find possible versions by looking at the directories in /usr/kde/.
# - Else, if you are using KDE 3 enter "kdm-3.5"
# - Else, if you are using KDE 4 enter "kdm" without a version
DISPLAYMANAGER="kdm"

Next step is to add xdm to default runlevel:

# rc-update add xdm default

Fonts suggestions

If you click to view the menu and notice that there is nothing legible, you need to install some fonts. Some common choices are media-fonts/corefonts, media-fonts/ttf-bitstream-vera and media-fonts/dejavu.

KDM fails to start

Start by checking the permissions in /usr/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:

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.3.1/CONTENTS | cut -f2 -d " ""
and be sure to increase the timeout - 60 should work

Also be sure that the following services are started:

# /etc/init.d/dbus 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 /etc/X11/xorg.conf. Take a look in your 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 consolekit running.

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

Double-hibernate or crashes after hibernate (bug 363363)

KDE 4.6 handles "sleep button" events on its own, and the system correctly hibernates. If you have manually set up any other programs to handle these events (e.g. acpid), please disable that, as you may otherwise get double hibernation and/or system instability.

Shutdown, reboot, logout does not work (bug 326393)

There is some strange interaction between the sound system and the logout mechanism going on. Open systemsettings, and disable the "logout sound". Afterwards, logging out will likely work.

The desktop background covers all windows (bug 365623)

In rare cases, after working with several screens the desktop settings are not cleaned up properly. The result is that the desktop background seems to cover all windows. More details plus some manual workarounds can be found in this KDE bug report.

No login possible, hangs at splash screen (bug 365637)

If you have been playing with unstable Gnome stuff (naughty!) you may encounter a so-far unexplained incompatibility. Logging in to KDE fails as soon as net-libs/glib-networking is installed. Unmerge that package and you should be fine.

8.  Archive

Upgrade from KDE SC 4.4 to 4.6

KDE SC 4.6.3 is currently stable. If you encounter problems during the upgrade from KDE SC 4.4, please have a look at the separate Gentoo KDE 4.4 - 4.6 Upgrade Guide first!

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.