Handbook:Parts/Installation/Base

Distribution files
In order to download source code quickly it is recommended to select a fast mirror. Portage will look in the file for the GENTOO_MIRRORS variable and use the mirrors listed therein. It is possible to surf to the Gentoo mirror list and search for a mirror (or mirrors) that is close to the system's physical location (as those are most frequently the fastest ones). However, we provide a nice tool called which provides users with a nice interface to select the mirrors needed. Just navigate to the mirrors of choice and press to select one or more mirrors.

Gentoo ebuild repository
A second important step in selecting mirrors is to configure the Gentoo ebuild repository via the file. This file contains the sync information needed to update the package repository (the collection of ebuilds and related files containing all the information Portage needs to download and install software packages).

Configuring the repository can be done in a few simple steps. First, if it does not exist, create the directory:

Next, copy the Gentoo repository configuration file provided by Portage to the (newly created) directory:

Take a peek with a text editor or by using the command. The inside of the file should be in format and look like this:

The default sync-uri variable value listed above will determine a mirror location based on a rotation. This will aid in easing bandwidth stress on Gentoo's infrastructure and will provide a fail-safe in case a specific mirror is offline. It is recommended the default URI is retained unless a local, private Portage mirror will be used.

Copy DNS info
One thing still remains to be done before entering the new environment and that is copying over the DNS information in. This needs to be done to ensure that networking still works even after entering the new environment. contains the name servers for the network.

To copy this information, it is recommended to pass the  option to the  command. This ensures that, if is a symbolic link, that the link's target file is copied instead of the symbolic link itself. Otherwise in the new environment the symbolic link would point to a non-existing file (as the link's target is most likely not available inside the new environment).

Mounting the necessary filesystems
In a few moments, the Linux root will be changed towards the new location. To make sure that the new environment works properly, certain filesystems need to be made available there as well.

The filesystems that need to be made available are:


 * which is a pseudo-filesystem (it looks like regular files, but is actually generated on-the-fly) from which the Linux kernel exposes information to the environment
 * which is a pseudo-filesystem, like which it was once meant to replace, and is more structured than
 * is a regular file system, partially managed by the Linux device manager (usually ), which contains all device files
 * is a temporary file system used for files generated at runtime, such as PID files or locks

The location will be mounted on  whereas the others are bind-mounted. The latter means that, for instance, will actually be  (it is just a second entry point to the same filesystem) whereas  is a new mount (instance so to speak) of the filesystem.

Entering the new environment
Now that all partitions are initialized and the base environment installed, it is time to enter the new installation environment by chrooting into it. This means that the session will change its root (most top-level location that can be accessed) from the current installation environment (installation CD or other installation medium) to the installation system (namely the initialized partitions). Hence the name, change root or chroot.

This chrooting is done in three steps:


 * 1) The root location is changed from  (on the installation medium) to  (on the partitions) using chroot
 * 2) Some settings (those in ) are reloaded in memory using the  command
 * 3) The primary prompt is changed to help us remember that this session is inside a chroot environment.

From this point, all actions performed are immediately on the new Gentoo Linux environment. Of course it is far from finished, which is why the installation still has some sections left!

Installing a Gentoo ebuild repository snapshot from the web
Next step is to install a snapshot of the Gentoo ebuild repository. This snapshot contains a collection of files that informs Portage about available software titles (for installation), which profiles the system administrator can select, package or profile specific news items, etc.

The use of is recommended for those who are behind restrictive firewalls (it uses HTTP/FTP protocols for downloading the snapshot) and saves network bandwidth. Readers who have no network or bandwidth restrictions can happily skip down to the next section.

This will fetch the latest snapshot (which is released on a daily basis) from one of Gentoo's mirrors and install it onto the system:

From this point onward, Portage might mention that certain updates are recommended to be executed. This is because system packages installed through the stage file might have newer versions available; Portage is now aware of new packages because of the repository snapshot. Package updates can be safely ignored for now; updates can be delayed until after the Gentoo installation has finished.

Optional: Updating the Gentoo ebuild repository
It is possible to update the Gentoo ebuild repository to the latest version. The previous command will have installed a very recent snapshot (usually recent up to 24h) so this step is definitely optional.

Suppose there is a need for the last package updates (up to 1 hour), then use. This command will use the rsync protocol to update the Gentoo ebuild repository (which was fetched earlier on through ) to the latest state.

On slow terminals, like some framebuffers or serial consoles, it is recommended to use the  option to speed up the process:

Reading news items
When the Gentoo ebuild repository is synchronized, Portage may output informational messages similar to the following:

News items were created to provide a communication medium to push critical messages to users via the Gentoo ebuild repository. To manage them, use. The application is a Gentoo-specific utility that allows for a common management interface for system administration. In this case, is asked to use its   module.

For the  module, three operations are most used:


 * With  an overview of the available news items is displayed.
 * With  the news items can be read.
 * With  news items can be removed once they have been read and will not be reread anymore.

More information about the news reader is available through its manual page:

Choosing the right profile
A profile is a building block for any Gentoo system. Not only does it specify default values for USE, CFLAGS , and other important variables, it also locks the system to a certain range of package versions. These settings are all maintained by Gentoo's Portage developers.

To see what profile the system is currently using, run using the   module:

As can be seen, there are also desktop subprofiles available for some architectures.

After viewing the available profiles for the architecture, users can select a different profile for the system:

Updating the @world set
At this point, it is wise to update the system's @world set so that a base can be established.

This following step is necessary so the system can apply any updates or USE flag changes which have appeared since the stage3 was built and from any profile selection:

Configuring the USE variable
USE is one of the most powerful 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 support for GTK+ or with support for Qt. 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 users can define what options a package should be compiled with. This is where USE comes into play.

In the USE variable users define keywords which are mapped onto compile-options. For instance,  will compile SSL support in the programs that support it. will remove X-server support (note the minus sign in front). will compile programs with GNOME (and GTK+) support, and not with KDE (and Qt) support, making the system fully tweaked for GNOME (if the architecture supports it).

The default USE settings are placed in the files of the Gentoo profile used by the system. Gentoo uses a (complex) inheritance system for its profiles, which we will not dive into at this stage. The easiest way to check the currently active USE settings is to run and select the line that starts with USE:

A full description on the available USE flags can be found on the system in.

Inside the command, scrolling can be done using the  and  keys, and exited by pressing.

As an example we show a USE setting for a KDE-based system with DVD, ALSA, and CD recording support:

When a USE value is defined in it is added to the system's USE flag list. USE flags can be globally removed by adding a minus sign in front of the value in the the list. For example, to disable support for X graphical environments,  can be set:

CPU_FLAGS_*
Some architectures (including AMD64/X86, ARM, PPC) have a USE_EXPAND variable called CPU_FLAGS_ARCH (replace ARCH with the relevant system architecture as appropriate).

This is used to configure the build to compile in specific assembly code or other intrinsics, usually hand-written or otherwise extra, and is not the same as asking the compiler to output optimized code for a certain CPU feature (e.g. ).

Users should set this variable in addition to configuring their COMMON_FLAGS as desired.

A few steps are needed to set this up:

Inspect the output manually if curious:

Then copy the output into :

VIDEO_CARDS
The VIDEO_CARDS USE_EXPAND variable should be configured appropriately depending on the available GPU(s). The Xorg guide covers how to do this. Setting VIDEO_CARDS is not required for a console only install.

Optional: Configure the ACCEPT_LICENSE variable
The licenses of a Gentoo package are stored in the LICENSE variable in the ebuild. The accepted specific licenses or groups of licenses of a system are defined in the following files


 * system wide in the profile
 * system wide in
 * per package in.

Portage looks up in the ACCEPT_LICENSE which packages to allow for installation. In order to print the current system wide value run:

Optionally override the system wide accepted default in the profiles by changing.

Optionally one can also define accepted licenses per package as shown in this example:

The license groups defined in the Gentoo repository, managed by the Gentoo Licenses project, are:

module.

With, the available targets are displayed:

With the correct locale can be selected:

Manually, this can still be accomplished through the file and for Systemd the  file:

Setting the locale will avoid warnings and errors during kernel and software compilations later in the installation.

Now reload the environment:

For additional guidance through the locale selection process read also the Localization guide and the UTF-8 guide.