Using Portage

Portage has for some time now, had alot features, which can give alot control over ones system, mainly the files in /etc/portage, which can be used to unmask hardmasked packages, accept a masked package, provide a package(instead of injecting), and change virtuals. it is much nicer to have useflags separate for each package, as it gives one greater control of them, and also, its much better to change mask and stuff in the files in /etc/portage rather than in /usr/portage since then they wont be erased after a sync.

Working with hardmasking

Hardmasking is typically done on packages which are not working, or when it will break to simply upgrade, an example of this is mysql, where mysql 4.0 is the old stable release (which is still stable in gentoo), the current production release of mysql is 4.1, which is not binary compatible with 4.0, and one cant have both installed, so therefore 4.1 remains hardmasked for now, however if one does a new install, 4.1 is perfectly fine, but then manual unmasking is nessecary


To unmask packages, we will need to edit /etc/portage/package.unmask, the example of file syntax is shown below.


The way to mask packages is basically identical to the way to Unmask packages, the only difference is that the file we need to edit is /etc/portage/package.mask.

File syntax

the format is one package per line, you can use stuff like ‘=’, ‘>’, ‘<’ and combinations to get it like you want. an example file:


Working with keywords

Keywords are typically used to hold back packages for mainstream till they have been tested, however this can take a bit time, and often one wants to simply install the latest package. And since known to break packages are hardmasked, there’s not involved a GREAT risk.

Managing keywords

The way portage has keywords is for stable ones, ‘arch’, for example: ‘x86’ or ‘amd64. and for the untested ones: ‘~x86’ or ‘~amd64’. the global accepted keywords are placed in /etc/make.conf, however its most useful to only override the accepted keywords on a single or more packages, in which case we need to edit /etc/portage/package.keywords.

File syntax

The syntax is one package per line, you can specify it for only a specific version, or others with the following: ‘=’, ‘>’, ‘<’ and combinations, however no such thing is required if it should apply to all versions, which is generally smartest. example file:

dev-php/php ~amd64
dev-php/mod_php ~amd64

USE flags

USE flags are used to determine which features are built into packages, which has the ability to select/deselect them. for example php, has optional support for a broad selection of features.

Managing USE flags

USE flags can be set globally in /etc/make.conf, however it is more convenient, and gives more control of the system to specify all useflags on a per package base. to do this we need to edit /etc/portage/package.use. and if we want only to use useflags we specify in package.use, we can set USE=”-*” in /etc/make.conf

File syntax

The syntax is one package per line, you can specify it for only a specific version, or others with the following: ‘=’, ‘>’, ‘<’ and combinations, however no such thing is required if it should apply to all versions, which is generally smartest. example file:

dev-php/mod_php apache2 mysql session ssl zlib xml2 simplexml
dev-php/php mysql session ssl zlib xml2 simplexml


Virtuals are used, when more than 1 package can satisfy a dependency, an example of this is the virtual “virtual/libc” where both uclibc and glibc will work, these things are specified in the portage profile, but can be overridden in order to do a specific thing.

Managing virtuals

To manage virtuals, we need to edit the file /etc/portage/profile/virtuals, and specify the name of the virtual, and the name of the package we want it be choose.

File syntax

The syntax of the file is one package per line, and for this we cant specify versions, only package names. an example file:

virtual/alsa                            sys-kernel/dummy-sources
virtual/os-headers                      sys-kernel/linux-headers
virtual/kernel                          sys-kernel/linux-headers
virtual/linux-sources                   sys-kernel/dummy-sources
virtual/dev-manager                     sys-fs/udev


Overlays are local portage trees, so that you can have ebuilds which portage will not erase when you sync, an example of an overlay is Fluidportage
The directory scheme of overlays are the same as of the real portage: “category/packagename”

Managing overlays

Path’s to overlays are controlled via the PORTDIR_OVERLAY variable.. if you want multiple overlays seperate them by spaces.. example:



FILESDIR variable in the ebuild in the overlay ONLY reads from the overlay package’s files folder, therefore, if you are copying some ebuild from /usr/portage to your overlay, to perform some edit/version bump, you will also need to copy the files dir in the package in /usr/portage to the overlay

Injecting a package

Injecting a package can be very useful, however doing it with emerge inject(add a package to world file) is not very nice, since it would then be subject to updates. Examples of when injecting a package is useful, is for example if you are running a kernel which has been patched with some driver, like lm-sensors, which might require a new version of i2c, which isnt in vanilla yet, but you have it compiled in, lm-sensors depends on i2c then, but since you run your updated kernel, you dont want it to install new i2c modules, therefore you inject the i2c package.

Managing injected packages

The list of packages which portage thinks is installed is in /etc/portage/profile/package.provided. here we can add them, and portage will instantly think they are already emerged, and the dependency will be satisfied.

File syntax

The syntax is 1 package per line, since there can only be a specific version of the package injected, there are no need to specify boundaries. an example of the file is:


Change make.profile

Changing profile can be very useful, since there exists many profiles for portage, and these profiles holds information about the base system, and other interesting system stuff. for example for amd64 gentoo 2005.0 there exists a very nice subprofile called no-multilib, which compiles gcc without multilib, and masks the 32bit emulation packages, so that you will be running a 100% 64bit system.

Determine the current profile

To determine which profile you are using now, simply look what /etc/make.profile (symlink) links to. like this:

redeeman@redeeman $ ls -l /etc/make.profile
lrwxrwxrwx  1 root root 60 Feb 10 20:44 /etc/make.profile -> /usr/portage/profiles/default-linux/amd64/2005.0/no-multilib

Find a suitable new profile

Before you change, you need to find the apropriate profile for the system, you can have a look at those available in /usr/portage/profiles/

Change the profile

To change the profile, simply unlink /etc/make.profile, and create a symlink to the new one, like this:

root@redeeman $ unlink /etc/make.profile
root@redeeman $ ln -s /usr/portage/profiles/default-linux/amd64/2005.0/ /etc/make.profile
root@redeeman $ ls -l /etc/make.profile
lrwxrwxrwx  1 root root 49 Jul 27 20:15 /etc/make.profile -> /usr/portage/profiles/default-linux/amd64/2005.0/

Using emerge

Portage’s frontend, emerge, is the tool used to install, remove and update packages, and emerge has alot features making these tasks easier.


Here is a table of some of the most commonly used options:

Option Description Example Result
-p Pretend the action emerge -p zsh Shows all actions it would take to emerge zsh
-v Verbose information emerge -v zsh Emerges zsh with verbose output
-s Searches for packages via name emerge -s zsh Lists all packages which names contains zsh
-S Searches for packages via name and description emerge -S zsh Lists all package which name and description matches zsh
-f Fetches the package only emerge -f zsh Fetches zsh’s sourcecode
-C Unmerges the package emerge -C zsh zsh gets uninstalled
-D Deep emerge -uD zsh zsh and all the dependencies of it and all the way gets updated
-t Tree(implies -p) emerge -uDt zsh Shows the zsh emerge process as a tree
sync Sync the portage tree emerge sync The portage tree gets synced
–newuse Manage packages where USE flags have changed emerge –newuse world All packages in world where useflags have changed gets reinstalled


The following command will pretend an update of all packages in world, and its dependency tree, with verbose output, so one can see which packages pulls what in, and the packages useflags:

root@redeeman $ emerge -uDtv world
howtos/portage.txt · Last modified: 2005/11/12 01:14 by redeeman
Recent changes RSS feed RDL Licensed Powered by PHP Powered by Linux Powered by Apache Powered by Gentoo Powered by The Gimp Valid XHTML 1.0 Valid CSS Driven by DokuWiki

Sponsored by Sandberg Enterprises