Handbook:Parts/Installation/Stage

Setting the date and time
Before installing Gentoo, make sure that the date and time are set correctly. A mis-configured clock may lead to strange results in the future!

To verify the current date and time, run :

If the date/time displayed is wrong, update it using the  syntax (Month, Day, hour, minute and Year). At this stage, it is recommended to use UTC time. Later on during the installation, the timezone will be defined.

For instance, to set the date to March 29th, 16:21 in the year 2014:

Downloading the stage tarball
Go to the Gentoo mount point where the root file system is mounted (most likely ):

Depending on the installation medium, there are a couple of tools available to download a stage. One of these tools is, a non-graphical, menu-driven browser. To download a stage, surf to the Gentoo mirror list like so:

To use an HTTP proxy with, pass on the URL with the  option:

Next to there is also the  browser. Like it is a non-graphical browser but it is not menu-driven.

If a proxy needs to be defined, export the http_proxy and/or ftp_proxy variables:

On the mirror list, select a mirror close by. Usually HTTP mirrors suffice, but other protocols are available as well. Move to the directory. There all available stage files are displayed (they might be stored within subdirectories named after the individual sub-architectures). Select one and press to download.

Like with the minimal installation CDs, additional downloads are available:


 * A file that contains a list of all files inside the stage tarball
 * A file that contains checksums of the stage file, in different algorithms
 * A file that, like the  file, contains checksums of the stage file in different algorithms, but is also cryptographically signed to ensure it is provided by the Gentoo project

When finished, press to quit the browser.

After downloading the stage file, it is possible to verify the integrity of the downloaded stage tarball. Use and compare the output with the checksums provided by the  or  file.

For instance, to validate the SHA512 checksum:

Another way is to use the command:

To validate the Whirlpool checksum:

Compare the output of these commands with the value registered in the files. The values need to match, otherwise the downloaded file might be corrupt (or the digests file is).

Just like with the ISO file, it is also possible to verify the cryptographic signature of the file using  to make sure the checksums have not been tampered with:

Unpacking the stage tarball
Now unpack the downloaded stage onto the system. We use to proceed:

Make sure that the same options ( and  ) are used. The x stands for Extract, the v for Verbose to see what happens during the extraction process (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. Finally, the  is to include the extended attributes stored in the archive as well.

Now that the stage is installed, continue with Configuring the compile options.

Introduction
To optimize Gentoo, it is possible to set a couple of variables which impacts the behavior of Portage, Gentoo's officially supported package manager. All those variables can be set as environment variables (using ) but that isn't permanent. To keep the settings, Portage reads in the file, a configuration file for Portage.

There is currently only one officially supported package manager for Gentoo, however alternatives to Portage do exist! Paludis is a semi-popular alternative package manager found in the main Gentoo repository. From here on out the Handbook will presume Portage will be used as the system's package manager.

Fire up an editor (in this guide we use ) to alter the optimization variables we will discuss hereafter.

From the file it is obvious how the file should be structured: commented lines start with "#", other lines define variables using the VARIABLE="content" syntax. Several of those variables are discussed next.

CFLAGS and CXXFLAGS
The CFLAGS and CXXFLAGS variables define the optimization flags for the GCC C and C++ compiler respectively. Although those are defined generally here, for maximum performance one would need to optimize these flags for each program separately. The reason for this is because every program is different. However, this is not manageable, hence the definition of these flags in the file.

In one should define the optimization flags that will make the 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. To understand them all, read the GNU Online Manual(s) or the gcc info page ( - only works on a working Linux system). The file itself also contains lots of examples and information; don't forget to read it too.

A first setting is the  or   flag, which specifies the name of the target architecture. Possible options are described in the file (as comments). A commonly used value is native as that tells the compiler to select the target architecture of the current system (the one users are installing Gentoo on).

A second one is the  flag (that is a capital O, not a zero), which specifies the gcc optimization class flag. Possible classes are s (for size-optimized), 0 (zero - for no optimizations), 1, 2 or even 3 for more speed-optimization flags (every class has the same flags as the one before, plus some extras). is the recommended default. is known to cause problems when used system-wide, so we recommend to stick to.

Another popular optimization flag is  (use pipes rather than temporary files for communication between the various stages of compilation). It has no impact on the generated code, but uses more memory. On systems with low memory, gcc might get killed. In that case, do not use this flag.

Using  (which doesn't keep the frame pointer in a register for functions that don't need one) might have serious repercussions on the debugging of applications.

When the CFLAGS and CXXFLAGS variables are defined, combine the several optimization flags in one string. The default values contained in the stage3 archive that is unpacked should be good enough. The following one is just an example:

MAKEOPTS
The MAKEOPTS variable defines how many parallel compilations should occur when installing a package. A good choice is the number of CPUs (or CPU cores) in the system plus one, but this guideline isn't always perfect.

Ready, set, go
Update the file to match personal preference and save (nano users would hit +).

Then continue with Installing the Gentoo base system.