Gentoo Linux Tidbits

I’ve been using Gentoo for about two years now and I took notes on managing my box. These are those notes. If you’re interested in installing Gentoo take a look at Gentoo Quick Install.

Update: bash script

This section is an addition. I’ve since created a bash script that does many of the functions and make reading the rest less necessary. The script is self-explanatory: link.

About Portage

Gentoo Linux uses a package management system called Portage. Portage offers one of the most extensible and customizable package systems available in Linux.

System Update

Update all packages on the computer. This process involves: syncing Portage, creating a text file to review updates, updating the system, merging new configuration files, remove orphaned dependencies.

Sync the portage tree

emerge --sync # or
eix-sync      # preferrable for faster searches (eix search)

Examine update before install

emerge --pretend --verbose --update --newuse --deep @world | less

If unexpected dependencies are being pull in, use the --tree option to track it down.

Complete update

emerge --update --newuse --deep --with-bdeps=y @world
revdep-rebuild  # ...
emerge --depclean
  • In the first command, portage wiil update all packages on the system
  • dispatch-conf is configuration updating and merge tool
  • revdep-rebuild will check that all programs and libraries are linked correctly and rebuild them if necessary.
  • emerge --depclean will remove orphaned dependencies
  • Additionaly a kernel update may need compiling again, distfiles may need to be cleaned up…

Failed package emerge in compilation string

At times in a long list of package emerges (like a system update) a package will fail to emerge. The bug-tracker and the forums usually have information about known problems with the package. If not, it’s possible the package needs a newer version of a package that has not yet been installed in the compilation string. Skipping the problem package and emerging it again when the rest of the packages are compiled may fix the problem.

emerge --resume --skipfirst

Blocked packages

Packages that block other packages from being emerged can be fixed by removing the obstructing packages then reinstalling it after blocked package is emerged.

quickpkg $BLOCKER
emerge -C $BLOCKER
emerge $BLOCKED
emerge --usepkgonly $BLOCKER

Specify USE Flags per package

In /etc/portage/package.use add pkg-category/pkg useflag useflag2. To add a USE flag temporarily (not recommended):

USE="useflag" emerge package

Masked Packages (keyword)

The “missing keyword” mask states an ebuild doesn’t support or hasn’t been tested on the current architecture (x86, amd, ppc… ). Keywording can be added to /etc/portage/package.accept_keywords for example: media-libs/libquicktime ~ppc.

Masked Packages (hard)

Gentoo hards masks some packages for security concerns, collisions… Packages are hard masked in /usr/portage/profiles/package.mask. If liking to live on the edge packages can be unmasked in /etc/portage/package.unmask.

Emerge dependency of a package

Packages that are dependencies of other packages (i.e. have no use on their own) should be emerged as oneshot. This is because if the main package is removed so too will this package when emerge –depclean is run. Otherwise these dependent packages are added to the world file.

emerge --oneshot package

Freeze a Package

If a rebuild of a package is undesired a package can be frozen. This is useful for kernels and other such packages.

  • Mask the entire package (i.e. without version) in /etc/portage/package.mask with sys-kernel/gentoo-sources.
  • Add the specific version to /etc/portage/package.unmask with sys-kernel/gentoo-sources-version.

Create a Binary Package

If enough disk space is available its may be a good idea to create and archived-binary of a package so it is quicker to re-install:

emerge --buildpkg zim
emerge --usepkg zim    # to reinstall

Info About the Portage System

This information can be useful for reporting bugs:

emerge --info

Other Portage Tools

Info about USE flags (equery is part of gentoolkit):

equery uses package

Programs built with a specific USE flag:

equery hasuse useflag

View what files are installed by program:

equery files alsa-lib

View what packages install to a folder:

equery belongs /usr/share/fonts/misc

List all installed packages:

equery list

Select a new system profile (With each new revision (i.e. 2006.1 to 2007) new profiles are added. Profiles define basic system USE flags…):

eselect profile list
eselect profile set 4

Select new kernel:

eselect kernel list
eselect kernel set 2

Rebuild external modules (added from Portage). Drivers build against the kernel (video drivers, sound drivers…) and will need to be rebuilt with new kernels:

emerge --ask @module-rebuild

Compile with specific compiler version. Some packages require a specific version of the compiler. See installed GCC profiles and select one:

gcc-config -l
gcc-config 2
source /etc/profile

Clean portage world file:

Remove entries that are dependencies only in /var/lib/portage/world to help emerge times. Careful what to remove thought. For example, “epiphany-extensions” requires “epiphany” so if “epiphany” is removed and later its decided that “epiphany-extensions” are no longer needed than running `emerge –depclean’ will removed “epiphany”.

Layman / Overlays

Overlays are package repositories that can be added to the portage tree. A good number of third party overlays are available in necessary.

Local Overlay

Create a local overlay to create your own ebuilds or edit an existing one. If the later, it’s best to see if the program has an ebuild in bugzilla or is in one of the third party overlays.

To make a personal overlay create an overlay directory and let make.conf known to it (for example) mkdir /home/user/.portage-local and add to make.conf:


Ebuilds must be placed in a category that already exists in Portage

mv package.ebuild ~/.portage-local/media-plugins/

Keyword if necessary:

emerge gentoolkit-dev
ekeyword ~ppc package-

Create a manifest and build:

ebuild ~/.portage-local/category/program/program-version.ebuild digest
emerge package


Layman is a manager for third party overlays.

emerge layman subversion

Add to make.conf:

source source /var/lib/layman/make.conf

To add an overlay:

layman --list
layman --add overlay

Update layman overlays:

layman -S

About Gen2ly

<3's linux

Posted on 2008-03-21, in Command Line, Gentoo. Bookmark the permalink. 11 Comments.

  1. Good and refreshing article. :)

    Sums up pretty much the need to know stuff in Gentoo.

  2. “Package states ‘missing keyword'”: A note on this. The safest way to get it is /etc/portage/package.keywords. An entry looks like that:

    cat-egory/package **

  3. Christian,

    I never really understood the use for package.keywords. I’ve actually seen people use it to unmask packages which seems odd to me. But now that I’ve looked into it this is alot better way to do keywording.

    Thanks for the tip.

  4. Great post.

    Do you know how to block packages from an overlay repository?


    How to add a single package from an overlay?

    Some times you need some overlay for one or two ebuilds and its a bit insane update the rest of your system with other that do you prefeer the gentoo oficials repository ebuilds….

    Thanks a lot for the post.. very instructive.

  5. Straight to the point. Excelent!

  6. Some good info but: Never use etc-update! Use dispatch-conf instead.

  7. @ AlanR

    yes using dispach-conf is a lot better for not overwritting existing configs. when i used gnome i had meld in /etc/etc-update.conf:

    diff_command=”meld %file1 %file2″

    I’ve tried Kompare but its not quite as good.

  8. Thanks for the info. The way you described oneshot helped!

  9. Reblogged this on Linux Tidbits and commented:

    Updated bash script and generally

  10. Very useful, with a lot of attention to detail.

  1. Pingback: Helpful Linux Tidbits

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


Get every new post delivered to your Inbox.

Join 58 other followers

%d bloggers like this: