Gentoo is the most recent distribution I’ve tried and I thoroughly recommend it. Gentoo have produced brilliant documentation - perhaps the best examples I’ve seen - so visit Gentoo.org before reading anything here. This page is simply my short cut to the information I most regularly require.
Index
- Useful links
- System files
- Program files
- Installing and uninstalling packages
- Package install / update logs
- Find available packages
- Updating environment
- Update portage tree
- Update everything / all installed packages
- List all installed packages
- Rebuild applications that depend on a particular library
- Unstable and masked packages
- Forcing specific version of a package
- Set services to start at a given runlevel
- Update profile
- Clear disk space
Useful links
First, some links to Gentoo documentation I’ve used:
- Gentoo Linux x86 Handbook
- The X Server Configuration HOWTO
- ALSA Guide
- Printing Guide
- Gentoo Linux GCC Upgrade Guide
- Gentoo Linux Cron Guide
- Gentoo Linux USB Guide
- Gentoo Upgrading Guide
- Using UTF-8 with Gentoo
Other links to useful resources:
System files
Tabulated below are a number of files and directories relevant to the Gentoo distribution. Many are common to most Linux distributions.
| Location | Description |
|---|---|
| /etc/env.d/ | Holds environment configuration files, each of which contains environment variable assignments. These are processed by Gentoo (using env-update) in alpha-numeric order (0-9, a-z) to build the environment. |
| /etc/init.d/ | Holds service initialisation scripts. These can be manually executed with /etc/init.d/[service] [start|stop|restart]. You can set which script starts at a runlevel with rc-update [add|del] [service] [runlevel]. The scripts are processed by Gentoo in alpha-numeric order (0-9, a-z). |
| /etc/runlevels/ | Contains a subdirectory per runlevel, normally boot, default, nonetwork and single. Each directory contains soft links to init scripts held in /etc/init.d/, populated using the rc-update command (see the Set services to start at a given runlevel section). |
| /etc/conf.d/ | Holds program configuration files. |
| /etc/conf.d/net | Network config. |
| /etc/make.conf | Define build variables, e.g. USE flags. |
| /etc/portage/package.keywords | Place package names in here if you want to use the version from the testing branch rather than from the stable branch. You can place specific keywords at the end of a line, after the package name, e.g. app-office/gnumeric ~x86. See the Unstable and masked packages section. |
| /etc/portage/package.use | Place package names in here if you want to change their use flags. You can place specific keywords at the end of a line, after the package name, e.g. dev-lang/python doc -berkdb to remove the berkdb use flag from python. |
| /usr/portage/profiles/package.mask | Specifies which packages are masked and the reason why. Don’t edit this file. |
| /etc/portage/package.unmask | Place package names here to unmask them (overriding /usr/portage/profiles/package.mask). It must contain exactly the same line as in /usr/portage/profiles/package.mask. Note that this file does not exist by default. |
| /etc/portage/package.mask | Place package names here to mask them. |
| /usr/shared/doc/ | From the 1. Ebuild HOWTO section in the Gentoo Developer Handbook: ‘Documentation files are installed in /usr/share/doc, into a subdirectory reflecting the name, version, and revision of the particular program. This applies to all programs: GNOME, KDE, X11 and console alike. However, some programs may install additional documentation and support files into a /usr/share hierarchy for their own purposes.’ |
| /usr/portage/profiles/use.desc | Holds a list of use flags and their descriptions. To check a particular use flag: cat /usr/portage/profiles/use.desc | grep [use flag] |
| /var/lib/portage/world | A list of all packages installed by the user. Note that it does not list their dependencies. A system file, used by portage, so best not to screw it up. |
| /var/log/emerge.log | Emerge log, showing packages that were installed/uninstalled. |
| /var/log/portage/elog/* | Emerge logs, one for each package. |
| /var/log/portage/elog/summary.log | Detailed messages about your last emerge. |
Program files
| Location | Description |
|---|---|
| /etc/X11/xorg.conf | X configuration, set by xorgconfig. |
| /etc/X11/xinit/xinitrc | Default X initialisation config, which normally defines the start of a number of programs followed by a window manager. |
| /home/user/.xinitrc | User-level X initialisation config. This is loaded by xinitrx, if found, in place of /etc/X11/xinitrc/xinitrc |
| /etc/X11/xdm/Xresources | Read by the xsession file when you log in using xdm. Put X application config here (e.g. xterm config). |
Installing and uninstalling packages
Install:
emerge -av whatever
Uninstall:
emerge -Cav whatever
Note that this last command does not check dependencies, so use with care.
The a flag causes emerge to ask for confirmation and the v flag results in verbose output.
Constraints are unsatisfied
If you get something like the following:
...
!!! Problem resolving dependencies for some/package from @selected
...
The following REQUIRED_USE flag constraints are unsatisfied:
cpu_flags_x86_foo? ( cpu_flags_x86_bar )
...
It means that you have cpu_flags_x86_foo enabled but not cpu_flags_x86_bar. Enable cpu_flags_x86_bar to resolve the USE flag constraints.
References
Package install / update logs
/var/log/emerge.log contains a list of packages installed/uninstalled.
/var/log/portage/elog/ contains logs, one for each package.
/var/log/portage/elog/summary.log has a summary of the emerge.
The elogviewer program can be used to view logs via a GUI, or elogv via Curses.
Find available packages
To search for packages whos description and name matches the [terms]:
emerge -Ss [terms]
It is case and space insensitive (e.g. if the term is ‘something’ it’ll match ‘SomeThing’ and ‘something’).
It will take a while if searching the description with the -S flag, so to search only the name:
emerge -s [terms]
Listing available masked packages
The equery tool can show masked packages, by listing those in the portage tree rather than those installed on your computer:
equery list -p [package]
See my equery notes for more on the equery command.
Updating environment
After doing an emerge it’s often important to update your environment. This consists of updating both the configuration files and the environment variables. To update the config files:
Configuration files
dispatch-conf
You’ll be presented with diffs of each configuration file that has changed, with a set of options for updating them. I use the following options most often:
- u
- Use the new configuration (the right hand side) in its entirety.
- z
- Use the original configration (the left hand side) in its entirety (“zap” i.e. kill/delete the new).
- m
- Merge the files, manually, but inspecting the changes side by side. When you are merging use
lto choose the left (original) version andrto choose the right (updated) version.
I used to use etc-update, but dispatch-conf is quicker.
Environment
To update the environment variables:
env-update
Then start using the new environment:
source /etc/profile
References
dispatch-conf Manpage of dispatch-conf Manpage of env-update
Update portage tree
emerge --sync
Or if you can’t use rsync because of firewall restrictions:
emerge-webrsync
Update everything / all installed packages
To update system packages:
emerge -avu system
And to update all packages:
emerge -avu world
Note that the packages’ dependencies are not updated, which isn’t necessary most of the time since any packages that are updated will install their dependencies anyway.
The -D switch will cause all dependencies to be updated too.
The -N switch rebuilds the packages with the USE flags you’ve specified in /etc/make.conf - do this if you’ve changed them since your last emerge.
List all installed packages
To list all installed packages, you can use qpkg or equery, provided with the gentoolkit ebuild.
qpkg -I
Or:
equery list
See my equery notes for more on the equery command.
Rebuild applications that depend on a particular library
Sometimes an application will segfault with mention of a particular library, e.g. libjpeg.so.62 (I had this when thunar was crashing). If a solution can’t be found on the web, rebuild the apps that depend on the library to see if that fixes the problem:
revdep-rebuild --library libjpeg.so.62
Unstable and masked packages
If you attempt to emerge a package that’s unstable or masked, you’ll get a message informing you why the package can’t be installed (yet).
The following was lifted from Gentoo Linux Documentation – A Portage Introduction:
- ~arch keyword means that the application is not tested sufficiently to be put in the stable branch. Wait a few days or weeks and try again.
- -arch keyword or -* keyword means that the application does not work on your architecture. If you believe the package does work file a bug at our bugzilla](http://bugs.gentoo.org){:.weblink} website.
- missing keyword means that the application has not been tested on your architecture yet. Ask the architecture porting team to test the package or test it for them and report your findings on our bugzilla website.
- package.mask means that the package has been found corrupt, unstable or worse and has been deliberately marked as do-not-use.
- profile means that the package has been found not suitable for your profile. The application might break your system if you installed it or is just not compatible with the profile you use.
There are 2 types of mask - hard and soft, otherwise known as unstable. Hard masked packages have been listed in /usr/portage/profiles/package.mask and can be unmasked by editing /etc/portage/package.unmask. Soft masked (unstable) packages can be unmasked by editing /etc/portage/package.keywords.
Soft Masks (aka Unstable)
You can unmask a soft masked package by adding the package name to /etc/portage/package.keywords and optionally specifying the architecture. Useful operators include =, <=, <, >, >=, though you don’t have to use them.
[comparison operator][category]/[name] ~arch
For example:
app-office/mozilla-sunbird-bin ~x86
<=net-www/mod_auth_kerb-5.0
=www-apache/mod_jk-1.2.13 ~x86
Hard Masks
You can unmask a hard masked package by adding the package name to /etc/portage/package.unmask. Useful operators include =, <=, <, >, >=, one of which you have to use. Note that hard masked packages are not supported by Gentoo, so you won’t get any support from them if you hit problems.
[comparison operator][category]/[name]
For example:
<=net-www/mod_auth_kerb-5.0
=www-apache/mod_jk-1.2.13
Forcing specific version of a package
When the package version is (soft) masked, add it to /etc/portage/package.keywords:
=the-category/the-package-n.u.m
When the package version is not masked, the above setting in package.keywords will not work. Instead mask particular versions in /etc/portage/package.mask to force the version you want:
>the-category/the-package-n.u.m
Set services to start at a given runlevel
Add:
rc-update add [service] [runlevel]
Remove:
rc-update del [service] [runlevel]
The [service] must be in /etc/init.d/ and the [runlevel] must be in /etc/runlevels/.
Update profile
Follow the Gentoo Upgrading Guide, because it can be more complicated than the two commands listed below. You will need the eselect program installed.
To list all available profiles:
eselect profile list
To switch to profile [n]:
eselect profile set [n]
