Gentoo Linux Tidbits

I’ve been using Gentoo for about two years now and I took notes on managing my system. These are those notes. I’ve since created a bash script that does many of the functions and I’ll just post it here because it is pretty self-explanatory. For more details read below.

If you’re interested in installing Gentoo take a look at Gentoo Quick Install.

# /root/.bin/Gentoo/e - portage management tool

if [[ -z $@ ]]; then
  echo "e <option> <*option2/pkg> - portage management tasks:
  1 | oneshot   - adds a package as a dependency
  - | flagrem   - removes a global USE flag
  + | flagadd   - adds a global USE flag
  b | blocked   - blocked pkg workaround - <blocking> <tomerge>
  c | clean     - cleans (removes) package sources no longer in portage tree
  d | depclean  - remove unneeded dependencies
  e | elog      - view elog (developer notes for merged packages)
  f | flag      - add flag to package - <category/pkg flag>
  g | flaginfo  - information on a package's USE flags
  h | flaghas   - programs using USE flag
  i | install   - installs package (will use binary if available)
  k | keyword   - add keyword for unsupport archtechtures
  l | list      - lists files installed to a package
  o | owns      - check the file's owning package
  p | pretend   - check details of how a package is going to be added
  q | query     - search for an installed package
  r | remove    - remove package(s)
  s | search    - search for a package
  t | searchdes - search the description of packages
  u | upgrade   - emerge world (upgrade everything)
  x | check     - check installed pkg(s) integrity
  y | sync      - sync the portage database
  z | revdep    - rebuild dependencies
  freeze        - freeze a pkg update - <cat/pkg> <cat/pkg-version>
  unfreeze      - unfreeze a package - <package>
  unmask        - unmask package - <category/pkg-*version>
  gcl           - list installed gcc compilers
  gcs           - set new gcc compiler
  kl            - list available kernels
  ks            - select new kernel (will require bootloader update)"

# change to ebuild directory, put in ~/.bashrc:
# cde () { cd "$(dirname `equery ewhich "$@"`)" ; }
# b | blocked   - untested
# unfreeze      - generic matching will delete any line that matches
# forcerm(add?) - removes package that can't otherwise be uninstalled
#    forcerm )           shift
#                        emerge --force "$@"
#                        ;;
# etc-update (add?)
# --resume --skipfirst (add?)

case $1 in
    1 | oneshot )       shift
                        emerge --oneshot "$@"
    - | flagrem )       shift
                        if [[ -z "$@" ]]; then
                          echo " exiting: flag required"
                          exit; else
                          euse -D "$@"
    + | flagadd )       shift
                        if [[ -z "$@" ]]; then
                          echo " exiting: flag required"
                          exit; else
                          euse -E "$@"
    B | Block )         shift
                        quickpkg $1
                        emerge --unmerge $1
                        emerge $2
                        emerge --usepkgonly --nodeps $1
    c | clean )         eclean distfiles
    d | depclean )      emerge --depclean
    e | elog )          less /var/log/portage/elog/summary.log
    f | flag )          shift
                        echo "$@" >> /etc/portage/package.use
    g | useinfo )       shift
                        equery uses "$@"
    h | flaghas )       shift
                        equery hasuse "$@"
    i | install )       shift
                        emerge --usepkg --ask "$@"
    k | keyword )       shift
                        echo -e "$@ **" >> /etc/portage/package.keywords
    l | ls | list )     shift
                        equery files "$@"
    o | own )           shift
                        equery belongs "$@"
    p | pretend )       shift
                        emerge -pv "$@"
    q | query )         shift
                        equery list "*$@*"
    r | remove )        shift
                        emerge --unmerge "$@"
    s | search )        shift
                        eix "$@"
    t | searchdes )     shift
                        eix -S "$@"
    u | upgrade )       emerge --update --newuse --deep --ask world
    x | check )         shift
                        equery check "$@"
    y | sync )          eix-sync
    z | revdep )        revdep-rebuild
    freeze )            shift
                        echo "$1" >> /etc/portage/package.mask
                        echo "$2" >> /etc/portage/package.unmask
    unfreeze )          shift
                        sed -i "/$@/d" /etc/portage/package.mask
                        sed -i "/$@/d" /etc/portage/package.unmask
    unmask )            shift
                        echo "$@" >> /etc/portage/package.unmask
    gcl )               gcc-config -l
    gcs )               shift
                        gcc-config "$@"
    kl )                eselect kernel list
    ks )                shift
                        eselect kernel set "$@"
    * )                 emerge "$@"

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 -pv –update –newuse –deep world | less

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

Complete update:

emerge –update –newuse –deep world
glsa-check -f affected
eclean distfiles
  • In the first command, portage wiil update all packages on the system
  • etc-update is Portages configuration replacement tool. To merge configurations consider using dispatch-conf.
  • revdep-rebuild will check that all programs and libraries are linked correctly.
  • glsa-check is Gentoo’s security patches
  • eclean distfiles will remove package sources that aren’t installed anymore.

Remove Abandoned Dependencies:

emerge –depclean

Failed Package Emerge in a Compilation String

At times in a long list of package emerges like a system update, a package will fail to emerge. Bugzilla 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 and 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:

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.keywords:

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 you like living 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 isn’t necessary or undesired, a package can be frozen. This is useful for kernels and other such packages.

Mask the generic package (i.e. without version) in /etc/portage/package.mask:


Add the specific version to /etc/portage/package.unmask:


Create a Binary Package

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

emerge –buildpkg zim

To install a binary package:

emerge –usepkg zim

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

then “Update System”.

Select new kernel:

eselect kernel list
eselect kernel set 2

Rebuild modules added from Portage. Some drivers build against the kernel (video drivers, sound drivers…).


GCC Update. Update System for new GCC toolchain (yes both are recommended):

emerge -eav system
emerge -eav world

See installed GCC profiles and select one:

gcc-config -l
gcc-config 2

Then update the environment:

source /etc/profile

Create a binary of an already installed package:

quickpkg <package>

Clean portage world file:

Udept is a program that can speed up emerge by reducing the amount of calculations required by emerge. It does so by erasing repeat entries and dependencies in the world file (/var/lib/portage/world).

Note: Though udept can reduce emerge calculation time, it does so literally. For example, “epiphany-extensions” requires “epiphany” so udept sees “epiphany” as a dependency of “epiphany-extensions” and take it out of the world file. Later, if “epiphany-extensions” is unmerged, “emerge –depclean” will removed “epiphany”.

dep -w

Layman / Overlays

Overlays are package systems that run on top of Portage. Many Gentoo users eventually create their own overlay to be able to customize packages or build packages that are not yet in Gentoo Portage. A good number of third party overlays are available.

Local Overlay

Portage ebuilds can be edited to the users needs but once Portage has been synced all changes will be lost. Create a local overlay to edit ebuilds or make your own.

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 the overlay directory and let make.conf known of it (this folder can be almost anywhere).

mkdir /home/user/.portage-local

In 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 (the most popular being sunrise).

emerge subversion
emerge layman

Add to make.conf:

source /usr/portage/local/layman/make.conf" >> /etc/make.conf
layman –fetch
layman –list # -Lk for a more complete list

To add an overlay:

Sunrise is the most popular overlay in portage. If it’s not in the regular portage tree check sunrise.

layman –add sunrise

Update layman overlays:

layman -S
About these ads

About Gen2ly

<3's linux

9 comments on “Gentoo Linux Tidbits

  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. [...] For more on managing Gentoo take a look at Gentoo Linux Tidbits. [...]

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 52 other followers

%d bloggers like this: