Portage

From Gentoo Linux Wiki

Portage is the package manager used in gentoo. Unlike most package managers, it is primarily used to handle source packages: portage can automatically build source packages as you need them, while binary package managers primarily install pre-built tarballs.

The purpose of this article is to teach the "best-known practices" for working with Portage on a daily basis. This is not a primer or introduction to using Portage or emerge. If you're new to Gentoo, the best way to learn how to use these tools are by reading the Working with Gentoo chapter of the Gentoo Handbook. In this article we'll take an in-depth look at how Portage works and how we can make it work better.

[edit] Emerging Packages

The emerge command is the primary way one interacts with Portage. Nearly all actions that can be performed are available using any number of command-line options in combination. Here, some of the more useful ones will be explained. For the full list, consult the emerge man page.

emerge --ask or emerge -a

Display a message stating exactly what actions emerge will be performing and prompts you to confirm them.

This is very similar to the --pretend option (-p), but it saves you from having to enter the command twice (once with and once without -p). --ask should be used almost every time you run emerge, so get into the habit of adding it now. ;)

emerge --verbose or emerge -v

Display the current USE flags available and selected for the given package, as well as the size of the source and total size of the data that needs to be downloaded.

USE flags in (parenthesis) are forced, masked or removed by your profile, -dash are disabled flags, asterisks* indicate that a flag has changed since the package was last emerged while percentage% indicate that it has been newly added or removed as an option.

This option should also be enabled on every emerge, and is only useful with --ask or --pretend.

emerge --deep or emerge -D

Check the entire dependency tree for a package rather than just the immediate dependencies.

When the target is world, --deep checks the dependency trees of packages in the world file. This option can find updates for packages that emerge would not have reported otherwise.

emerge --tree or emerge -t

Display the dependency tree for the specified packages.

If you have ever tried to figure out what's pulling in a particular package, or just wanted to see what depends on what, this is the option you should use.

Here you can see how asterisk depends on newt and sox, and newt depends on slang. Also, notice that the --tree option reverses the order that the packages are listed in. The first package to be emerged appears at the bottom instead of the top.

[edit] Maintaining packages

There are four files other than make.conf that can be used for package maintenance: package.keywords, package.mask, package.unmask and package.use.

/etc/portage/package.keywords

Used to set per-package ACCEPT_KEYWORDS.

Content is a list of package atoms, one line each, followed by one or more arch names.

Except for the standard arch names that can be used with ACCEPT_KEYWORDS (as found in /usr/portage/profiles/arch.list), package.keywords also accepts three special "arch names":

*

Package is visible if it is stable on any architecture.

~*

Package is visible if it is in testing on any architecture.

**

Package is always visible, ACCEPT_KEYWORDS are ignored completely.

For ** to work you need sys-apps/portage-2.1.2-r3 or higher.

sys-kernel/gentoo-sources -~*

x11-wm/compiz ~amd64

games-fps/quake3-demo x86

In addition to the "arch name" suffixes, the following version specifying prefixes can be used in conjunction with a version number suffix:

=

Package is visible if it has exactly the version number suffixed.

>

Package is visible if it is a later version than the version number suffixed.

>=

Package is visible if it is later than or equal to the version number suffixed.

=sys-devel/gcc-4.3.1-r1

>=www-client/mozilla-firefox-3.0-r1

>=dev-java/eclipse-ecj-3.3.0-r5 ~amd64

/etc/portage/package.use

Used to set per-package USE flags.

Content is a list of package atoms, one line each, followed by one or more USE flags.

Uses the same USE flags as make.conf, which can be found in /usr/portage/profiles/use.desc along with a description for each.

sys-kernel/gentoo-sources symlink

media-sound/decibel-audio-player -gnome

x11-libs/gtk+ tiff jpeg jpeg2k

/etc/portage/package.mask and /etc/portage/package.unmask

Used to hide and unhide packages, respectively.

Content is a list of package atoms, one line each.

[edit] Flagedit

You can also use app-portage/flagedit, which is useful in managing the keywords and USE flags.

Globally (make.conf)

To enable a flag

To disable a flag

To use whatever is specified by your profile.

Individual packages

To enable a flag

To disable a flag

To use whatever is specified by make.conf or your profile.

If you wish to reset all the use flags for a particular package

Same thing for keywords, except you add two dashes (--) before the keyword

In Portage 2.2.0 package sets were introduced. In order for flagedit to work you have to apply the following patch to /usr/bin/flagedit

8,14c8,14
< our $VERSION='0.0.7';
< my $uf_file = '/etc/portage/package.use';
< my $kw_file = '/etc/portage/package.keywords';
< my $mc_file = '/etc/make.conf';
< my $portage_dir = '/usr/portage';
< my $alpha_order = 0;
< my $strict = 0;
---
> our $VERSION='0.0.7.1';
> my $uf_file = (-d '/etc/portage/package.use' ? '/etc/portage/package.use/monolithic' : '/etc/portage/package.use');	#useflag file
> my $kw_file = (-d '/etc/portage/package.keywords' ? '/etc/portage/package.keywords/monolithic' : '/etc/portage/package.keywords');	#keyword file
> my $mc_file = '/etc/make.conf';	#make.conf file in etc
> my $portage_dir = '/usr/portage';	#directory where portage is installed
> my $alpha_order = 0;
> my $strict = 0;

[edit] Maintaining the World File

Your world file contains every package you have explicitly installed. Dependencies for these files are not added, but checked for when needed instead.

It is recommended that the world file is never edited directly, and instead the user uses the emerge command to maintain it. Below is a summary of the commands that interact with your world file.

emerge -u world or emerge -u system

Upgrade the packages in your world file and their immediate dependencies.

emerge -uD world or emerge -uD system

Same as above, except all dependencies of every package is also upgraded.

Because of this difference you can, if you so choose, maintain a known stable set of packages, only upgrading the "top level" packages.

emerge --depclean -a

Lists all the packages that is not registered in your world file and is also not a dependency for another package. If you chose to continue the listed packages will be removed. This should be followed by a revdep-rebuild to rebuild any necessary dependencies removed by depclean. To keep a package from being remove, add the full package name (e.g. dev-java/sun-jdk:1.4) to its own line in /var/lib/portage/world.

emerge -n <package>

Adds an entry for the specified package in your world file. This can be used to "protect" packages from getting removed when running with --depclean.

emerge -1 <package>

Install a package, but don't add it to the world file. If want to re-emerge a package which you only want because it's a dependency of another package, use this command.

[edit] Output color and formatting

Output from portage is compactly formatted to indicate a plethora of information.

[edit] State flags

B

blocked by an already installed package

b

blocked by an already installed package (conflict will be automatically resolved)

I

interactive package installation (required user input)

N

new, not currently installed

S

installs into a new slot

D

downgrading to older version

U

upgrade to newer version

R

re-emerging the same version, possibly due to new or removed use-flags

F

fetch restricted, must be manually downloaded

f

fetch, already downloaded

[edit] USE flags

• An unmarked USE flag is unchanged and enabled.
• A dash (-) preceding a USE flag (yellow, green or blue) shows that it is disabled.
• A percent symbol (%) following a USE flag indicates that it has been newly added or removed as an option for this package. Identical to yellow output.
• An asterisk (*) following a USE flag indicates that its meaning/scope has been updated. Identical to green output.
• Parentheses () around a USE flag indicate that it is currently masked by your profile. This is usually because the USE flag can not be supported on the given platform (for example, the win32codecs on amd64 with non-binary packages) or is irrelevant; for example, sse is available on all amd64 CPU's, so there's no point being able to disable it in a 64-bit environment.

[edit] Color

Portage returns information to you using both symbols and colors. While the combination makes for a pretty output it also may appear confusing on first glance. Note that the color information is not required and can be turned off, so it repeats the symbolic output.

red

The USE flag is enabled and has not changed.

yellow

The USE flag has been added, removed or masked since the package was last installed.

green

The USE flag has changed since the last time the package was installed, as the asterisk after it indicates.

blue

The USE flag is disabled, as the dash before it indicates.

[edit] Example

If you run the command

you might get something similar to

[ebuild   R    ] sys-kernel/linux-headers-2.6.11-r2  USE="-gcc64%" 36,470 kB 
[ebuild     U ] sys-process/psmisc-22.0 [22.2]  USE="X* ipv6 nls (-selinux)" 238 kB

In this example the sys-kernel/linux-headers package would be reinstalled as indicated by the "R" at the beginning of the line. The sys-process/psmisc package is being updated, as shown by the "U" at the beginning of the line. The version being updated from is shown within box brackets and is colored blue.

• The gcc64 USE flag is yellow and followed by a percentage symbol (%), showing that that option has been added since the package was last installed. The dash (-) shows that it will be disabled during this update.
• The X USE flag is green and followed by an asterisk (*), because that USE flag has changed since the last time the package was installed. No "-" shows that it will be enabled during this update.
• The ipv6 and nls USE flags is red since they are enabled and have not changed.
• The selinux USE flag is blue and preceded by a dash (-), because the flag is disabled. The parentheses () also show that it is an unavailable or irrelevant option.

[edit] Updating your system

To update your entire system execute

Since package dependencies constantly change you might also want to run the following.

[edit] Troubleshooting

[edit] "masked by: missing keyword" message

This error message typically shows up when you try to emerge a package that has not been adequately tested on the platform you are using.

Using package.keywords

There are several ways to instruct portage to install 'unstable' packages, many of which are bad for several reasons. The proper way to do this by adding the package to your package.keywords file

Details on this are given in the maintaining packages section of this article.

For packages that are available for your specific platform all you have to do is add the package to your package.keywords file and add the architecture, prepended with a ~, on the same line separated by a space. For example, on an AMD 64 computer to install the unstable version of the kernel we would do

sys-kernel/gentoo-sources ~amd64

For packages that are only available for other platforms, you would have to use the other platforms architecture instead. For example, if we're not on x86 but would like to install quake3-demo anyway

games-fps/quake3-demo x86

Bad methods

Following are two examples that are most often not what you would want.

Bad Method 1: ACCEPT_KEYWORDS

One dubious approach is ACCEPT_KEYWORDS="~x86" emerge foo. This has several undesirable features:

• It will merge unstable versions of all missing dependencies, not just the unstable version of foo.
• It will be forgotten immediately. The next time you run emerge -u world, portage will attempt to downgrade foo to the highest version that is stable. Portage will undo your changes, because you have told it to temporarily emerge an unstable version.
• Messages about all other packages that might be incompatible are not displayed.

If you like using unstable/testing software, you can place the ACCEPT_KEYWORDS="~x86" in your /etc/make.conf file.

Bad Method 2: emerge /path/to/ebuild

Another poor workaround is emerge /path/to/foo.ebuild. This has the annoying side effect of functioning as --oneshot. Portage will not add foo to your /var/lib/portage/world file. Unless foo happened to be in the world file beforehand, the foo package will never be upgraded again unless you force it manually, emerge -u world will miss it.

[edit] See Also

• USE Flags
• Overlay
• Porthole, a graphical interface to Portage.
• Writing Ebuilds

[edit] External Links

• GaMMa's Original Thread
• portage article on Redeeman's Wiki.