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