Gentoo – package maintenance basics

Prerequisite

Outside of the emerge command, an essential collection of tools to maintain your Gentoo system is the “eclean” collection of tools available from the official repositories. This contains tools to clear unused packages, their downloaded source codes, as well as unused kernels. It is recommended to install with the command below before proceeding.

emerge --ask app-portage/gentoolkit

Installing and uninstalling packages

Installation

It’s important here to make a stop to explain installing and uninstalling packages.

To install a package, it is as simple as calling “emerge”. For example, below I am installing the “gentoo-sources” package with default flags:

emerge gentoo-sources

The above is sufficient to install your package, although it is common to call the “verbose” and “ask” flags as well, such as below:

emerge --ask --verbose gentoo-sources
#or as below
emerge -av gentoo-sources

In your journey you may find conflicting packages, so for specificity, it is good to install you package by specifying its category; the package category can be found in the corresponding package’s page in the packages.gentoo.org site. For example, the “gentoo-sources” package is in “sys-kernel” and can be found at:

https://packages.gentoo.org/packages/sys-kernel/gentoo-sources

Conveniently, the link makes it easy to copy the correctly formatted package:

emerge --ask --verbose sys-kernel/gentoo-sources
#or as below
emerge -av sys-kernel/gentoo-sources

Uninstalling

To uninstall, simply specify the package, meta-package, or group to flag a package or multiple packages respectively for removal:

emerge --deselect gentoo-sources

emerge --deselect xfce-base/xfce4-meta
#https://packages.gentoo.org/packages/xfce-base/xfce4-meta

emerge --deselect gnome-base
#Gnome base contains gnome software set
#See: https://packages.gentoo.org/categories/gnome-base

Now that the packages are flagged for removal, we can process the removal with emerge’s “depclean” flag:

emerge --depclean

After the above, feel free to proceed with maintenance as mentioned below

Updating packages

A footnote: Previously, as still reflected in the Gentoo wiki, other tools such as “eix” were recommended to perform certain package maintenance functions; That is no longer necessary as many of their features are integrated into the main “portage” package.

Updates to available packages are performed through the Portage package manager which uses rsync internally, deltas to the package list are saved locally; this is referred to as syncing.

emerge --sync

Performing a sync is necessary to receive updates before performing updates.

To perform updates, a thorough command to perform is:

emerge -avDuN @world

Syncing etiquette is to not sync more than once a day and generally does not need to be done more frequently than that. Package updates can be done on any frequency, and syncing on a weekly, biweekly, or monthly basis is usually okay. If the majority of the software selection is on the stable branch, updates can be performed less frequently.

There are two ways to pass parameters to the emerge program using either the single or double hyphen; double hyphens are for passing the name of the parameter in full, whereas the single hyphen allows you to combine several parameters at once, as in the case above:

-avDuN breaks down to:
--ask (ask permission to proceed, no prompt is implied otherwise)
--verbose (print all output of compilation, alternative is --quiet. On most upgrades this will fill terminal buffer)
--deep (check dependencies)
--update (perform update)
--new-use (check all configuration changes in /etc/portage/ for changes that may introduce new USE flags, implies --changed-use)

@world (check world set; all packages are in the world set. Smaller sets can be manually curated and added to your config for rebuilds, installations, etc.)

Installation cleanup

Package cleanup

Cleaning packages is an essential part of maintaining a Gentoo system; without regular maintenance, old package source files and kernel source files will fill up the drive as they are not automatically removed as a part of the installation/emerge process.

Recently I was diagnosing my dearth of disk space on my Gentoo machine and found that old installation – “dist” files were taking up ~100GB of space. During the entire course of my machine, since it was first installed about 2 years ago, I had not once cleaned out these files.

Thankfully, maintenance is quite simple:

eclean-dist --deep

eclean-dist with the deep flag will remove all previously downloaded source files that are no longer accessible on the repositories as well as all downloaded source files that are no longer installed. If rebuilds are needed, this will require you to redownload the source files again; if you have a fast internet connection, then this should not be an issue.

Kernel cleanup

If compiling kernel from source using the gentoo-sources package, be sure to use eclean-kernel:

eclean-kernel -n2

In this case -n2 is set as an example of retaining only the 2 most recent kernels; this can be set to any number, including -n1 to only retain the most recent kernel, however this is not recommended.

Removing deselected packages and orphans

To clean and process uninstalled packages and orphans, simply run:

emerge --depclean

The above will remove packages, but not packages or kernel source files, those must be processed in the manner described above.

General cleanup

If running the system on any SSD, it is recommended to run a filesystem trim on a regular basis to ensure unused blocks are discarded.

fstrim / -v

The above performs a fstrim on the root partition with the –verbose flag.

Typical workflow

emerge --sync
#Synchronize package list

emerge -avDuN @world
#Perform upgrade

emerge --depclean
#Remove any orphaned or deselected packages

eclean-dist --deep
#Remove unused source files after successful upgrade

fstrim / -v
#Trim unused blocks for health of SSD (if applicable)

TUI Gentoo maintenance script

Save below in a shell script, for me, I have this saved as “emerge_helper.sh”.

Currently formatting only works for zsh, I may eventually fix this to allow for bash compatibility.

sync () { emerge --sync }
update () { emerge -avDuN @world }
depclean () { emerge --depclean }
backtrack () { emerge --backtrack=0 --ask --verbose --pretend --update }
portageupdate () { emerge --ask --oneshot portage }
buildnewkernel () {
    clear
    CURRENTKERNEL=$(ls /usr/src/linux -l | grep -o 'linux-[0-9]*.[0-9]*.[0-9]*-gentoo')
    KERNELDIRECTORY="/usr/src/$CURRENTKERNEL"
    eselect kernel list
    echo "Select kernel number:"
    read -r SELKERN
    eselect kernel set $SELKERN
    cp "$KERNELDIRECTORY/.config" "/usr/src/linux/"
    cd /usr/src/linux
    make oldconfig
    make menuconfig
    make modules_prepare
    make -j8
    make modules_install
    make install
    emerge acpi_call
}
cleankern () { eclean-kernel -n2 }
cleandist () { eclean-dist --deep }
trimmy () { echo "Beginning filesystem trim; this may take some time." ; time fstrim / -v }
pause () {
    printf "%s " "Press enter to continue"
    read ans
}

MainMenu () {
REPOTIMESTAMP=$(emerge --info | grep "Timestamp of repository gentoo:")
SELECT=$(whiptail --title "Emerge Assistant" --menu "$REPOTIMESTAMP \nPlease select an option:" 25 78 16 \
"Sync" "emerge --sync" \
"Update" "emerge -avDuN @world" \
"Depclean" "emerge --depclean" \
"Backtrack" "emerge --backtrack=0 -avp" \
"Update portage" "emerge --ask --oneshot portage" \
"Build new kernel" "Compile kernel, emerge modules & install" \
"Clean kernels" "eclean-kernel -n2" \
"Clean old packages" "eclean-dist --deep" \
"Trim" "fstrim / -v" \
"Reboot" "Reboot" 3>&1 1>&2 2>&3)

case "$SELECT" in
  "Sync")
    sync ; pause ; MainMenu
    ;;

  "Update")
    update ; pause ; MainMenu
    ;;

  "Depclean")
    depclean ; pause ; MainMenu
    ;;

  "Backtrack")
    backtrack ; pause ; MainMenu
    ;;

  "Update portage")
    portageupdate ; pause ; MainMenu
    ;;

  "Build new kernel")
    buildnewkernel ; pause ; MainMenu
    ;;

  "Clean kernels")
    cleankern ; pause ; MainMenu
    ;;

  "Clean old packages")
    cleandist ; pause ; MainMenu
    ;;

  "Trim")
    trimmy ; pause ; MainMenu
    ;;

    "Reboot")
    reboot
    ;;
esac
}
MainMenu