Introduction
There are a number of major elements that define any Linux distribution. One of the most important is the package management philosophy or system that the distribution embraces. For example, we can categorize distributions designed around RPM as Red Hat based, or we can say that Ubuntu or Knoppix are derived from Debian because they all use APT. The package manager found at the heart of Gentoo Linux is known as Portage.
Portage sets itself apart from nearly all other package
managers in many ways. But the most significant difference is that it's
not actually a package manager at all, but rather what's known as a
meta-distribution engine. What this means is because of the power,
flexibility, and configurability of Portage, very few Gentoo Linux
installations are ever the same. Instead of being merely a tool used to
install and remove software packages (although it performs these tasks
with ease), the purpose of Portage is the construction of a complete
Linux distribution unique to the user who created it. In this sense,
Gentoo Linux is actually a meta-distribution. It's not a static
product, but actually a robust toolkit for people wanting to build a
custom operating system themselves.
The purpose of this HOWTO 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 is by reading the Working with Gentoo
chapter of the Gentoo Handbook. In this HOWTO 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 we will explain some of the more useful ones. For the full list, consult the emerge man page.
- emerge --ask (-a for short)
- Display a message stating exactly what actions emerge will be performing and prompt the user 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. ;)
root ~ # emerge -a patch
These are the packages that I would merge, in order:
Calculating dependencies ...done!
[ebuild R ] sys-devel/patch-2.5.9-r1
Do you want me to merge these packages? [Yes/No]
- emerge --verbose (-v)
- Display the current USE flags available and selected for the given package, as well as size of the source and total size of data needed to be downloaded.
- USE flags in (parens) are not available for your profile. +plus and -minus are enabled or disabled flags of course. asterisks* indicate that a flag has changed since the package was last emerged.
- This option should also be enabled on every emerge, and is only useful with --ask or --pretend. Little known fact: this flag also controls the display of those "GNU info directory index" messages at the end of the emerge that no one cares about.
root ~ # emerge -pv gimp
These are the packages that I would merge, in order:
Calculating dependencies ...done!
[ebuild R ] media-gfx/gimp-2.2.7-r1 -aalib (-altivec) -debug -doc -gimpprint -gtkhtml
-hardened +jpeg -lcms +mmx +mng +png +python -scanner -smp +sse +svg -tiff* -wmf 13,647 kB
Total size of downloads: 13,647 kB
- emerge --deep (-D)
- Check the entire dependency tree of a package rather than just the immediate dependencies.
- When the target is world, --deep checks the dependency trees of packages in the world file (more on this later). This option can find updates for packages that otherwise emerge would have not reported.
- emerge --tree (-t)
- Display the dependency tree for the package/target.
- This is an extremely useful option that is often overlooked. If you've 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 for you. ;)
root ~ # emerge -atv asterisk
These are the packages that I would merge, in reverse order:
Calculating dependencies ...done!
[ebuild N ] net-misc/asterisk-1.0.8 +alsa -bri -debug -doc +gtk -hardened +mmx -mysql
-postgres -pri -resperl -speex -vmdbmysql -vmdbpostgres -zaptel 9,451 kB
[ebuild N ] dev-libs/newt-0.51.6 -gpm 152 kB
[ebuild N ] sys-libs/slang-1.4.9-r2 -cjk -unicode 616 kB
[ebuild N ] media-sound/sox-12.17.7-r1 +alsa -encode -mad +ogg 455 kB
Total size of downloads: 10,675 kB
Do you want me to merge these packages? [Yes/No]
- Here we see 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. The first package to be emerged appears at the bottom instead of the top.
[edit] Forcing Unstable Packages
[edit] The dreaded "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. The only way around the problem is to tell Portage to disregard all keywords by using ~* or *.
There are several ways to instruct portage to install 'unstable' packages (e.g., to use the ~x86 branch instead of x86). Many bad methods for installing unstable software have been spread. The following will explain how and how not to unmask unstable software.
[edit] 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.
- There's a bug in emerge that results in an ugly error message.
If you like using unstable/testing software, you can place the ACCEPT_KEYWORDS="~x86" in your make.conf file.
[edit] 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, foo package will never be upgraded again unless you force it manually. emerge -u world will miss it.
[edit] A Good Method: /etc/portage/package.keywords
Details on this are given at TIP package.keywords. In short, to keyword an otherwise "unkeyworded" package you need to use either * or ~*. These are two special keywords.
* means "Match any stable keyword"
~* means "Match any unstable keyword"
** means "Match any keyword (even "")"
If the ebuild you are using is stable on x86, but not on sparc ( unkeyworded on sparc ) and you are on sparc, you would need to unmask it with *, since there are no ~arch keywords for ~* to match against.
For ** to work you need >=portage-2.1.2-r3.
If, for example, you wanted to explore currently uncharted territory by testing the Xen package on an AMD64 system, this is how you would do so:
| File: /etc/portage/package.keywords |
=app-emulation/xen-3.0.0_pre20051027 ~* |
Most of the time ~* works fine because there is an unstable keyword for one of the arches, however there are times when the package is stable on a number of arches, but not the arch that you are on. This is when using the * arch keyword comes in handy.
[edit] Maintaining Packages
Occasionally, portage may want to downgrade a package to an older version. Generally, there is a good reason behind it and it's best to downgrade it. There are exceptions though; for example linux-headers wanted to revert to 2.4.x when I have a 2.6.x kernel (Note: this is no longer the case with 2005.0 and later profiles). In /etc/portage/package.keywords we add a line or do
echo sys-kernel/linux-headers -* >> /etc/portage/package.keywords
Packages get downgraded when there is a huge security problem that isn't fixed in the newest versions and for other reasons, such as instablity being found that is very serious. Also, some devs just might accidentally mark something stable too early (they're only humans after all :-P )
Packages sometimes try to creep back onto the system when they aren't needed. Early on, users of xorg-x11 may have noticed xfree trying to make its way back onto the system. To fix this, in /etc/portage/package.mask a line was added:
| File: /etc/portage/package.mask |
x11-base/xfree |
Packages are also hard-masked from time to time. One such example is realone. It's hard-masked due to the fact there is a security hole that could lead to a compromised system. If for some reason you want to use realone, there's a package.unmask file. Make a /etc/portage/package.unmask and enter this command:
echo media-video/realone >> /etc/portage/package.unmask
Also if you don't want a package to include a particular USE flag, there's a package.use. Make a /etc/portage/package.use and enter a function similar to this into a terminal
echo net-p2p/bittorrent -X >> /etc/portage/package.use
This would tell portage not to include X support when emerging bittorrent.
But when you just want to get newest version of GNOME, KDE or any other ebuild with a lot of dependencies it can be a real pain to keep doing "emerge -pv gnome" only to get one single dependency at the time. Therefore you can run:
ACCEPT_KEYWORDS="~x86" emerge -pv gnome
Get all the dependencies listed and add them to your /etc/portage/packages.keywords .
[edit] Maintaining the World File
The world file is a record of packages which have been specifically installed by the user. More specifically it's a list of packages which the user wants to keep installed and updated on their system. It will not record the dependencies of those packages, but instead uses the dependencies of the currently installed packages to keep track of this information.
This means that, for example, if the emerge kde-meta command is issued, only kde-meta is added to the world file. The rest is worked out from its dependencies.
Contrary to some opinions, the world file is intended as a reference for the portage toolset only, and not to, for example, maintain a list of packages that the user wishes to be updated when running emerge -u world (this should be controlled using the package.* files under /etc/portage).
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 main commands. See emerge --help for information on all the available commands.
emerge -u (system: Update the system (base packages) or world packages and their immediate dependencies.
emerge -uD (system: Update the system or world packages and all their dependencies.
Why the difference between -u and -uD? Control. Using -u world instead of -uD world, the user can choose to maintain a known stable basic set of packages, only upgrading the top level of packages.
emerge --depclean --ask: List, ask the user to check and then remove all packages upon which no other package depends. In recent versions portage has got really good and not listing false positives here, but you should still check it just in case.
emerge --noreplace <package>: If a package is listed to be removed by depclean, but you don't want it removed, you can run this command and it will add the package to the world file, but won't actually install it.
emerge --oneshot <package>: Install a package, but don't add it to the world file. If want to re-emerge a package which you know you only want because it's a dependency of another package, use this command.
[edit] Troubleshooting: Lost World File
If you've lost your world file, portage no longer knows which packages you 'prefer' to be upgraded - this is generally not desirable. To (attempt to) fix your world file and add the packages type: regenworld
There's also a forum thread that provides information on how to fix your world file if regenworld doesn't work.
[edit] Understanding Portage's Formatted and Colored Output
Output from portage is compactly formatted to indicate a plethora of information.
[edit] Emerge "Pretend" Output
- 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 (re-merging same version)
- F = fetch restricted (must be manually downloaded)
- f = fetch (already downloaded)
- B = blocked by an already installed package
[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 is new 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 Output
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, so it repeats the symbolic output.
- red - The USE flag is enabled and has not changed.
- yellow - The USE flag has been added 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
emerge --update --verbose --deep --newuse world
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.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 gcc64 USE flag is colored yellow and followed by "%" showing that that option has been added since the package was last installed. The "-" shows that it will be disabled during this update.
- The X USE flag will be green and followed by "*" because that USE flag has changed since the last time the package was installed, as the asterisk after it indicates. No "-" shows that it will be enabled during this update.
- The ipv6 and nls USE flags would appear red since they are enabled (No "-") and have not changed (No "*").
- The selinux USE flag will be blue because the flag is disabled, as the dash before it indicates. The parentheses also show that it is an unavailable or irrelevant option.
[edit] TimeSavers
For those out there who want to simplify the whole "keywords" and "useflags" management, there is an application app-portage/flagedit which is insanely useful in managing the keys and useflags.
Per Package To enable a flag
flagedit foo-foo/foo +fooflag
To disable a flag ( regardless of what the make.conf file says and despite what your profile might want you to use )
flagedit foo-foo/foo -fooflag
To use whatever is specified by make.conf or your profile ( defaults )
flagedit foo-foo/foo %fooflag
Globally: aka make.conf as above, except without the foo-foo/foo part, ie:
flagedit +fooflag
flagedit -fooflag
flagedit %fooflag
if you wish to reset ALL the use flags for a particular package
flagedit foo-foo/foo %
Keywords to manipulate keywords, its the same as useflags, except you place a -- in the middle of the argument
flagedit foo-foo/foo -- +~fooArch
flagedit foo-foo/foo -- -~fooArch
flagedit -- -~fooArch
flagedit -- +~fooArch
flagedit foo-foo/foo -- %~fooArch
[edit] Conclusion
To update your entire system execute emerge --sync followed by emerge --update --ask --verbose --tree --deep --newuse world (or emerge -uavtDN world) Since package dependencies constantly change, an emerge --depclean followed by a revdep-rebuild -- -p -v might be in order, but is certainly not required.
There have been a variety of "cruft scripts" and cleaners available, but they all seem to have fallen out of maintenance or just plain dropped off the face of the planet. If you have any good ones, please post them here.
[edit] Also See
GaMMa's Original Thread More verbose guide on portage
Porthole is a graphical interface to Portage. By default it is masked so I leave it to you to try it. Newbies should not use it to install or uninstall software, though when ran with user privileges it makes for a convenient way to browse available software.
