En:HOWTO: The Complete Portage Guide

From Sabayon Wiki
Revision as of 11:25, 19 April 2012 by Nightshade (talk | contribs) (-l only lists active overlays)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
i18n: ca de en es fr pl tr
Portage (emerge) is not the primary package manager for Sabayon Linux, and this article is for advanced users only. In other words if this fails for you, it's your fault. You have been warned.


Q.What is a Shell?

A. A Shell is a command line interface or terminal, known to MS Windows users as The Command Prompt.

To get to a Shell, press Alt-F2 (the shortcut key for the Run command window) and type konsole or gnome-terminal or xterm depending on your preference.

To get into a Root Shell either use the su (switch user) command by typing su - (the "-" means change to that user's settings and home directory) or press Alt-F2 and type kdesu shellprogram or gnomesu shellprogram where shellprogram is "konsole", "gnome-terminal", "xterm" (without the quotes) or another. Technically, the Shell is actually the environment of the command line and not just the front-end for it. The most common Linux shell is BASH (Bourne Again Shell).

Q. What is all this Alt-F2'ing?

A.The most useful toolbar known to new Sabayon users is the Run Command Dialog, which allows you to run all sorts of programs and commands simply by typing the name of the command and pressing Enter. Alt-F2 is the global shortcut for this (it works in KDE, Gnome, XFCE, etc); it can also be accessed by right-clicking on the Desktop and selecting Run Command from the menu.

Q. Why do you use && in your instructions?

A. Because it is an easy way for issuing multiple commands on one line.

Q. What do I need for this guide?

A. You need a Sabayon Linux or a Gentoo Linux installation, a working brain (not everybody has one :), some eyes and the ability to read, think and learn.

Guide Starts Here

Q. How do I install software in Sabayon from source code?

Short Answer: In a root shell type emerge packagename where packagename is the name of the package you wish to install.

Longer answer:

This depends on what method you are using or what software you want to install. GENERALLY YOU WILL WANT TO IGNORE THE FIRST METHOD BELOW!!!

Source Installation

Note the instructions below are generic. For specific examples or command line examples with all the correct options for each step use Google :), or your brain.

  1. You download a source package using wget in a shell, or using a Web browser, or by some other means
  2. You extract this source package (often a tar.bz2 or tar.gz file) using tar in the shell or using Ark or File-roller
  3. You move the extracted directory to /usr/local/src/ using cp -R in a root shell or using Konqueror or Nautilus as Root
  4. You read the README and INSTALL files in the extracted package directory in /usr/local/src/
  5. You change directory by typing cd /usr/local/src/packagename (where "packagename" is the name of the package)
  6. Unless otherwise stated in the README and INSTALL files, if a configure script exists you type ./configure otherwise make one (usually required for svn or cvs installs) by typing autoconf (if autoconf gives errors type libtoolize && autoreconf, then type rm configure && autoconf)
  7. Unless otherwise stated in the README and INSTALL files, if a makefile exists type make && make install
  8. Done

Finally, the EASIEST and BEST method for Sabayon or Gentoo is using Portage / emerge.


Portage is a package management system that is used by Gentoo and Sabayon to install, uninstall and maintain software on your system from the source code. The Portage system consists of the Portage tree which is a collection of ebuilds, the emerge command which follows the instructions in ebuilds (special scripts), the Portage configuration files and the third-party Portage / emerge tools.

The Portage tree is a local copy (located in /usr/portage/) of the central ebuild repository. Whenever you install software on your system with the emerge command, the Portage tree is searched. If a matching package name is found, its dependencies are calculated, the source code for the package and its dependencies are downloaded and then they're all compiled and installed onto your system.


An ebuild is a specialized BASH script used by Gentoo & Sabayon to give a set of instructions to emerge as an interface to the Portage software management system. An ebuild is an automated way to perform the compilation and installation procedures for software.

Each version of each application or package in the Portage repository has a specific ebuild script written for it.

The ebuild script is used by the emerge command. The emerge tool uses the ebuild to perform its task: calculate any dependencies of the desired software installation; download the required files (and patch them, if necessary); configure the package (based on USE flag settings); compile; perform a sandboxed installation (in /var/tmp/portage/[ebuild name]/image/ by default). Upon successful completion of these steps, the installed files are merged into the live system outside the sandbox.

Although most ebuilds found in the Gentoo Portage repository are used to compile programs from source code, there are also ebuilds to install binary packages, ebuilds that install only documentation or data such as fonts, and basic ebuilds called "metabuilds" which solely trigger the installation of other ebuilds (such as the GNOME or KDE metabuilds).

For instructions on the creation of ebuilds see Gentoo Development Guide: Quickstart Ebuild Guide and Gentoo Development Guide.


The emerge command-line tool is the heart of Portage. The command is fairly complex with many options and modifiers. It is written in the Python programming language. The emerge tool is the most important utility to access the features of Portage from the command line.

The program calculates and manages dependencies, executes ebuilds and maintains the local Portage tree and database of installed packages. The compilation settings used by ebuilds can be changed through the CFLAGS environment variable, based on the specifications of the individual computer and on the user's desire for optimization. The emerge utility executes ebuilds in a sandbox environment. This way the system is protected from software executed by the ebuild, and resulting binaries are only merged after a successful build and sandboxed install.

What emerge installs as dependencies is affected by the USE flag settings. They decide which optional features will be included when installing or upgrading an application. The emerge command can also be used to download and install binary files, although some people argue that using binary packages is not taking full advantage of Portage's power since it foregoes the compile-time optimization options normally available.

To do stuff with emerge

You can mix and match most of the flags or switches below. Emerge works best run as root. See man emerge for more information.

Syncing Portage / Updating Portage Tree
emerge --sync

This updates and rebuilds the local Portage tree by syncing with on-line servers holding ebuilds. You will want to run this command before you start installing/removing packages since it ensures that emerge uses the most recent information. Often you will also want to run:

layman -S

to update all the overlays added to your installation. (You can read more about overlays in #Overlays & layman)

Install packages
# emerge packagename 


# emerge =packagecategory/packagename-version

(=packagecategory/packagename-version is known as a valid package atom)

This installs or upgrades / downgrades a package.

# emerge -u packagename 


# emerge -u =packagecategory/packagename-version 

This upgrades to best version of a package, not necessarily the latest.

There are more then 11,000 packages in Portage. Below are a few of the valid package atoms that can be installed.

  • www-client/mozilla-firefox-
  • net-fs/samba-3.0.24
  • media-video/mplayer-1.0_rc1-r2
  • app-emulation/wine-0.9.30
  • media-gfx/inkscape-0.44.1

Packages can be viewed either on

http://packages.gentoo.org/ (official)



Of course you can usually just specify the package name (e.g. mozilla-firefox, samba, mplayer, wine or inkscape).

Remove packages
# emerge -C packagename 


# emerge -C =packagecategory/packagename-version 

This removes a package.

# emerge -c packagename 


# emerge -c =packagecategory/packagename-version 

This cleans / removes a package and its unnecessary dependencies.

# emerge --depclean 

This removes all packages not listed in the system or world files.

Changing Portage verbosity
# emerge -v packagename 

This makes Portage verbose.

# emerge -q packagename 

This makes Portage quiet.

# emerge -s packagename 

This searches for a package with the packagename.

# emerge -S packagename 

This searches for a package with the packagename or the search term in the package description.

Asking and Pretending
# emerge -a packagename 

This makes emerge ask you to confirm each action before proceeding with it.

# emerge -p packagename 

This makes emerge pretend to do the following action, but not actually do it. It is useful combined with the -v flag. The key for the information provided by pretend is shown below. N = new (not yet installed) S = new SLOT installation (side-by-side versions) U = updating (to another version) D = downgrading (best version seems lower) R = replacing (remerging the same version)) F = fetch restricted (must be manually downloaded) f = fetch restricted (already downloaded) B = blocked by an already installed package

Other cool options
# emerge -1 packagename 

doesn't add the package/s to the world file (list of packages you want installed) when installing packages.

# emerge -o packagename 

doesn't emerge the package/s you want, only its dependencies.

# emerge -f <packagename> 

doesn't install or unpack the package/s you want, only fetching / downloading the source or binary package.

# emerge --resume 

resumes the last operation, which is useful it you stopped it midway through using Ctrl-C to kill it.

Big updates & recompiles
# emerge world


# emerge -e world

This reinstalls / upgrades everything in your world file / list of packages you want installed. This is DANGEROUS if done without proper planning, package masking (see below) and the correct switches / flags. For the best way to emerge world, see the howtos in the Gentoo Forums or the Gentoo Wiki, and Good Luck.

# emerge system


# emerge -e system

This reinstalls / upgrades all your core system packages. This is not as dangerous as emerge world, but still needs correct planning.

Overlays & layman

Portage overlays are custom Portage trees that contain packages not found in, or different from the packages in, the main Portage tree.

Overlays can be manually added by changing PORTDIR_OVERLAY="" in /etc/make.conf , but in Sabayon we prefer to use Layman (overlay manager).

# layman -l

This lists all active overlays.

# layman -S

This syncs all installed overlays (similarly to emerge --sync).

# layman -s overlayname 

This syncs the overlay with the overlayname.

# layman -a overlayname 

This adds / installs an overlay. You may need to edit /etc/make.conf to finalize.

# layman -d overlayname 

This removes / uninstalls an overlay. You may need to edit /etc/make.conf to finalize.

To sync the Sabayon overlay type:

# layman -s sabayon 

If you want to search for packages in ALL overlays, then do:

# emerge eix && eix-update && eix-remote update 

Now you can use eix keyword to search for a keyword in all overlays(you can use -e option for exact match). Then you can use layman to add the needed overlay. Remember to run eix-update && eix-remote update from time to time.

For more on 3rd party packages and overlays see http://www.gentoo-wiki.info/HOWTO_Installing_3rd_Party_Ebuilds .

For more information of overlays see http://en.gentoo-wiki.com/wiki/Portage_Overlay

Portage GUI Tools

Kuroo and Porthole are GUI front-ends for emerge / Portage in KDE and Gnome respectively. However Kuroo is no longer actively developed and is no longer in the Portage tree. Porthole is said to be less hassle than Kuroo because it ignores the Portage rules which Kuroo complains about.

Two other Portage GUI front-ends, both based on the GTK, are Portato and Himerge (the latter written in Haskell).

Optional: You can speed up the Portage GUI tools and the emerge command by typing as root emerge udept, then as root typing dep -w, this cleans up Sabayon Linux's world file and it takes some time but does speed up merging.

Installing Himerge

See also HOWTO: Install Himerge
# emerge -av himerge

Hard-masked Packages & /etc/portage/package.mask and /etc/portage/package.unmask

Masked / Hard-masked packages are packages in Portage that are locked or blocked from being installed for many reasons.

(=packagecategory/packagename-version) This is what is known as a valid package "atom". Any time you receive an error in Portage concerning package "atoms" one of three possibilities may exist:

  1. You typed the package atom incorrectly. Check your typing and re-emerge.
  2. The atom only exists in the Sabayon overlay and you need to use layman -S to update the overlay and re-emerge the package.
  3. The atom you are trying to install does not exist at all.

Examples of valid package atoms that may need to be masked or unmasked include:

  • =x11-drivers/xf86-video-i128-1.2.1
  • =sys-apps/dbus-1.0.2
  • <=dev-libs/dbus-glib-0.73

To mask a package, add a line for that package containing either =validpackageatom or >validpackageatom or <validpackageatom or >=validpackageatom or <=validpackageatom depending on which version of that package you want to mask, in /etc/portage/package.mask

To unmask a package add a line for that package containing either =validpackageatom or >validpackageatom or <validpackageatom or >=validpackageatom or <=validpackageatom depending on which version of that package you want to unmask, in /etc/portage/package.unmask

Packages are masked for a reason. This reason is either provided in Portage, or can be identified by asking other people. Be careful when masking and unmasking packages.

More info here: http://www.gentoo-wiki.info/Masked

Missing keyword

If Portage says: "masked by: missing keyword" while emerging, it means that the package isn't available for your architecture yet, e.g. you are running x86_64 (amd64) and the package has, for instance, the "x86" keyword only. If you really need that package, then you can try: echo "category/package x86 ~x86" >> /etc/portage/package.keywords to override it for package in a category. (Note: I've used the unstable "~x86" since the rest of Sabayon is running with unstable keywords anyway). As Gentoo is source-based there's good chance of a package compiling and working without modifications.

More info here: http://www.gentoo-wiki.info/Masked


This file is used to run unstable packages on stable systems, or ebuilds that haven't been tested on your platform. This file isn't that important to Sabayon users, but gentoo-wiki.com has more information if you are interested.


See here http://www.gentoo-wiki.info/MAN_make.conf_5

etc-update & dispatch-conf

These two tools update configuration files after packages have been emerged. man etc-update and man dispatch-conf provide the need-to-know information. When in doubt make a backup of your old config file first and then update. If something bad happens restore from the backup.

revdep-rebuild, equery, eix, and more

revdep-rebuild rebuilds broken packages caused by reverse dependencies and libraries breaking.

revdep-rebuild -Xp before typing revdep-rebuild -X is a good idea. -X makes revdep-rebuild ignore the specific package version, -p makes it pretend, similar to the emerge -p command.

revdep-rebuild takes time and often involves big emerges, but your system should be working well by the end of it.

equery and eix are extended Portage search tools, man equery and man eix provide their syntax and for further resources see gentoo-wiki.com and the Gentoo Forums.

Thanks to

--Appleman1234 23:48, 15 February 2007 (PST)