Raspberry Pi 3B
Gentoo Cheat Sheet

I've never used Gentoo before, and when I have to do things over or to respond to screwups, I tend to forget how to do things. So here is a cheat sheet for how to do common tasks in Gentoo.

The Gentoo AMD64 Handbook is your guide to installing and using Gentoo. There isn't one (yet) for ARM64, so I picked the AMD64 (x86_64) version as a close relative. For all available architectures, see the Handbook Main Page.

Commands tend to barf out a lot of output, so it's a good idea to use one of these motifs:

• command >& /tmp/logfile ; less /tmp/logfile #If non-interactive
• command |& tee /tmp/logfile #If interactive

Find a package

Gentoo packages are usually named as category/basename, for example app-editors/vim. The version, or various version or variant selectors, can be appended. This command line shows descriptions of all packages whose name contains the given string:
emerge -s "string"

Use -S to also look in the descriptions. The search string can be a "%regexp" (it's a POSIX regexp as in grep, maybe extended).

Install a package

emerge --ask $PKG |& tee /tmp/logfile

Newbies should always use --ask, which will ask for confirmation to start compiling, and will also enable features to recover from blockages. Emerge will check dependencies, and will propose compiling dependent packages that are not yet installed.

Install a specific version

Although emerge is pretty good about using older versions if something is installed that won't tolerate a new version, sometimes you need to give it some help. To do a specific package version, specify it as "=$PKG-$VERS" (single '='), e.g. "=dev-libs/glib-2.52.3". You can also use generic comparison operators: > >= <= < .

If a package is blocked, etc.

emerge --ask may give you the option to write out keyword changes for blocked packages. Also, in normal installation it may deposit a revised version of a configuration file such as /etc/ssh/sshd_config. In these cases you should run dispatch-conf (no command line arguments). It will find the revised configuration files and let you deal with them. First it will show a diff between the old and new files, using less if it's long. Then you give it an action letter:

• u -- Install the new version, overwriting the old one. This is the most common choice, particularly for keyword changes.
• z -- Toss the new version, keep the old one. (Etymology: zap.)
• n -- Leave the old and new versions in place, go to the next file.
• e -- Edit the new file (and come back for another action letter).
• m -- Interactive merge. (I've never done this; not sure how it's controlled.)
• l -- See the diff again. (That's ell, not one.)
• t -- Toggle polarity of the 'u' action letter.
• h -- Show help screen.
• q -- Quit before finishing all files.

What are keyword changes?

For each package Gentoo has saved a set of Use Keywords which tell which features of the package should be compiled in: for example, X-Windows support may be optional and you need the 'X' keyword to get it. Very, very frequently when emerging on a Raspberry Pi or other ARM machine, you need the ~arm64 keyword. The tilde means in this case that the package is experimental (vs. stable) on this architecture, and your permission is needed to have it on your system. Emerge is pretty good about detecting missing or inappropriate keywords, and if given permission it can write out an updated use file that will work, after which dispatch-conf can install it.

Updating packages

Packages in the source repo may receive bug fixes or security patches. To get these onto your system you need to first download the package index, then download and compile packages that are installed on your machine and which have new versions.

• To download the package index, use emerge-webrsync (no command line arguments). This index is typically rebuilt daily.

• If, for some reason, you need an intra-day update, emerge --sync will fetch it. This feature takes extra bandwidth on the server, so only use it if you have a good reason.

• Index updates sometimes have accompanying news items. Use eselect news to read them. Capture the output and use less to view it at your own pace. After a new installation there will be several years of unread news. Not actually that onerous, and you don't have to do anything about any of them.

• Finally, this command line is suggested to compile the new packages:
  emerge --ask --verbose --update --deep --newuse @world |& tee /tmp/logfile

  Particularly in a new installation, allow plenty of time to compile a lot of updated packages. On my aarch64 install there were 38 packages which took 2 hours, and a normal desktop installation on x86_64 will probably take a lot longer.

Starting a daemon at boot

Gentoo has profiles that use systemd, but if you're keeping it simple, the legacy init system is called openrc, the init scripts are found in /etc/init.d , and the ones provided by the distro are in a special scripting language and are execed by openrc-run. If the basename is, for example, sshd, look for /etc/init.d/sshd, and activate it by
rc-update add sshd default
which gets it running when the default runlevel is activated, i.e. at a normal boot-up.

To remove a service change add to remove. To show the enabled services do
rc-update show default
(or omit the runlevel to see all of them at once.) They're in alphabetical order, not startup order.

Starting network at boot

The recommended way is: (illustrated for etho)
cd /etc/init.d
ln -s net.lo net.eth0
rc-update add net.eth0 default