Gentoo Basics

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 http://www.gentoo.org before reading anything here. This page is simply my short cut to the information I most regularly require.

First, some links to Gentoo documentation I've used...

• Gentoo Linux x86 Handbook
  • 1. A Portage Introduction - documentation on usage of emerge.
  • 2. USE flags - documentation on configuring use flags.
  • 3. Mixing Software Branches - documentation on using unstable (soft masked) packages, (hard) masked packages and use of the ACCEPT_KEYWORDS variable.
  • 4. Initscripts - documentation on the configuration of initialisation scripts.
  • 7. Configuring the Kernel - documentation on configuring the kernel, both manually or using genkernel.
• 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

...and some Gentoo documentation I will use.

• Using UTF-8 with Gentoo

Other links to useful resources:

• My notes on Installing Gentoo Linux on an Acer Travelmate 8104WLMi
• My Gentoo Links.

Index

• System files
• Program files
• Installing and uninstalling packages
• Searching for available packages
• Updating environment
• Update portage tree
• Update installed packages
• List all installed packages
• Unstable and masked packages
• Set services to start at a given runlevel
• Update profile

System files | Go to top

Tabulated below are a number of files and directories relevant to the Gentoo distribution. Many are common to most Linux distributions.

Program files | Go to top

bsetbg -f /location/of/background/image.jpg &
xterm &
exec fluxbox

Installing and uninstalling packages | Go to top

emerge -av whatever

and

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.

Searching for available packages | Go to top

emerge -Ss string

searches for packages whos description and name matches the string. It is case and space insensitive (e.g. if the term is something it'll match SomeThing and something).

Updating environment | Go to top

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:

etc-update

To update the environment variables:

env-update

You can then run source /etc/profile to start using the new environment.

Update portage tree | Go to top

emerge --sync

or if you can't use rsync because of firewall restrictions:

emerge-webrsync

Update installed packages | Go to top

To update system packages:

emerge -u system

and to update all packages:

emerge -u 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 | Go to top

To list all installed packages, you can use qpkg or equery, provided with the gentoolkit ebuild.

qpkg -I

Or

equery list

Unstable and masked packages | Go to top

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).

• ~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 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

Set services to start at a given runlevel | Go to top

rc-update add service runlevel

and

rc-update del service runlevel

The service must be in /etc/init.d/ and the runlevel must be in /etc/runlevels/.

Update profile | Go to top

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]