Choosing the Right Stage

When we asked you to choose for an installation medium (LiveCDs, existing distribution etc.) we explained you what the pros and cons are. One of those was choosing your stage: do you go for a full compilation (stage1), skip the bootstrapping (stage2) or start from a precompiled stade (stage3)?

Depending on your installation medium, you can still make your choice. Others will already have made the choice at the beginning of the installation. It is now time to install your choice of stage. But first we'll configure Portage with the compiler optimizations you want and feature support you need.

Configuring the Compile Options Introduction

To optimize Gentoo, you can set a couple of variables which impact Portage behaviour. All those variables can be set as environment variables (using export) but that isn't permanent. To keep your settings, Portage provides you with /etc/make.conf, a configuration file for Portage. It is this file we will edit now.

Fire up your favorite editor (in this guide we use nano) so we can alter the optimization variables we will discuss hereafter.

# nano -w /etc/make.conf

As you probably notice now, the make.conf file is structured in a generic way: commented lines start with "#", other lines define variables using the VARIABLE="content" syntax. Several of those variables are discussed next.

CHOST Although it might be interesting for non-stage1 users, they should not change the CHOST setting in make.conf. Doing so might render their system unusable. Again: only change this variable if you use a stage1 installation.

The CHOST variable defines what architecture gcc has to compile programs for. The possibilities are:

x86i386i386-pc-linux-gnux86i486i486-pc-linux-gnux86i586i586-pc-linux-gnux86i686 and above (incl. athlon)i686-pc-linux-gnualphaalpha-unknown-linux-gnuppcpowerpc-unknown-linux-gnusparcsparc-unknown-linux-gnuhppa
Architecture Subarchitecture CHOST Setting
CFLAGS and CXXFLAGS

The CFLAGS and CXXFLAGS variables define the optimization flags for the gcc C and C++ compiler respectively. Although we define those generally here, you will only have maximum performance if you optimize these flags for each program seperately. The reason for this is because every program is different.

In make.conf you should define the optimization flags you think will make your system the most responsive generally. Don't place experimental settings in this variable; too much optimization can make programs behave bad (crash, or even worse, malfunction).

We will not explain all possible optimization options. If you want to know them all, read the GNU Online Manual(s) or the gcc info page (info gcc -- only works on a working Linux system).

A first setting is the -march= flag, which specifies the name of the target architecture. Possible options are described in the make.conf file (as comments). For instance, for the x86 Athlon XP architecture:

-march=athlon-xp

A second one is the -O flag, which specifies the gcc optimization class flag. Possible classes are s (for size-optimized), 0 (for no optimizations), 1, 2 or 3 for more speed-optimization flags (every class has the same flags as the one before, plus some extras). For instance, for a class-2 optimization:

-O2

Other popular optimization flags are -pipe (use pipes rather than temporary files for communication between the various stages of compilation) and -fomit-frame-pointer (which doesn't keep the frame pointer in a register for functions that don't need one).

When you define the CFLAGS and CXXFLAGS, you should combine several optimization flags, like in the following example:

CFLAGS="-march=athlon-xp -pipe -O3"
CXXFLAGS="${CFLAGS}"                  # Use the same settings for both variables
USE

USE is one of the most powerfull variables Gentoo provides to its users. Several programs can be compiled with or without optional support for certain items. For instance, some programs can be compiled with gtk-support, or with qt-support. Others can be compiled with or without SSL support. Some programs can even be compiled with framebuffer support (svgalib) instead of X11 support (X-server).

Most distributions compile their packages with support for as much as possible, increasing the size of the programs and startup time, not to mention an enormous amount of dependencies. With Gentoo you can define with what options a package should be compiled with. This is where USE comes into play.

In the USE variable you define keywords which are mapped onto compile-options. For instance, ssl will compile ssl-support in the programs that support it. -X will remove X-server support (note the minus sign in front). gnome gtk -kde -qt will compile your programs with gnome (and gtk) support, and not with kde (and qt) support, making your system fully tweaked for GNOME.

The default USE settings are placed in /etc/make.profile/make.defaults. What you place in /etc/make.conf is calculated against these defaults settings. If you add something to the USE setting, it is added to the default list. If you remove something from the USE setting (by placing a minus sign in front of it) it is removed from the default list (if it was in the default list at all). Never alter anything inside the /etc/make.profile directory; it gets overwritten when you update Portage!

A full description on USE can be found in our USE Howto. As an example we show a USE setting for a KDE-based system with DVD, ALSA and CD Recording support:

USE="-gtk -gnome qt kde dvd alsa cdr"
ACCEPT_KEYWORDS

Ebuilds (the package format Gentoo uses) are located in one out of three stadia. The first one is called ARCH, meaning that the ebuild and its dependencies are thought to be stable and ready for general acceptance. Most people want this. If you want your system to use packages from ARCH, then ACCEPT_KEYWORDS should contain your architecture (being x86, alpha, ppc, sparc or hppa):

ACCEPT_KEYWORDS="x86"

When an ebuild enters Portage, is first goes to ~ARCH, meaning that the developer who committed the ebuild sais it works on his box(es), but that the package needs more testing before it is moved to ARCH. If you want your system to use packages from ~ARCH, then ACCEPT_KEYWORDS should contain your architecture, prefixed by a tilde (~). Don't think this is the equivalent of "testing" or "unstable" in other distributions. Packages inside ~ARCH do occasionally break stuff! Some architectures don't even bootstrap succesfully if you use ~ARCH (notably SPARC).

ACCEPT_KEYWORDS="~x86"

If you want to use packages that are known to break your system, then you have dance with the devil and uncomment the packages in /usr/portage/profiles/package.mask. However, and this is a big fat warning:

Fiddling with package.mask is bad for your system, health and sense of humor. Do not touch it unless you drive a tank, wear a teflon vest 24h/7 and love to sit and wait until Gentoo is reinstalled again... and again... and again...
MAKEOPTS

With MAKEOPTS you define how many parallel compilations should occur when you install a package. The suggested number is the number of CPUs in your system plus one.

MAKEOPTS="-j2"
Ready, Set, Go!

Update your /etc/make.conf to your own will and save. You are now ready to install the stage you prefer onto your system.

The following two parts explain how to install your preferred stage. The default option here is to download your stage of choice from the internet. However, some LiveCDs have these stages available on the CD.

If you have a working Internet connection, you are advised to use the default option. If however you do not have a working Internet connection, or you want to install Gentoo using GRP (precompiled packages), then you have to choose for the alternative option.

  • Default: Downloading from the Internet
  • Alternative: Using a Stage from the LiveCD
Default: Downloading from the Internet Downloading the Stage Tarball

Go to the Gentoo mountpoint at which you mounted your filesystems (most likely /mnt/gentoo):

# cd /mnt/gentoo

Depending on your installation medium, you have a couple of tools available to download a stage. If you have lynx available, then you can immediately surf to the Gentoo mirrorlist and choose a mirror close to you. Then pick the releases/ directory, followed by your architecture (for instance x86/ and the Gentoo version (1.4/) to finish up with the stages/ directory. For there on you should see all available stage files for your architecture. Select one and press D to download. When you're finished, press Q to quit the browser.

# lynx http://www.gentoo.org/main/en/mirrors.xml

If you do not have lynx, you should have links2 at your disposal. links2 is more powerfull than lynx, but has some drawbacks. One of them is that it doesn't listen to the proxy variables we have declared previously. If you need to setup a proxy, use links2 -http-proxy proxy.server.com:8080. From there on, you should follow the same steps as with lynx as they are equivalent.

(Without proxy:)   # links2 http://www.gentoo.org/main/en/mirrors.xml
(With proxy:)      # links2 -http-proxy proxy.server.com:8080 http://www.gentoo.org/main/en/mirrors.xml
Unpacking the Stage Tarball

Now unpack your downloaded stage onto your system. We use GNU's tar to proceed as it is the easiest method:

# tar xvjpf stage?-*.tar.bz2

Make sure that you use the same options (xvjpf). The x stands for Extract, the v for Verbose (okay, yes, this is optional), the j for Decompress with bzip2, the p for Preserve permissions and the f to denote that we want to extract a file, not standard input.

Done? Okay, you are now ready to proceed with the next section on Installing the Gentoo Base System.

Alternative: Using a Stage from the LiveCD Extracting the Stage Tarball

The stages on the CD reside in the /mnt/cdrom/stages directory. To see a listing of available stages, use ls:

# ls /mnt/cdrom/stages

If the system replies with an error, you may need to mount the CD-ROM first:

# ls /mnt/cdrom/stages
ls: /mnt/cdrom/stages: No such file or directory
# mount /dev/cdroms/cdrom0 /mnt/cdrom
# ls /mnt/cdrom/stages

Now go into your Gentoo mountpoint (usually /mnt/gentoo):

# cd /mnt/gentoo

We will now extract the stage tarball of your choice. We will do this with the GNU tar tool. Make sure you use the same options (xvjpf)! In the next example, we extract the stage tarball stage3-20031011.tar.bz2. Be sure to substitute the tarball filename with your stage.

# tar xvjpf /mnt/cdrom/stages/stage3-20031011.tar.bz2
Installing a Portage Snapshot and Source Code

There is a Portage snapshot available on some LiveCDs. Since you are reading this, we can safely assume you are using such a LiveCD. To install this snapshot, take a look inside /mnt/cdrom/snapshots/ to see what snapshots we have available:

# ls /mnt/cdrom/snapshots

Now extract the snapshot of your choice using the following construct. Again, make sure you use the correct options to tar. Also, the -C is with a capital C, not c. In the next example we use portage-20031011.tar.bz2 as the snapshot filename. Be sure to substitute with your snapshot.

# tar xvjf /mnt/cdrom/snapshots/portage-20031011.tar.bz2 -C /mnt/gentoo/usr

You also need to copy over all source code from the CD.

# cp -R /mnt/cdrom/distfiles /mnt/gentoo/usr/portage/distfiles

If you want to use GRP (precompiled binaries), read on. Otherwise continue with Installing the Gentoo Base System.

Optional: Preparing GRP

If you want to install Gentoo using GRP (precompiled packages), you need to copy over all packages onto your filesystem so that Portage can use them.

# cp -a /mnt/cdrom/packages /mnt/gentoo/usr/portage/packages

Now continue with Installing the Gentoo Base System.