In order to minimize issues, it is best to begin with a clean enviroment. You will need to uninstall any beta or 4.0.X releases (this is needed if you are moving from any overlay and in particular if you plan to use the -kdeprefix USE flag - FHS install). Two possible ways of removing old KDE 4 installations are:

# emerge -C @kde-4.1 @kdebase-4.1 (only if you are coming from the kdesvn-portage or kde-testing overlay)
# emerge -C $(qfile -C -q -e /usr/kde/%PREFIX%) (replace %PREFIX% with your KDE version, eg. 4)

# cd /path/to/old/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.

# layman -fS; layman -a kde-testing

# git clone git://git.overlays.gentoo.org/proj/kde.git /PATH/WHERE/TO/PUT/OVERLAY

The KDE 4.1 ebuilds are no longer masked so you won't need to use the package.unmask file to be able to install them. If you're running ~arch and don't want to update to 4.1, you can use the package.mask file from Documentation/package.mask/kde. If you are running the stable tree you will need to keyword the ebuilds, otherwise skip this step. For those running the stable tree in Gentoo:

This overlay provides an appropriate package.keywords file that can be used in your package.keywords file/directory. You can find this file in "Documentation/package.keywords" directory. Copy it to the correct location "/etc/portage/package.keywords/" (preferably make a symlink to it), or add it to your "/etc/portage/package.keywords" file. Perform one of the following steps, depending on whether your /etc/portage/package.keywords is a directory or a file:

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

# cd /etc/portage/
# cat /path/to/overlay/Documentation/package.keywords/kde >> package.keywords 

# cd /path/to/our/overlay/
# find ./ -name \*.ebuild |sed -e "s:.ebuild::" -e "s:./::" |awk -F'/' '{print $1"/"$2}'  >> /etc/portage/package.keywords/kde4x
# cd /usr/portage/
# find ./x11-libs/qt-* -type d |sed -e "s:./::" |awk -F'/' '{print $1"/"$2}' | uniq >> /etc/portage/package.keywords/kde4x

# cd /path/to/our/overlay/
# find ./ -name \*.ebuild |sed -e "s:.ebuild::" -e "s:./::" |awk -F'/' '{print $1"/"$2}' >> /etc/portage/package.keywords
# cd /usr/portage/
# find ./x11-libs/qt-* -type d |sed -e "s:./::" |awk -F'/' '{print $1"/"$2}' | uniq >> /etc/portage/package.keywords

The new 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.1 and 4.2.

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

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

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.

# emerge @kdebase @kdegames

# emerge kde-meta:4.1

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.

# emerge kde-l10n

# emerge kde-i18n

KDE stores its configuration files in the ~/.kde directory by default. In the Gentoo ebuilds this has been changed in KDE 4.1 to allow for better integration of KDE 3.5 and 4.1 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.1 use the same configuration directory which is usually not desired.

KDE 3.5 uses ~/.kde and the default FHS (-kdeprefix) KDE 4.1 uses ~/.kde4. If you install KDE 4.1 using the kdeprefix USE flag then the configuration directory will default to ~/.kde4.1, ~/.kde4.2 etc. The advantage of this is that KDE 3.5 and 4.1 can be run from the same user account without clobbering settings. Moving backwards in version, i.e. 4.1 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,

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

If you used the kde-testing overlay before the testing branch was merged back into the master overlay, you're going to get collision-protection errors when you try to update; the new ebuilds will show up as belonging to a new slot [NS]. This is caused by a move from the 4 to 4.1 SLOT. You have 2 choices in this case:

# emerge -C @kde-4.1

Changing the SLOT in the VDB may cause issues and is not recommended -- do it at your own risk. You should instead do the above. If you really want to do that, please grab the script from the kde-testing overlay. You should only run it if you understand what it does and after you double checked it.

# change_slot kde 4 4.1
# (After you confirm that it works as expected (you should see SLOTS as 4.1 and not 4))
# change_slot kde 4 4.1 Y

# emerge -C @kde-3.5

KDE 4, as it moves towards a semantic desktop, did not bundle an icon for the desktop.

The desktop icon can be replaced with the standard folder icon using the following command.

$ sed -i -e "s:Icon=desktop:Icon=folder:g" ~/Desktop/.directory

When you occur with this bug try first this command before opening bug.

# emerge -1 kdebase-data && emerge -1 hicolor-icon-theme kdebase-data

Plasmoids are new plasma tools which can enhance your desktop experience to brand new level. We created kde-plasma/ section where we place every plasmoid 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.

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

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.

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.

If you get an error building kitchensync or some other package about configure being unable to find libopensync-0.30, be sure to either upgrade to the latest testing version or to downgrade and mask the 9999 version. You can read more about this in bug 240370.

If you are interested in getting flash working in konqueror point your mind to guide which describes necessary steps for getting it done.

In order to remove all KDE 4 packages and dependant packages:

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

To rebuild the KDE 3 application database run:

# kbuildsycoca --noincremental