I’ve been using Gentoo for about two years now and I took notes on managing my box. These are those notes. If you’re interested in installing Gentoo take a look at Gentoo Quick Install.
Update: bash script
This section is an addition. I’ve since created a bash script that does many of the functions and make reading the rest less necessary. The script is self-explanatory: link.
Gentoo Linux uses a package management system called Portage. Portage offers one of the most extensible and customizable package systems available in Linux.
Update all packages on the computer. This process involves: syncing Portage, creating a text file to review updates, updating the system, merging new configuration files, remove orphaned dependencies.
Sync the portage tree
emerge --sync # or eix-sync # preferrable for faster searches (eix search)
Examine update before install
emerge --pretend --verbose --update --newuse --deep @world | less
If unexpected dependencies are being pull in, use the
--tree option to track it down.
emerge --update --newuse --deep --with-bdeps=y @world dispatch-conf revdep-rebuild # ... emerge --depclean
- In the first command, portage wiil update all packages on the system
dispatch-confis configuration updating and merge tool
revdep-rebuildwill check that all programs and libraries are linked correctly and rebuild them if necessary.
emerge --depcleanwill remove orphaned dependencies
- Additionaly a kernel update may need compiling again, distfiles may need to be cleaned up…
Failed package emerge in compilation string
At times in a long list of package emerges (like a system update) a package will fail to emerge. The bug-tracker and the forums usually have information about known problems with the package. If not, it’s possible the package needs a newer version of a package that has not yet been installed in the compilation string. Skipping the problem package and emerging it again when the rest of the packages are compiled may fix the problem.
emerge --resume --skipfirst
Packages that block other packages from being emerged can be fixed by removing the obstructing packages then reinstalling it after blocked package is emerged.
quickpkg $BLOCKER emerge -C $BLOCKER emerge $BLOCKED emerge --usepkgonly $BLOCKER
Specify USE Flags per package
pkg-category/pkg useflag useflag2. To add a USE flag temporarily (not recommended):
USE="useflag" emerge package
Masked Packages (keyword)
The “missing keyword” mask states an ebuild doesn’t support or hasn’t been tested on the current architecture (x86, amd, ppc… ). Keywording can be added to
/etc/portage/package.accept_keywords for example:
Masked Packages (hard)
Gentoo hards masks some packages for security concerns, collisions… Packages are hard masked in
/usr/portage/profiles/package.mask. If liking to live on the edge packages can be unmasked in
Emerge dependency of a package
Packages that are dependencies of other packages (i.e. have no use on their own) should be emerged as
oneshot. This is because if the main package is removed so too will this package when
emerge –depclean is run. Otherwise these dependent packages are added to the world file.
emerge --oneshot package
Freeze a Package
If a rebuild of a package is undesired a package can be frozen. This is useful for kernels and other such packages.
- Mask the entire package (i.e. without version) in
- Add the specific version to
Create a Binary Package
If enough disk space is available its may be a good idea to create and archived-binary of a package so it is quicker to re-install:
emerge --buildpkg zim emerge --usepkg zim # to reinstall
Info About the Portage System
This information can be useful for reporting bugs:
Other Portage Tools
Info about USE flags (equery is part of gentoolkit):
equery uses package
Programs built with a specific USE flag:
equery hasuse useflag
View what files are installed by program:
equery files alsa-lib
View what packages install to a folder:
equery belongs /usr/share/fonts/misc
List all installed packages:
Select a new system profile (With each new revision (i.e. 2006.1 to 2007) new profiles are added. Profiles define basic system USE flags…):
eselect profile list eselect profile set 4
Select new kernel:
eselect kernel list eselect kernel set 2
Rebuild external modules (added from Portage). Drivers build against the kernel (video drivers, sound drivers…) and will need to be rebuilt with new kernels:
emerge --ask @module-rebuild
Compile with specific compiler version. Some packages require a specific version of the compiler. See installed GCC profiles and select one:
gcc-config -l gcc-config 2 source /etc/profile
Clean portage world file:
Remove entries that are dependencies only in
/var/lib/portage/world to help emerge times. Careful what to remove thought. For example, “epiphany-extensions” requires “epiphany” so if “epiphany” is removed and later its decided that “epiphany-extensions” are no longer needed than running `emerge –depclean’ will removed “epiphany”.
Layman / Overlays
Overlays are package repositories that can be added to the portage tree. A good number of third party overlays are available in necessary.
Create a local overlay to create your own ebuilds or edit an existing one. If the later, it’s best to see if the program has an ebuild in bugzilla or is in one of the third party overlays.
To make a personal overlay create an overlay directory and let
make.conf known to it (for example)
mkdir /home/user/.portage-local and add to
Ebuilds must be placed in a category that already exists in Portage
mv package.ebuild ~/.portage-local/media-plugins/
Keyword if necessary:
emerge gentoolkit-dev ekeyword ~ppc package-18.104.22.168.ebuild
Create a manifest and build:
ebuild ~/.portage-local/category/program/program-version.ebuild digest emerge package
Layman is a manager for third party overlays.
emerge layman subversion
PORTDIR_OVERLAY="/home/username/.portage-local" source source /var/lib/layman/make.conf
To add an overlay:
layman --list layman --add overlay
Update layman overlays: