Using portage

Portage basics

Portage is run by using the command "emerge". The syntax is as follows:

$ sudo emerge -<flags> <what to emerge>

To determine the version and locations of the latest packages, portage communicates with an rsync server, which will update the local information available to portage so it has the latest list of packages. To sync portage, use the command

$ sudo emerge --sync

Portage flags tell portage which action to take. Some of the available flags are

-u : update the package in question.
-D : update the package in question, and any packages it depends on
-N : re-emerge the package with new USE flags
-v : verbose mode
-a : ask before emerging the package(s)
-C : uninstall the package in question.
-s : search for package(s) in question.
-p : pretend to emerge package (see what would happen)

It is good practice to always use the -av flags before emerging any package.

Checking if a newer package is available

If I had just run an emerge --sync and wanted to see if there was a new version of the ati video drivers, I would issue the command

$ emerge -p ati-drivers

You can also search for packages using portage. If I wanted to search for vlc media player, I would issue the command

$ emerge -s vlc

To see all the packages on a system that could be updated,

$ emerge -uDNvp world

Your etc/make.conf contains your global USE flags. Portage reads these flags before emerging any package, and will use them to compile and optimize the package based on the flags you have set. To view a list of the packages available in portage, and the USE flags available for each package, visit

http://gentoo-portage.com/Browse

Global and per-package USE flags

If there is a USE flag you want to use for a specific package but don't want to use globally, you can specify the package and USE flag in /etc/portage/package.use/. To organize things better, individual files for the package classes are now kept in this folder. In this example we'll use the conky package, which is in the app-admin class:

$ sudo nano -w /etc/portage/package.use/app-admin

For example, if we wanted to emerge conky without the ivp6 USE flag, but we had the ipv6 USE flag in our make.conf, we would add a line such as

app-admin/conky truetype audacious -ipv6

to specify that portage emerge conky with the truetype and audacious USE flags, but not the ipv6 USE flag.

Masked Packages

Some packages in portage may be masked (or blocked) for various reasons. You may run into an issue where you can't install a certain package because it or one of its dependencies are masked. To unmask a package, edit your /etc/portage/package.keywords file:

$ sudo nano -w /etc/portage/package.keywords

To unmask a specific package, you'll need to package type and package name in the format <package-type>/<package-name>. For example, if we wanted to emerge masked versions of portage, we would add

sys-apps/portage **

to our package.keywords file. This strategy can be used to emerge any masked package. Some packages are hard masked, meaning the devs have gone out of their way to prevent a certain package from being installed. This is usually due to stability or security concerns. If you really need to install a hard masked package, you'll need to comment out the package atom listed in the file /usr/portage/profiles/package.mask.

Emerging specific versions

Since there may be many different versions of each package in portage, and in many cases, the latest package may not always be the best. You can specify specific package versions and prevent portage from upgrading them by specifying

=pkg-type/pkg-name-version

in your package.keywords file. You can also tell portage to install a specific package on-the-fly using the syntax

emerge =pkg-type/pkg-name-version

The most common problem when using portage is circular dependencies and blocked or masked packages. package x may require package y which may require package z which cannot coexist with package x. There are a number of ways to circumvent these types of issues, one of which is uninstalling a certain package.

Uninstalling packages

To uninstall or unmerge a package, use portage's -C flag.

$ sudo emerge -avC packagename

This is usually your best tool for the dreaded cyclical dependencies: you may have to uninstall certain packages or change your USE flags then try emerging again.