Tips for new Gentoo users

Gentoo is one of the most difficult distributions to learn, though veteran Gentoo users might point out that its friendly community and extensive documentation can help new users. Here are some tips that might make Gentoo easier for anyone who wants to give it a try.

First, be prepared to read a lot of documentation, especially in the early stages of using the distribution. You won’t even be able to install Gentoo without carefully examining the Gentoo Handbook.

Gentoo has a graphical installer, but I do not recommend it for inexperienced users. Installing Gentoo in the “traditional” way will force you to read the Handbook, and therefore you will not miss important points. Also Gentoo’s installer is sometimes not as good at setting up needed drivers as other distributions’. Expecting Gentoo’s graphical installer to work in ways similar to that of any other distribution’s may lead to misunderstanding and frustration.

The Handbook contains basic information about Gentoo. Further topics (such as configuration of X and ALSA) are described on the Gentoo Documentation Resources page. Another important source of information is the Gentoo wiki.

If you have questions that aren’t covered in those places, you can find answers on the Gentoo Forums or in the distro’s IRC channels.

Portage basics

One fundamental element that distinguishes Gentoo from other distributions is its package management system, called Portage, which is primarily oriented to installing software from source. This allows a great deal of control and customization — while in binary distributions users have several packages for the same software with different dependencies and options (which actually gives users limited control compared to the options available when building the package from source), with Portage you set so-called USE flags to select optional features for the whole system or selected packages.

For example, if you need to enable KDE support and disable GNOME dependencies globally, you’d add kde -gnome to your USE variable in /etc/make.conf. You can read more about USE flags in the Gentoo Handbook .

You use Portage by invoking the emerge command. To install package moo, for instance, you simply type emerge moo. Portage checks dependencies of the given package, downloads all the necessary source archives, compiles the package, and installs it. All the information it needs is stored in its database, which consists of ebuilds, which are bash scripts written in a specific way. Ebuilds are stored in /usr/portage.

Managing Portage settings

The first rule of Gentoo is that you have to keep your attention closely on the USE flags. Why is X.org installed when you emerge Midnight Commander? Because you have the X USE flag enabled. Why does your KDE not have KPDF? Because you do not have the pdf USE flag enabled (do not ask me why it contains KGhostScript, though).

Always install a new packages with emerge --ask --verbose (or emerge -av) to see which flags will be used before compilation starts. Install the gentoolkit package (emerge gentookit) — among other useful things, it contains the euse utility, which is intended to simplify management of USE flags. Run euse -i flag to view a flag’s description and see whether it is enabled. See euse’s man page for more details (do not worry, it is short).

If you need to change a set of USE flags for some package, do not install it as USE="some flags" emerge moo. This will work, but the next time you update it, the package will be recompiled with the old set of flags. Changing USE flags is what the file /etc/portage/package.use is for. Just invoke echo "category/moo some flags" >> /etc/portage/package.use before installing.

The same applies to ACCEPT_KEYWORDS — use /etc/portage/package.keywords. In Portage 2.1 you can use package.use and package.keywords directories instead of files to simplify management.

When should you use overlays?

Sometimes you need to install a package that is not in Portage. For instance, you may wish to install a (version of a) package that is deleted from Portage. You can fetch its ebuild from Portage’s CVS repository. Sometimes you want to try update a new package and find an ebuild in Bugzilla. There may be a case when you decide to edit an ebuild from the official Portage tree.

In any case, you should place your ebuilds in a custom local overlay. An overlay is a custom set of ebuilds which you want to inject to a Portage database. Do not store custom ebuilds in the primary portage tree (/usr/portage), because they will be deleted the next time you sync. Create a directory for your overlay and create a directory structure similar to /usr/portage in it. Place your ebuild there accordingly. Add PORTDIR_OVERLAY="/path/to/local/overlay" to your /etc/make.conf file.

The usual place for overlays is /usr/local/overlays, so the overlay for your own ebuilds should be /usr/local/overlays/local. What else can /usr/local/overlays contain?

In many cases, when you seek packages not included in official Portage tree, you find not just ebuilds, but also overlays you can synchronize with. For example, one of the popular overlays is xgl-coffee, which contains all you need to use Xgl. You can install it to /usr/local/overlays/xgl-coffee to separate it from other overlays and update it via SVN.

You can find more information on managing overlays in the Gentoo Wiki. You will also find there a list of third-party overlays and information on how to synchronize with them.

How often should you update?

You should not sync your Portage tree more than once a day. Even that is usually more than enough. You can keep track of your favorite packages by visiting the packages.gentoo.org or gentoo-portage.com sites (or subscribing to the corresponding RSS feeds), and resync and update only when new versions of packages you use often make their way to Portage.

Keep your world clean

Whenever you emerge some-package, the name of the package is added to the /var/lib/portage/world file. When you wish to upgrade all your packages you are usually invoking something like emerge --update --deep world, and that is when this list is used. You should keep this list of packages as short as possible; only the packages you use directly should be there. If some package is installed as a dependency of another package, it should probably not be in your world file.

For example, if you install some package that uses the wxWidgets library, this library is installed as a dependency, and is not added to your world. If you uninstall all the packages using wxWidgets, this library will not be updated when you run emerge --update (...) world, and it will be uninstalled if you run emerge --depclean. The only reason you might add wxWidgets to your world is if you were a programmer developing your own applications using this library.

There is a script that can assist you in removal of unnecessary packages from the world list. To install a package without adding it to world, use the --oneshot (-1) option. It is also a good idea to use this option when you want to install some package temporarily.

Uninstalling packages

emerge --uninstall will not check whether you are trying to remove a package that is needed by another one. Sometimes even emerge --depclean can remove packages you actually need. That’s why you should be very careful when uninstalling software.

Sometimes you remove an optional dependency of some package. In this situation the package may stop working until you re-emerge it. The revdep-rebuild utility from the gentoolkit package is used to locate and re-emerge such packages.

Portage logs

Whatever you do with emerge is reflected in /var/log/emerge.log. For example, if you want to know which package is being compiled at the moment, run tail /var/log/emerge.log (I use a simple Python script to convert timestamps into a readable format). A utility called genlop (emerge genlop) can retrieve some useful information from this log. For example, running genlop -c will tell you which package is currently being compiled, and will try to predict how much time the compilation will take.

Cleaning temporary files

When an emerge session is stopped with an error, it leaves a directory that contains the temporary files it created while compiling the last package in /var/tmp/portage. If you fix the problem immediately and successfully re-emerge that package, these files will be deleted. In other cases you can empty /var/tmp/portage manually.

After several updates you may end up with many files in /usr/portage/distfiles. Use the eclean utility from the gentoolkit package to delete source files you do not need anymore. This utility can also delete binary packages you have created (invoke it as eclean-dist and eclean-pkg accordingly). See the man page for possible options.

Gentoo gives you great powers to customize your system. I hope this article will help you turn those powers to your side. While Gentoo requires you to put some effort into learning its ins and outs, it gives you the satisfaction of controlling every aspect of your system. You will like that feeling.