Gentoo Handbook

1. The Gentoo Handbook Effort

The Gentoo Handbook is available in the following languages:

Welcome to the Gentoo Handbook page. This page will give you some explanation about the Gentoo Handbook and should answer most of your questions regarding the handbook. We will talk about the ideas behind the handbook, its current status, the future plans, how bug reports are handled, etc.

Architectures

Gentoo Linux is available for many architectures. But what exactly is an architecture?

An architecture is a family of CPUs (processors) who support the same instructions. The two most prominent architectures in the desktop world are the x86 architecture and the x86_64 architecture (for which Gentoo uses the amd64 notation). But many other architectures exist, such as sparc, ppc (the PowerPC family), mips, arm, ...

A distribution as versatile as Gentoo supports many architectures. For that reason, you'll find that our Gentoo Handbooks are offered for many of the supported architectures. However, that might lead to some confusion as not all users are aware of the differences. Some are only aware of the CPU type or name that their system is a part of (like i686 or Intel Core i7). Below you will find a quick summary of the supported architectures and the abbreviation used in Gentoo. However, most people that do not know the architecture of their system are mostly interested in x86 or amd64.

Note: The table below gives a high-level overview of the supported architectures. The example set of CPUs or systems is nothing more than an example. If you are still not certain which architecture to pick, please read the first section of the Gentoo Handbook's second chapter (Choosing the Right Installation Medium) as this will elaborate on the supported platforms.

Architecture	Description	Sample set of CPUs or systems
x86	A 32-bit architecture used by CPUs that are often said to be "Intel compatible". It was, until recently, the most popular architecture for desktop PCs. Gentoo offers builds for i486 (supports all families) and i686 (supports Pentium and higher or compatible).	i486, i686, Intel Core, AMD Athlon, Intel Atom
x86_64 (amd64)	A 64-bit architecture that is compatible with the x86 architecture. It was first used by AMD (under the AMD64 name) and Intel (under the EM64T name) and is now the most prominent architecture for medium and high-end desktop PCs. It is also commonly found in the server segment.	AMD Athlon 64, AMD Opteron, AMD Sempron processors, AMD Phenom, Intel Pentium 4, Pentium Core i3, i5, i7
ia64	A 64-bit architecture designed by Intel and used in their Intel Itanium processor series. This architecture is not compatible with x86 or x86_64 (aka amd64) and is mostly found in medium and high-end server series.	Intel Itanium
sparc	The SPARC architecture is best known by its most common producers, Sun (now Oracle) and Fujitsu. It is used in server systems although a few workstations exist as well. In Gentoo, only SPARC64 compatible CPUs are supported.	E3000, Blade 1000, Ultra 2
ppc	A 32-bit architecture used by many Apple, IBM and Motorola processors. They are most commonly found in embedded systems.	Apple OldWorld, Apple NewWorld, generi Pegasos, Efika, older IBM iSeries and pSeries
ppc64	The 64-bit variant of the PPC architecture, popular in both embedded as well as high-end performance servers.	IBM RS/6000s, IBM pSeries, IBM iSeries
alpha	The Alpha architecture is a 64-bit architecture developed by Digital Equipment Corporation (DEC). It is still in use by some mid-range and high-end servers, but the architecture is slowly being faded out.	ES40, AlphaPC, UP1000, Noname
PA-RISC (hppa)	Referred to as HPPA, the PA-RISC architecture is an instruction set developed by Hewlett-Packard and was used in their mid- and high-end server series until about 2008 (after which HP started using Intel Itanium)	HP 9000, PA-8600
mips	Developed by MIPS Technologies, the MIPS architecture entails multiple subfamilies (called revisions) such as MIPS I, MIPS III, MIPS32, MIPS64 and more. MIPS is most common in embedded systems.	MIPS32 1074K, R16000
arm	This 32-bit architecture is a very popular architecture for embedded and small systems. Subarchitectures range from ARMv1 to ARMv7 (Cortex) and are often found in smartphones, tablets, handheld consoles, end-user GPS navigation systems, etc.	StrongARM, Cortex-M

2. View the Handbook

Assuming that you know (or at least have an idea) which architecture your system is using, you can now select your choice of handbook.

Format	Description	Links
HTML	Latest version, one page per chapter, perfect for online viewing	x86, sparc, amd64, ppc, ppc64, alpha, hppa, mips, ia64, arm
HTML	Latest version, all in one page	x86, sparc, amd64, ppc, ppc64, alpha, hppa, mips, ia64, arm
HTML	Latest version, all in one page, printable version	x86, sparc, amd64, ppc, ppc64, alpha, hppa, mips, ia64, arm

Historical Releases

For historical reasons we also keep the handbook versions for older releases (since 2004.2). Printable versions of individual pages can be reached through the "Print" link on the top right corner. To have an all-in-one-page version, add ?full=1 to the URL.

Warning: These handbooks are not maintained.

Release	Architectures
2004.2	alpha, amd64, hppa, mips, ppc, sparc, x86
2004.3	amd64, hppa, ppc, sparc, x86
2005.0	alpha, amd64, hppa, ppc, sparc, x86
2005.1	alpha, amd64, hppa, ppc, ppc64, sparc, x86
2006.0	alpha, amd64, hppa, ppc, ppc64, sparc, x86
2006.1	alpha, amd64, hppa, ppc, ppc64, sparc, x86
2007.0	amd64, hppa, ppc, ppc64, sparc, x86
2008.0	amd64, hppa, ppc, ppc64, sparc, x86

3. Information about the handbook

Goal

The goal of the Gentoo Handbook is to create a coherent document that describes every possible aspect of Gentoo Linux. It combines already existing guides in one consistent book, targeting a specific architecture, so that the entire document can be used as a single resource for installing and administering Gentoo Linux.

Many parts of the different Gentoo Handbooks (different by architecture) are copied across all handbooks (actually, it is written once and duplicated automatically) to make sure that the general information and quality of the documentation remains consistent.

Reporting bugs and enhancement requests

If you find a bug in the handbook, please visit our Gentoo Linux Bugzilla and create a bug for Documentation, Component Installation Handbook.

4. Frequently Asked Questions

Can't you magically have the handbook dynamically created for each choice?

Everything is possible, but we have opted to only do this on a per-architecture level. Other choices, like partitioning, kernel selection, tool installation and more are easy enough to explain in a single document.

I can't find stage1 information in the Gentoo Handbook

Instructions on using a stage1 or stage2 tarball are now available in the Gentoo FAQ. A stage3 installation is the only supported installation as of now.

I disagree with ...

Please report your idea; disagreeing without providing us with constructive feedback doesn't help the situation. Documentation is made for the community, so community feedback is well appreciated.

However, you must know that most decisions made while developing documentation are based on a consensus-model. It is impossible to write/structure documentation in such a way that everybody is happy with it. You must be able to accept a "No" with the reason that we believe the current implementation benefits most people.

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.

Page updated February 11, 2013

Summary: The Gentoo Handbook is an effort to centralise documentation into a coherent handbook. This handbook contains the installation instructions for internet-based installation approaches and parts about working with Gentoo and Portage.

Sven Vermeulen
Author

Donate to support our development efforts.