# HOWTO: Major System Upgrades - Post I - Preparation

## dufeu

Pre-Introduction -1) Huh?!?!?

This is the first of a series four posts describing and walking through the complete process of performing a Major Upgrade on a Gentoo based system. The other posts are:Post II - Initial Upgrades ++ - Initial group of packages to upgrade and more system cleanups to perform.

Post III - World Domination - Bulk of the packages to upgrade.

Post Mortem - Final system cleanups. Loose ends. It's a wrap!

Introduction 0) We State Our Reasons Why

At some point, it seems nearly every Gentoo user is faced with the decision of whether to perform a major upgrade or re-install a PC which hasn't been upgraded for some time. We're not discussing the usual daily or weekly or monthly package maintenance {emerge --sync && emerge -uND world} most of us do on the PCs we actively administer. Rather, "Some Time" means some period such that many of the packages are at least 2 and probably more releases behind. In fact, it means that virtually all the installed packages need to be upgraded.

Such a PC in serious need of upgrading might be a household network server sitting in a closet or squirreled away under a desk running unattended for years. It might be one you put together for your mother/father/grandmother/grandfather/other relative. Maybe it's the one you built for your non-techy spouse/SO/best friend to get them off of their addiction to MS Windows. Now you've finally been able to pry their virus resistant, always running pride and joy from their spasmatic clutches for a long overdue upgrade.

Ultimately, the decision to upgrade or re-install comes down to which will cause the least pain and/or give the best results and/or be quickest and/or least risky. What criteria you use and how you rank their importance is a personal decision. I generally rank risk of loss as most important and length time needed to upgrade as least important.

I've done both many re-installs and many upgrades. The example PC we're going to take through the major upgrade process has been frozen in time for two reasons. The first reason is because I used to use it for work. Given a choice, never, ever break the tools you use to make a living. The second reason is that I knew I needed to co-ordinate the revision levels of nvidia-drivers, the linux kernel, X-windows and vmware-workstation to be sure the resulting revisions of each would all work nicely together.

I've recently upgraded my desktop workstation and know that the latest revisions of these packages will, indeed, work well together. Therefore, I've finally decided to upgrade rather than re-install all the packages on this example laptop. These are my other reasons for upgrading: Upgrades are an interesting way to see which packages and how they've changed over time.

 There have been extensive changes and improvements in the unstable version of portage. Extensive upgrades are a good way to actually see the impact of portage enhancements.

 Re-installs mean having to remember/make a list of all the packages you will need to re-install. As such, re-installs are like re-installs of Windows. Overwrite everything on the hard drive and install as new all the software you originally installed. Upgrades leave the gestalt of installed packages in place.

 Upgrades reveal which packages are no longer supported and have been orphaned. This is an excellent way to realize that you may have to change what and how you do/did things.

 All the user accounts are left intact. For me, re-installs are just that. Complete re-installs from bare metal. Therefore with upgrades, I don't need to save off user accounts for future restore.

 Finally, through the magic of "make.stage4.sh" or alternatively, make.stage5, I'll be able to make clones of my upgraded system with my preferred software base intact.

 At the present moment, the example laptop is not being used for work so there is no time deadline to meet.

I will also point out that I always run the unstable branch for my Gentoo based systems. This means I configure '~x86' instead of 'x86' or '~amd64' instead of 'amd64'. Whether I upgrade or re-install, I will be compiling all packages anyway. The real difference in work is that upgrading requires significant cleanup and much closer monitoring.

Note that I consider re-installing "high risk" for functional loss and data loss. You need to understand that a major upgrade such as we're contemplating here means that there is a history potentially spanning years. This history includes customization decisions settings, package additions and deletions and the reasons behind them. For me, anything I decided 2 weeks ago is a fog. Decisions I made two years ago are a deep, dark mystery. All that I or the actual end user knows is that stuff works the way we like it. Even though the upgrade is needed, we're not looking to change either our preferred functionality nor lose any data. If potential functional loss or potential data loss is not a problem, then a re-install is actually a desirable alternative. Examples of PCs where re-installs might be preferred include firewalls, routers etc. In other words, any PC not used to store information and also not used for special end user needs would be a good candidate for a re-install.

These posts are intended as a somewhat complete record/guide with commentary of what is involved with a major upgrade. If you're contemplating doing such an upgrade, these posts will give you an idea of what you're letting yourself in for. 

There is no such thing as a trouble free nor un-attended upgrade. I can't stress this enough. The fact is that you won't be performing the implied monolithic item we refer to as "a major upgrade". Even though "emerge -uND world" consists of a single command, the upgrade itself consists of many small, many intermediate and many large, independently developed, independently supported and independently upgraded packages. These packages are only tied together by more or less informally accepted conventions. 

You won't need to monitor the upgrade process constantly. But you will need to monitor it at regular intervals over time.

In addition to working familiarity with the Gentoo emerge process, you should also be comfortable using 'ssh', a terminal console and/or know how to login at the Command Line Interface {CLI} level. I assume that if you're running Gentoo, you are familiar already with these areas/tools.

For our example PC, this particular unit is a Dell Latitude C810 laptop built in the fall of 2001. lspci displays the following installed components:

```
00:00.0 Host bridge: Intel Corporation 82815 815 Chipset Host Bridge and Memory Controller Hub (rev 04)

00:01.0 PCI bridge: Intel Corporation 82815 815 Chipset AGP Bridge (rev 04)

00:1e.0 PCI bridge: Intel Corporation 82801 Mobile PCI Bridge (rev 03)

00:1f.0 ISA bridge: Intel Corporation 82801BAM ISA Bridge (LPC) (rev 03)

00:1f.1 IDE interface: Intel Corporation 82801BAM IDE U100 Controller (rev 03)

00:1f.2 USB Controller: Intel Corporation 82801BA/BAM USB Controller #1 (rev 03)

01:00.0 VGA compatible controller: nVidia Corporation NV11 [GeForce2 Go] (rev b2)

02:03.0 Multimedia audio controller: ESS Technology ES1983S Maestro-3i PCI Audio Accelerator (rev 10)

02:06.0 Ethernet controller: 3Com Corporation 3c556 Hurricane CardBus [Cyclone] (rev 10)

02:06.1 Communication controller: 3Com Corporation Mini PCI 56k Winmodem (rev 10)

02:0f.0 CardBus bridge: Texas Instruments PCI4451 PC card Cardbus Controller

02:0f.1 CardBus bridge: Texas Instruments PCI4451 PC card Cardbus Controller

02:0f.2 FireWire (IEEE 1394): Texas Instruments PCI4451 IEEE-1394 Controller
```

It runs at 1.13 Ghz with the maximum possible 512 megs RAM installed. The screen display is 1600x1200 {hence the built in nVidia GeForce2 Go graphics chip}. I've installed a 100G hdd and updated the BIOS to the last rev available {required on this laptop for hard drives over 40G}.

The hard disk is partitioned:

```
Disk /dev/sda: 100.0 GB, 100030242816 bytes

255 heads, 63 sectors/track, 12161 cylinders

Units = cylinders of 16065 * 512 = 8225280 bytes

Sector size (logical/physical): 512 bytes / 512 bytes

I/O size (minimum/optimal): 512 bytes / 512 bytes

Disk identifier: 0x00000000

   Device Boot      Start         End      Blocks   Id  System

/dev/sda1               1           4       32098+  83  Linux

/dev/sda2               5         516     4112640   82  Linux swap / Solaris

/dev/sda3             517       12161    93538462+  83  Linux
```

As a work laptop, I ran VMWare-Workstation with a Windows 2000 guest. Due to {at the time} issues with nvidia-drivers and vmware-workstation, the kernel was vanilla-sources-2.6.28.9.

Pertinent packages we will be upgrading included gcc-4.3.3, xorg-server-1.4.2, openrc-4.3, vmware-workstation-5.5 and kde-3.5.10. Other installed windows managers included xfce4 and fluxbox.

I did, at one point, try to install kde-4.X when it first became available in the unstable branch '~x86'. This didn't really work out for me. The net result was that I also had installed kde-4.1.3 and kde-4.2.0.

Previous versions of gcc included gcc-3.3.6 and gcc-3.4.6.

Web browsers included contemporaneous versions of firefox-1.X, firefox-2.X and seamonkey.

In other words, virtually all the installed packages are old and will be upgraded.

The upgrades will bring packages up to the their latest current unstable revisions: gcc-4.4.3, kde-4.4.1, vanilla-sources-2.6.33.1, firefox-3.6, seamonkey 2.X, qt-4.6.2, xorg-1.7.6, the latest vmware-workstation-6.5 series and so forth.

I already know that all these packages and their respective versions will work well together. However, if you use specialist software such as VMWare or proprietory drivers, it is your responsibility to be certain they'll work in the upgraded environment.

Chapter 1) - Initial Cleanups

The first step is to resist the temptation to run "emerge --sync". The reason for this is that the upgrade will proceed more cleanly if we first do some housekeeping. Counter-intuitively, the best start to housekeeping is to have the same portage database present as when the last upgrades happened. If "emerge --sync" has been run at any time after the last set of update emerges, then skip the remainder of this chapter. Really. While it's nice and helpful to clean out unneeded packages, it's not absolutely required and the world won't end. Go to Chapter 2).

If it is certain that the portage dataset dates back to the last time "emerge world" was run, then execute:

```
emerge --depclean -vp
```

What we're trying to accomplish is to clean up portage and all installed packages prior to performing the upgrade. Leaving dead packages in place only leads to extra noise during the upgrade process. Assuming the aged target system is in reasonable shape and further assuming that the portage database is contemporaneous with the installed packages, we should get a list of packages proposed for deletion.

A clean system with no unneeded packages will gives results similar to this:

```
Packages installed:   1837

Packages in world:    1043

Packages in system:   50

Required packages:    1837

Number to remove:     0
```

These results mean Chapter 1) is complete and we're ready to go to Chapter 2). However, you may continue to read the rest of this chapter for some additional tips.

A clean system with some unneeded packages will give results similar to this:

```
>>> These are the packages that would be unmerged:                                                                                                                                         

                                                                                                                                                                                           

 dev-haskell/network

    selected: 2.2.1.7 

   protected: none 

     omitted: none 

 dev-perl/yaml

    selected: 0.70 

   protected: none 

     omitted: none 

 dev-python/pyrex

    selected: 0.9.8.6 

   protected: none 

     omitted: none 

 dev-util/boost-build

    selected: 1.39.0 1.41.0 

   protected: none 

     omitted: 1.42.0 

 kde-base/kppp

    selected: 4.4.0 

   protected: none 

     omitted: none 

>>> 'Selected' packages are slated for removal.

>>> 'Protected' and 'omitted' packages will not be removed.

Packages installed:   1837

Packages in world:    1043

Packages in system:   50

Required packages:    1831

Number to remove:     6
```

Any other results means abandon Chapter 1) and go directly to Chapter 2). This is because the working portage database is not contemporaneous with the installed packages. We'll simply have to put up with the extra noise during the upgrade process.

For those of you with clean systems and unneeded packages {i.e. "Number to remove:" is greater than zero}, re-run the above command {without "-pv"} and allow the unneeded packages to be unmerged.

```
# emerge --depclean
```

Note 1: "Number to remove:" represents all packages which will never be used as the system is currently configured. These will always be packages that fulfilled previous depencies needed by packages which are no longer installed. As such, they are not directly accessed by the user. Since the user won't directly invoke these packages and their original calling programs are now gone, "--depclean" determines they can be removed.

Note 2: The above example is not from the laptop I upgraded. It's my desktop system. I did not heed my own advice and had to skip to Chapter 2).  :Very Happy: 

That's {mostly} it for Chapter 1). However! Don't continue on just yet.

If the target system's portage database met the requirements for performing this step, now is a good time to review whether there are packages that can be removed by user choice. Observe the following output fragment from the previous "emerge --depclean -pv" command:

```
  www-client/fetch-1.0-r1 pulled in by:

    @selected

  www-client/firefox-bin-3.6-r1 pulled in by:

    @selected

  www-client/httrack-3.43.7 pulled in by:

    @selected

  www-client/links-2.2 pulled in by:

    @selected

    dev-lang/mono-2.6.1

  www-client/lynx-2.8.8_pre2 pulled in by:

    @selected

    app-text/docbook-sgml-utils-0.6.14

    media-video/videotrans-1.6.0

  www-client/midori-0.2.4 pulled in by:

    @selected

  www-client/mozilla-firefox-3.6-r4 pulled in by:

    @selected

    www-plugins/noscript-1.9.8.86
```

Of special interest are those packages which have display "... pulled in by:" with only the single line of "@selected". This means that this package has no other package which directly depends on it. It also means that it was pulled in either as a result of a profile, USE flag declarative or explicitly requested by the user. In this case, midori and mozilla-firefox-bin were explicitly requested by the user.

It's not uncommon for users to try out different or new packages. For those packages which have the single line "@selected" and are no longer needed by the user, now is a good time to unmerge them. Once all these type of user abandoned packages are removed, rerun Chapter 1) to see if any other dependency fulfilling packages can be removed as well.

Caution: some packages are selected because of a profile configuration or USE flag setting. It won't do any actual harm to unmerge these by mistake because they'll be re-pulled later anyway. On the other hand, the real interest is in determining packages originally requested by the user that are no longer needed and eliminating them.

Chapter 2) - Needed Tools and Settings Changes

Execute the following command:

Wait for it ...

```
emerge --sync
```

Yes. Now is the time to find out just how naughty and neglectful the sys admin has been.

a) Don't bother running "emerge -puNDv world" just yet. Instead, if there is a message to update portage {almost a virtual certainty depending on how long it's been since the last emerge/upgrade}, do it now. The reason is that portage is continually improved and you definitely want the latest functionality improvements on your side.

b) Also, at the end of your latest "emerge --sync" there was probably a message telling you to look at portage mail. Regardless, run the following command:

```
# eselect news read all | less
```

READ IT! It has important information. An item of particular note is the special utility: lafilefixer. This will be important later. Install it and follow the instructions now.

```
# emerge lafilefixer

# lafilefixer --justfixit
```

Take notes and make yourself aware of the remaining contents of portage mail.

c) If gentoolkit or portage-utils haven't already been installed on the target PC, do so now:

```
# emerge gentoolkit portage-utils
```

 There are several tools which will be needed later. Specifically, qlist {from portage-utils} is required as part of upgrading KDE and equery {from gentoolkit} is helpful for researching which packages may need upgrading after an emerge aborts. There are other tools in each tool kit some of which provide equivalent functions between them. It's always a good idea to read the help associated with each tool so that you know what's available.

d) So you're done with emerging the latest version of portage, gentoolkit, portage-utils and lafilefixer? Now is a good time to look at /etc/make.conf before you go any further. Execute the following command:

```
# grep ACCEPT_LICENSE /etc/make.conf
```

If nothing appears, then execute:

```
# echo 'ACCEPT_LICENSE="dlj-1.1 PUEL"' >> /etc/make.conf
```

The latest versions of Java {JRE and JDK} require acceptance of the new Sun license: dlj-1.1. It is the responsibility of the end user to make themselves familiar with the terms of this license.

If a line with ACCEPT_LICENSE is displayed, be sure it includes the above value {but see the proviso in the next line below}. Edit /etc/make.conf and update as needed.

To blindly accept whatever licenses are required for all installed packages, replace "dlj-1.1 PUEL" with "*" {including quotes} in the prior command. This is not recommended.

Also in /etc/make.conf, look at the current settings for:

INPUT_DEVICES

VIDEO_CARDS

For INPUT_DEVICES="mouse keyboard" has been superceded by INPUT_DEVICES="evdev". If you still have "mouse keyboard", change them now. If you have a touchpad for a mouse {like many laptops} then use INPUT_DEVICES="evdev synaptics". If you have a USB based Wacom tablet, then add "wacom".

For ATI radeon owners, in VIDEO_CARDS="{some list}" some names have been changed. If you have a radeon card and you're going to use the open source kernel driver, set VIDEO_CARDS="radeon vesa". If you have a radeon based graphics card and you're going to use ATI's proprietary driver, set VIDEO_CARDS="vesa fglrx". I always include vesa as my fallback for when all else fails. Whatever your graphics chip, you want to be certain VIDEO_CARDS is set properly.

Now is also a good time to check the remaining values set in /etc/make.conf. Since you're upgrading virtually all packages anyway, there is no extra cost to making changes now. These could include settings in CFLAGS, LINGUAS, FEATURES, CAMERAS, ALSA_CARDS and more.

Chapter 3) - Prepping the Target PC - Command Line Interface {CLI}

Still don't bother running "emerge -puNDv world" just yet. There are more set up tasks to do.

At this point, we've removed known unneeded packages {if possible}, loaded all needed utilities and updated settings as needed/desired.

Since virtually all packages will be re-emerged to their latest versions, it is time now to say goodbye to whatever windows manager is active and drop exclusively to CLI. A better setup is to open a terminal window on another PC and 'ssh' into the target PC being upgraded. From here on out, we want to have as few active programs as possible so that we don't inadvertently emerge a running package and so that we give as many resources as possible to the upgrade process. This means {among other things} not running any program which requires X windows to be active.

Start by executing the following in whatever terminal window you've been working in:

```
# rc-update del xdm
```

This will cause the target PC to start with a Command Line Interface {CLI} style login prompt the next time it's rebooted. This way, the target PC will not try to start a partially updated X windows session or subsequent partially updated windows manager {read KDE, Gnome or similar}. The idea is to keep things clean and simple while the upgrade takes place.

Exit the current windows manager by either rebooting or simply logging off the current user. If 'ssh' from another PC is not an option, I recommend rebooting.

If you're staying on the PC you're upgrading and you haven't rebooted, press the CTL, ALT and F1 keys simultaneously. This should bring up a CLI login prompt. Log in as 'root' which will make it easier to perform the upgrade.

If you're going to use 'ssh' from another PC, do so now. Reminder: sshd needs to be running on the target PC!

It will be helpful to be logged into the target PC multiple times. If you're working exclusively on the target PC, pressing CTL, ALT and F1 through F6 will allow you to cycle through up to 6 logins. e.g. Press CTL, ALT and F1 for the first login then CLT, ALT and F2 for the second login and so forth. If you're accessing the target PC through ssh, then simply open multiple tabs in your terminal window and ssh to the target PC from each tab.

Chapter 4) - More Cleanups - KDE

Can you run "emerge -puNDv world"? Nope. Not yet. There's more housecleaning now and further on too! If KDE is installed on the target system, it needs cleaning now.

Due to changes in upstream and upstream's ending of support for the KDE-3.5 series, it is required that you clean KDE off completely before upgrading. User settings for KDE do not need to be cleaned off. It's just that all the KDE packages need to be removed.

The cleanup instructions for KDE-4.X as provided in the Gentoo KDE Guide are good but they are not complete. I don't know why the example laptop PC was the way it was, but the bottom line is that the location given for removal of prior KDE-4.X files may or may not be the location said files were installed on the target PC. This apparently depends on the KDE version and when it was installed. The instructions provided here will remove most, but not all, of the KDE-4.X packages which are installed. Removal exceptions and reasons for the exceptions will be pointed out later.

A quick explanatory aside. There are two versions of portage available. They are the 2.1 series and the 2.2 series. From an end user standpoint, the 2.2 series is a superset of the 2.1 series. The most visual difference between the two is portage 2.2's support for the concept of "sets". You should already be familiar with "world" and "system" as sets of packages. Portage series 2.2 extends that concept to sets for things like "kde-meta" and something called "preserved-rebuild". In portage 2.2, sets are prefaced with @ and are written, for example, as "emerge @world".

In the portage 2.1 series, there is no support for directly unmerging all kde-base packages at one time. In the portage 2.2 series, the idea is to be able to say something like "emerge --depclean -pv @kde-meta:4.4.1" and have all kde-base packages for version 4.4.1 be unmerged. Sets are a work in progress. Some of the functionality is there and some of the functionality isn't there.

I don't follow sets functionality discussions as I am not a dev. And take anything I've written here with a grain of salt. I will be demonstrating @preserved-rebuild in later posts. At this time, the functionality that is there that I've personally used seems to work well.

However, for KDE related cleanups, we'll ignore sets functionality altogether. The commands given below will work regardless of the series version of portage you use.

I've included this discussion of the two portage series because it's mentioned in the Gentoo KDE Guide and because, by default, even if you've specified the unstable branch of Gentoo, you get the portage 2.1 series. You explicitly need to unmask the 2.2 series to enable it. I am not recommending that you enable the 2.2 series. I'm just letting you know where the discussion of "sets" comes from in case you don't already know.

The KDE cleanup instructions make use of the 'qfile' command {from portage-utils}. With the options shown, the qfile determines which package 'owns' a given file. This package is then queued up for unmerging. I'm going to ignore the Guide instructions for using "sets" to clean out old KDE packages.

Under "Cleaning Up KDE", the Gentoo KDE Guide gives the following for cleaning out older versions of KDE:

```
# emerge -C $(qfile -C -q -e /usr/kde/%PREFIX%) (replace %PREFIX% with your KDE version, eg. 3.5, 4)
```

Go ahead and run this for KDE-3.5.X. Execute:

```
# emerge -C $(qfile -C -q -e /usr/kde/3.5)
```

For removing most of the KDE-4.X packages, start by executing this:

```
# ls /usr/bin/ | xargs qfile -C -q -e | grep kde
```

This will provide a listing of most of the KDE packages that are installed. Many packages will appear multiple times. This is not a problem and can be safely ignored. What we're searching for is to see exactly which versions of KDE packages have been installed. In the case of our example laptop, there were packages from KDE-3.5.10, KDE-4.1.3 and KDE-4.2.0 installed. The first command given above for the KDE-3.5 series removed the KDE-3.5.10 packages.

This second command works by listing all the files in /usr/bin and passing that list to the command 'xargs'. 'xargs' then executes the command 'qfile -C -q -e' for each file 'xargs' receives. The output from that is then passed onto the grep command so that only 'kde' packages are displayed. If you wish to learn more about 'xargs', the man file makes a good start.

Despite all the brute force processing and the many files in /usr/bin {typically over 3000}, qfile is efficient and fast enough to make the entire final listing painless. If you are not 'ssh'ed in and are running this command directly on the target PC, you should pipe the output to 'less' by adding ' | less' to the command string like so:

```
# ls /usr/bin/ | xargs qfile -C -q -e | grep kde-base | less
```

Piping the output to 'less' allows you to see all of the packages installed rather than simply allowing the listing to scroll off the screen.

If you used ssh from another PC, you should be able to scroll back in your terminal window {not xterm; use konsole or equivalently powerful terminal program. i.e. one that supports scrolling} to see the complete listing and therefore don't need to pipe the output to 'less'.

Base on the above resulting listing for the example laptop, the following commands were executed:

```
# ls /usr/bin/ | xargs qfile -C -q -e | grep kde | grep 4.1.3 | xargs emerge -C

# ls /usr/bin/ | xargs qfile -C -q -e | grep kde | grep 4.2.0 | xargs emerge -C
```

Don't forget that KDE also has it's own office programs. I'm not referring to the koffice suite. Rather, I'm referring to kexi, kword etc. Those need to be cleaned out too. In the case of the example laptop, I already knew that the KDE office package versions were the 1.6 series. I executed:

```
# ls /usr/bin/ | xargs qfile -C -q -e | grep app-office | grep 1.6 | xargs emerge -C
```

Limitations: There are some KDE-4 based packages which will not be unmerged by these commands. Any package which doesn't produce a file which gets written to /usr/bin will not get seen and therefore will not get unmerged. These types of packages include artwork, lib files only and meta packages. They also include packages which don't follow the base KDE revision numbering scheme or are not included in kde-base/kde-misc such as 'amarok', 'k3b' and 'koffice'.

On the example laptop, these are the packages I manually unmerged.

```
# emerge -C kdeartwork-icewm-themes-4.1.3 libkdeedu-4.1.3 libkdegames-4.1.3

# emerge -C libkcddb-4.1.3 kode-4.1.3 knotify-4.1.3 kdnssd-4.1.3 libkonq-4.1.3 kdialog-4.1.3 solid-4.1.3 ksplash-4.1.3 kurifilter-plugins-4.1.3 ktimezoned-4.1.3 kpasswdserver-4.1.3 kdesu-4.1.3 kcmshell-4.1.3 kstyles-4.1.3 kstartupconfig-4.1.3 kcheckpass-4.1.3 kscreensaver-4.1.3 ksysguard-4.1.3 libkcompactdisc-4.1.3 kdemultimedia-meta-4.1.3 kdepim-meta-4.1.3 kdeedu-meta-4.1.3 kdegraphics-meta-4.1.3 kdegames-meta-4.1.3 kde-menu-icons-4.1.3 libtaskmanager-4.1.3 kdeartwork-meta-4.1.3 kdetoys-meta-4.1.3 kdebase-meta-4.1.3 kde-meta-4.1.3

# emerge -C kdemultimedia-meta-3.5.10 libkcompactdisc-4.2.0 kde-menu-icons-4.2.0 libtaskmanager-4.2.0

# emerge -C libkpgp-4.2.0 libkleo-4.2.0 kdepim-icons-4.2.0 kdepim-strigi-analyzer-4.2.0 libkipi-4.2.0 libkexiv2-4.2.0 libkmahjongg-4.2.0 kde-wallpapers-4.2.0 kdebase-desktoptheme-4.2.0 libplasmaclock-4.2.0 kdeartwork-iconthemes-4.2.0 kdeartwork-wallpapers-4.2.0 kdeartwork-sounds-4.2.0 kdeartwork-desktopthemes-4.2.0 kdeartwork-emoticons-4.2.0 kdeartwork-colorschemes-4.2.0 mimelib-4.2.0 libksieve-4.2.0 

# emerge -C amarok k3b koffice-data koffice-libs koffice-meta koffice-l10n
```

Failure to clean out all KDE packages is not a terrible thing. What will happen is that the "emerge -uND world" process will fail packages which complain about 'already existing file conflict' messages. I discuss how to deal with this later. The object is to reduce midstream cleanups to the minimum possible.

Note: While the target PC's USE flags and also the fact that 'kde-meta' was not unmerged will pull back in the latest version of KDE, the packages for 'amarok', 'k3b' and 'koffice' will probably need to be added back manually. Start making a list of "to be manually re-installed" packages now.

That's it for preparation, cleaning and setting up for a major Gentoo upgrade. You can continue to Post II - Initial Upgrades Plus More.

Suggestions either here or through PM are welcome. Post II will be linked to from here after posting later tonight. Post II will include steps to run, what to watch for, how to deal with certain types of problems and include examples.

Sorry for any typos and/or grammatical errors. These will be corrected on a "time permitting" basis.

{edit} March 22, 2010 - Added links, corrected typos and grammar, added clarifying paragraphs, restated some poorly formed sentences.

----------

## krinn

1/ after syncing the tree, first things you should do is emerge portage (or read news... but updating the tool that handle everything is really not a bad idea)

2/ qfile,qlist... aren't in gentoolkit, they are in portage-utils, so all parts with qfile... will fail if the user didn't emerge it before

3/ the preserved-rebuild (might apply to your other post too) output is false for unstable : for me the current unstable portage i have is sys-apps/portage-2.1.8.2 and this version doesn't handle (bug us !) the preserved-rebuild option.

 :Very Happy:  maybe you should have done /1 and you would have seen it.

or maybe i'm wrong and i have find a trick to disable the preserved-rebuild option, but i don't remember, and if it's that: the way to disable it should be put here because that option is dawn stupid/buggy and useless.

edit: forgot! NICE WORK !!!

----------

## dufeu

 *krinn wrote:*   

> 1/ after syncing the tree, first things you should do is emerge portage (or read news... but updating the tool that handle everything is really not a bad idea)
> 
> 2/ qfile,qlist... aren't in gentoolkit, they are in portage-utils, so all parts with qfile... will fail if the user didn't emerge it before
> 
> 3/ the preserved-rebuild (might apply to your other post too) output is false for unstable : for me the current unstable portage i have is sys-apps/portage-2.1.8.2 and this version doesn't handle (bug us !) the preserved-rebuild option.
> ...

 

Thank you for the response and yes, you are correct. I should have been saying portage-utils rather than gentoolkit.  :Smile: 

I just finished the Post Mortem today. I'll be going back to each of these (all 4 posts) with corrections in the next few days. It took 9 days total to perform the upgrade on the example laptop and I'm still digesting some it. Plus I've always found it difficult to self edit without letting at least a few days pass.

Anyway, I will be putting in corrections soon so it anyone notices anything or thinks of something I may have left out, please either post here or PM me.

Thanks again!  :Smile: 

Oh! And yes, I did mean to imply that I wrote the first 3 posts as one document at one sitting. I decided I could and should logically break it into three focused posts when I started working with the forum posting tool. It's different than my normal writing mode.  :Wink: 

----------

## d2_racing

 *krinn wrote:*   

> 3/ the preserved-rebuild (might apply to your other post too) output is false for unstable : for me the current unstable portage i have is sys-apps/portage-2.1.8.2 and this version doesn't handle (bug us !) the preserved-rebuild option.
> 
> 

 

With portage 2.1.x, you can replace preserved-rebuild with revdep-rebuild -i I think.

----------

## NeddySeagoon

dufeu,

Very old systems will have the portage can't emerge the new python that new portage needs because portage needs to be EAPI aware.

You only need to have failed to update for about 12 months to be in that situation.

You don't describe the fix for that.

----------

## dufeu

 *NeddySeagoon wrote:*   

> dufeu,
> 
> Very old systems will have the portage can't emerge the new python that new portage needs because portage needs to be EAPI aware.
> 
> You only need to have failed to update for about 12 months to be in that situation.
> ...

 

Point. Definite point. I remember having to deal with that very issue on one PC, but I can't remember all the steps I had to take.

I believe I had to update python first, eselect the later version of python, then update portage. Then finally continue slogging through to finish.

I'll have to think about this for a bit and see what older systems I have which I could run through as examples.

Thanks for the reminder. If I recall correctly, wasn't there an upgrade procedure for the version jump in python as well?

----------

## NeddySeagoon

dufeu,

The process begins by getting binary tarballs of portage and python from tinderbox.dev.gentoo.org and unpacking them as if they were mini stage3 tarballs.

----------

## dufeu

 *NeddySeagoon wrote:*   

> The process begins by getting binary tarballs of portage and python from tinderbox.dev.gentoo.org and unpacking them as if they were mini stage3 tarballs.

 

Oh buggers!  I knew there was pain I would rather forget. I actually didn't follow that procedure, only read it. I did struggle with that particular upgrade on one of my systems, but did a different manual process to complete it. I'm going to need to go through it again before I can lay it out cogently. I'm not living at home at the moment so the systems I'd play with are not currently available to me.

The real issue is that there are a number of special upgrade procedures specific to particular circumstances.  What I really need to do is go back, take a look at the special upgrade procedures I've done in the past and then add a new chapter to reference specialist upgrades with links and appropriate commentary.

It will take me several weeks to consider exactly what to include. {sigh}

If you could respond back with the list of special circumstances upgrade procedures you consider most likely to encounter, I'd appreciate it.

Best regards!  :Smile: 

----------

## NeddySeagoon

dufeu,

Getting binaries from the tinderbox or extracting them from a stage3 always works.

There will be problems with expat, Xorg, udev not working with the kernel to name a few.

Some of the older issues and solutions can be found here.

That was put together in early 2008 from logs of #gentoo

----------

## Lupu

Your instructions go to great lengths to remove KDE. The last time I needed to do that, the following command line sufficed:

```
emerge -C `grep ^kde /var/lib/portage/world` && emerge --depclean -av
```

Is this not feasible for your setup?

----------

## dufeu

 *Lupu wrote:*   

> Your instructions go to great lengths to remove KDE. The last time I needed to do that, the following command line sufficed:
> 
> ```
> emerge -C `grep ^kde /var/lib/portage/world` && emerge --depclean -av
> ```
> ...

 

Actually, no. I'll explain in a bit.

From what I can see, your approach should work better than what I suggest for most people. In fact, I haven't seen anyone else suggest it. If I understand how I'm reading it, there is a lot to like about it. I hadn't thought of using /var as the source for determining what to remove. 

There are two classes of cases which won't be covered. I've encountered both sets of instances in the example PC I ran through.

The first set are those cases where, for whatever reason, /var is out of sync with what's installed. This is usually, but not always, due to manual intervention on the part of the user. In theory, that should never happen. However, in the case of kde based packages, there hasn't been any sanctioned way to removed an entire set. People have therefore done manual removing. When there are over 200 packages, this can have problematical results. In theory, the unstable branch of portage will eventually solve this with the "sets" functionality. This is why there are manual instructions for cleaning kde in the kde upgrade document.

The problem with the kde upgrade document is two fold. The first problem is that the instructions only cover certain expected resulting installation situations. In fact, from experience, I can say that depending on what version and what day that version was installed, the installed location will not match what's given in the kde upgrade document.

The second problem with the kde upgrade document is also the second class of packages which won't be covered. These are all those packages that are both not in one of the "kde-*" categories and also don't have "kde" as part of their name. This would include packages like "amarok". There are quite a few of these packages, certainly more than I initially suspected. Part of the instructions I give cover these packages in particular.

Using /var as the source as you suggest would definitely simplify removal of the bulk of the packages. I'll actively consider updating my instructions once I've had a chance to give it a real life run through!

Thank you very much!

----------

## Lupu

 *Quote:*   

> 
> 
> The first set are those cases where, for whatever reason, /var is out of sync with what's installed.
> 
> 

 

I'm not entirely sure I understand what you mean by "/var is out of sync with what's installed", so I'll assume that means /var/db/pkg. To my understanding this is where portage keeps track of all installed packages. If that database is not usable, well, it would pretty much defeat the purpose of updating vs. reinstalling. Anyway, both "emerge" and "qfile" as provided in your command lines rely on the same package database(unless it was located elsewhere back then?) to work in the first place.

 *Quote:*   

> 
> 
> The second problem with the kde upgrade document is also the second class of packages which won't be covered. These are all those packages that are both not in one of the "kde-*" categories and also don't have "kde" as part of their name. This would include packages like "amarok".
> 
> 

 

That is correct, but is it really necessary to remove all packages depending on KDE separately? I would expect that once you've removed KDE and try to update world, the updated Amarok(in this case) would pull in a newer KDE to be installed before Amarok itself is updated. Of course any packages that require an older KDE wouldn't work anyway and would need to be removed before updating world.

----------

