This is in no way a "Howto" for Gentoo Linux, nor is it a tutorial for advanced users wishing the squeeze every drop of performance out of their gentoo machines. All this is, is a small repository of general, buthelpful knowledge, that almost every gentoo user already knows, but wished they knew when they first setup their machines. Iam assuming you have a basic knowledge about linux, portage, the emerge command, and the basic structure of gentoo's packagesystem.

Basic portage use

First off, before you ever emerge anything, ALWAYS do a 'emerge -p packagename' first. the '-p' (or '--pretend') tests the emerge and shows you what packages that it depends on will be emerged along with it and in what order this will happen. Extremely helpfull in situation where you emerge vim and it starts emerging XFree86 for some strange reason. The output of this will look like this (example, not real results):

[ebuild R ] media-libs/libogg-1.0
[ebuild N ] app-arch/unzip-5.50-r1
[ebuild U ] media-sound/cdparanoia-3.9.8 [3.9.7]
[ebuild N ] media-libs/libungif-4.1.0.1b
[ebuild UD] dev-lang/nasm-0.98.34 [0.99]
[ebuild F ] apps-emulation/winex-transgaming-3.2

the 'R' means you have this package at the same version, and emergeing it will simply replace the current one.
the 'N' means its new. You don't have any version of this package installed yet.
the 'U' means emerge will upgrade your outdated package version (in brackets) with this one.
the 'UD' means emerge will downgrade your package [in brackets] to this one.
the 'F' means emerge cannot automatically download the files required to emerge this package, you will need to obtain the file yourself (usually from the application's website) and place it in /usr/portage/distfiles.

You'll notice on packages that will be updated, there is another set of numbers in brackets at the end of its entry. This is the version you have currently installed.

Second largest complaint (by me when I was starting out that is) by far was having to track down specific package names. By typing 'emerge -s foo', emerge will list packages that have names or descriptions that include "foo". Example: say you want flash for mozilla (or netscape or phoenix), but don't know the name of the package for the flash plugin, simply type 'emerge -s flash', and listed (among a couple other things) will be:

* net-www/netscape-flash
Latest version available: 6.0.79
Latest version installed: [ Not Installed ]
Size of downloaded files: 1,374 kB
Homepage: http://www.macromedia.com/
Description: Macromedia Shockwave Flash Player

By the looks of the description line, this is what we are looking for, and we can see from the first line that the name of the ebuild is "netscape-flash" and it's in the "net-www" category. So naturally you can install it by emering the ebuild: "emerge netscape-flash".

And, incase there are a few that didn't get it, 'emerge rsync' will update your list of packages with the freshest available ones.

Portage Directories

/usr/portage
This directory includes all the ebuild packages used by emerge. not really useful, but nice to know.

/usr/portage/distfiles
This directory is where emerge places the tar balls after it downloads them. They remain here even after the package been installed, so if your short on space you can clean this out every now and then.

/var/tmp/portage
This directory is where emerge extracts the tarballs to for compilation. Unlike the distfiles directory above, these 'work' directories are cleaned out after the package is installed.

/etc/make.conf

make.conf if the file portage uses to determine how to compile the application you emerge. It has quite a few

variables in it that change the way the programs with be built. Here I'll go over a few important ones that are

exetremely helpful to understand:

• USE : Items added to this will cause emerge to compile application with support (if applicable) for the items your added. i.e.: if you have USE="postgres" and compile php, it will automatically compile it with the --with-postgres argument (or whatever argument is) that adds postgres connectivity support to php. Inversely, you can say USE="-postgres" and software that will usually include postgres support will exclude it if possible. A complete list of aliases to be used in the USE argument can be found in /usr/portage/profiles/use.desc
• CHOST : Don't really know what this does, but leave it as CHOST="i686-pc-linux-gnu" unless you have a pentium or less, then just downgrade the '686' part of it to match your processor's family.
• CFLAGS: This is the arguments that emerge will pass to gcc during compile time that describe your processor so that processor specific optimizations can be used if applicable. A quick search on the Gentoo Forums for your proccessor type and the word "CFLAGS" will usually land you in the right vicinity of where you want to be.
• CXXFLAGS: Same as CFLAGS, for different gcc compiler, by default inherits CFLAGS's value.
• ACCEPT_KEYWORDS : Turn on the ability to download 'masked' packages. More on this later on.
• GENTOO_MIRRORS : URLS (other than Ibiblio) that emerge can download the packages from. I wouldn't suggest editing this by hand, there is a far easier way, explained a little bit later.

Masked packages

a "Masked" package is one that the author still considers as unstable, or still undergoing testing, and portage will not allow you to emerge them unless you specifically tell it to. For example, babygimp, an icon editor, is currently masked. If I were to type 'emerge babygimp', it would tell me "all ebuilds that could satisfy "babygimp" have been masked." But, If I wereto type 'emerge -s babygimp', I would get this:

In order to emerge this package, you will need to set /etc/make.conf 's ACCEPT_KEYWORDS argument to allow masked packages for your processor architecture to be emerged by uncommenting ACCEPT_KEYWORDS and setting it as follows:

ACCEPT_KEYWORDS="~x86"

The way this works is that ebuild writers define what system architechtures the package can compile on, and note it like "x86 ", or "PPC". If a package is in an unstabe state of development, its noted by prefixing a tilde to which architechtures the p ackage is currently unstable for.

BUT! Instead of changing it in make.conf (which you can forget, which can and will happen, and which screws your system), you can do it for just one instance of emerge by typing it all on one line like this:

ACCEPT_KEYWORDS="~x86" emerge babygimp

(or you can type this to see it pretend to work)

ACCEPT_KEYWORDS="~x86" emerge -p babygimp

(PS: you can do this "all on the same line" technique with all the arguments from make.conf, but it's only really helpfull fo r USE and ACCEPT_KEYWORDS)

mirrorselect

If your getting kind of aggravated by the download speeds emerge is giving you, you can fill you list of available mirrors au tomatically with a program called mirrorselect. Just simply emerge mirrorselect (or emerge -p mirrorselect to see all that it s going to install) to get it.

Then you can type:
mirrorselect -a -s5

for it to automatically populate your GENTOO_MIRRORS with the 5 fastest mirrors it can find (the 5 comes from the -s5, which you can supply any number for).

Distcc

Now that we have the downloading part of emerge sped up, what can we do about the compile times? Well, distcc can distribute the compilation of the files (most of the time) to other computers on your network, assuming, of course, that these other computers have distcc and the same version of the gcc compiler. And, seeing as we're running the rock and roll gentoo distro, to get it all you have to do is emerge distcc. There are a couple things you need to add to your make.conf file to get it working though:

• MAKEOPTS="-j5" - Actually, I'm not certain on this, but this is what I've gathered: the '5' is how many gcc threads to spawn, and you want around 2 per computer in the cluster.
• FEATURES="distcc ccache" - No idea, it just says you have to put that in there.
• DISTCC_HOSTS="host1 host2 host3" - Hosts in the cluster, running distcc, in order of priority (you usually want the local machine as the first one)
• DISTCC_LOG="/var/log/distcc.log" - Where to log the distcc activity

In order for a machine on the cluster to accept and process distcc requests, it must be running the distcc daemon, which Gentoo places (along side all the other daemon scripts) in /etc/init.d/. If you wish to see if a certain computer in thecluster is actually receiving and processing the distcc requests, the daemon logs all distcc client activity to /var/log/daemon.log.

Daemons and Runlevels

As with most distributions, Gentoo creates scripts to start and stop daemons and places them in /etc/init.d. These scripts read the configuration of each service from matching files in /etc/conf.d. For example, /etc/init.d/postgresql starts and stops the posgres database. If you wanted to add a commandline argument to postgres when this scripts runsit, you would edit /etc/conf.d/postgresql and find where it is assigning the commandline arguments and add it there.

To automatically start daemons at bootup at certain runlevels, you use a tool called rc-update. The syntax for this is as follows:

rc-update

You choose add or del depending on whether your adding a script to that runlevel or removing it. For the script, you just type the script's name from /etc/init.d. The runlevels available are boot, default, nonetwork, and single. You will use default is the one you will be manipulating 99.999% of the time, so that's the one I'll focus on.

As an example, the script for starting or stoping ssh is /etc/init.d/sshd. To get this to start automatically when you start the machine, you would type:

rc-update add sshd default

If this document has been of any help to you, or if you want something, or think something should be added, shoot me some feedback.

bkelly.
This document was last updated on 10/17/2003.