Difference between revisions of "Handbook:Main Page"

From Gentoo Wiki
Jump to:navigation Jump to:search
(Insert line break in order to better support translations of each section per Project_Talk:Handbook#Divide_translation_sections_in_Handbook:Main_Page.)
(Marked this version for translation)
Line 32: Line 32:
 
{{Note|The {{Keyword|arm}} and {{Keyword|arm64}} architectures ''are'' supported by the Gentoo project but do not yet have Handbooks at their disposal due to too many variations in SoCs. It is simply not practical for the Handbook project to maintain a cohesive set of installation instructions. Please refer to the [[Project:ARM|ARM]] or [[Project:ARM64|ARM64]] project pages and {{bug|534376}} for more information.<br /><br />
 
{{Note|The {{Keyword|arm}} and {{Keyword|arm64}} architectures ''are'' supported by the Gentoo project but do not yet have Handbooks at their disposal due to too many variations in SoCs. It is simply not practical for the Handbook project to maintain a cohesive set of installation instructions. Please refer to the [[Project:ARM|ARM]] or [[Project:ARM64|ARM64]] project pages and {{bug|534376}} for more information.<br /><br />
  
 +
<!--T:35-->
 
Equally, the {{Keyword|riscv}} architecture is supported, however there is no separate Handbook for it (yet). More information can be found on the [[Project:RISC-V|RISC-V project page]].}}
 
Equally, the {{Keyword|riscv}} architecture is supported, however there is no separate Handbook for it (yet). More information can be found on the [[Project:RISC-V|RISC-V project page]].}}
  
Line 39: Line 40:
 
:* Full sections: [[Handbook:Alpha/Full/Installation|Installation]] – [[Handbook:Alpha/Full/Working|Working]] – [[Handbook:Alpha/Full/Portage|Portage]] – [[Handbook:Alpha/Full/Networking|Networking]]
 
:* Full sections: [[Handbook:Alpha/Full/Installation|Installation]] – [[Handbook:Alpha/Full/Working|Working]] – [[Handbook:Alpha/Full/Portage|Portage]] – [[Handbook:Alpha/Full/Networking|Networking]]
  
 +
<!--T:36-->
 
; <span id="AMD64_Handbook">[[Handbook:AMD64|AMD64 Handbook]]</span>
 
; <span id="AMD64_Handbook">[[Handbook:AMD64|AMD64 Handbook]]</span>
 
: AMD64 is a 64-bit architecture that is compatible with the {{Keyword|x86}} architecture (and thus also known as {{c|x86_64}}). 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. Variants include: AMD Athlon 64, Opteron, Sempron, Phenom, FX, Ryzen, Threadripper, and Epyc along with Intel Pentium 4, Core2, Core i3, i5, i7, i9, Xeon, and some Atoms.
 
: AMD64 is a 64-bit architecture that is compatible with the {{Keyword|x86}} architecture (and thus also known as {{c|x86_64}}). 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. Variants include: AMD Athlon 64, Opteron, Sempron, Phenom, FX, Ryzen, Threadripper, and Epyc along with Intel Pentium 4, Core2, Core i3, i5, i7, i9, Xeon, and some Atoms.
 
:* Full sections: [[Handbook:AMD64/Full/Installation|Installation]] – [[Handbook:AMD64/Full/Working|Working]] – [[Handbook:AMD64/Full/Portage|Portage]] – [[Handbook:AMD64/Full/Networking|Networking]]
 
:* Full sections: [[Handbook:AMD64/Full/Installation|Installation]] – [[Handbook:AMD64/Full/Working|Working]] – [[Handbook:AMD64/Full/Portage|Portage]] – [[Handbook:AMD64/Full/Networking|Networking]]
  
 +
<!--T:37-->
 
; <span id="ARM_Handbook">ARM Handbook</span>
 
; <span id="ARM_Handbook">ARM Handbook</span>
 
: ARM is a 32-bit architecture that is a very popular in embedded and small systems. Sub-architectures range from ARMv2 to ARMv6 (legacy), to ARMv6-M (Cortex), as well as ARMv8-R and ARMv8-M and are often found in smart phones, tablets, hand-held consoles, end-user GPS navigation systems, etc. Variants include: StrongARM and Cortex-M.
 
: ARM is a 32-bit architecture that is a very popular in embedded and small systems. Sub-architectures range from ARMv2 to ARMv6 (legacy), to ARMv6-M (Cortex), as well as ARMv8-R and ARMv8-M and are often found in smart phones, tablets, hand-held consoles, end-user GPS navigation systems, etc. Variants include: StrongARM and Cortex-M.
 
:* There is no ARM Handbook available at this time. Please see the [[Project:ARM|ARM project page]] and {{bug|534376}} for more information about Gentoo's support for ARM.
 
:* There is no ARM Handbook available at this time. Please see the [[Project:ARM|ARM project page]] and {{bug|534376}} for more information about Gentoo's support for ARM.
  
 +
<!--T:38-->
 
; <span id="ARM64_Handbook">ARM64 Handbook</span>
 
; <span id="ARM64_Handbook">ARM64 Handbook</span>
 
: ARM64 is a 64-bit variant of ARM for embedded and server systems. The primary sub-architecture referred to as AArch64 (also known as ARMv8-A) is produced by a few manufacturers. AArch64 chips are seen in a variety of SoCs including developer boards, smart phones, tablets, smart TVs, etc. Variants include: ARM Holdings' Cortex-A53, A57, A72, A73, and Qualcomm's Kryo and Falkor.
 
: ARM64 is a 64-bit variant of ARM for embedded and server systems. The primary sub-architecture referred to as AArch64 (also known as ARMv8-A) is produced by a few manufacturers. AArch64 chips are seen in a variety of SoCs including developer boards, smart phones, tablets, smart TVs, etc. Variants include: ARM Holdings' Cortex-A53, A57, A72, A73, and Qualcomm's Kryo and Falkor.
 
:* There is no ARM64 Handbook available at this time. Please see the [[Project:ARM64|ARM64 project page]] and {{bug|534376}} for more information about Gentoo's support for ARM64.
 
:* There is no ARM64 Handbook available at this time. Please see the [[Project:ARM64|ARM64 project page]] and {{bug|534376}} for more information about Gentoo's support for ARM64.
  
 +
<!--T:39-->
 
; <span id="HPPA_Handbook">[[Handbook:HPPA|HPPA Handbook]]</span>
 
; <span id="HPPA_Handbook">[[Handbook:HPPA|HPPA Handbook]]</span>
 
: 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). Variants include: HP 9000 and PA-8600.
 
: 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). Variants include: HP 9000 and PA-8600.
 
:* Full sections: [[Handbook:HPPA/Full/Installation|Installation]] – [[Handbook:HPPA/Full/Working|Working]] – [[Handbook:HPPA/Full/Portage|Portage]] – [[Handbook:HPPA/Full/Networking|Networking]]
 
:* Full sections: [[Handbook:HPPA/Full/Installation|Installation]] – [[Handbook:HPPA/Full/Working|Working]] – [[Handbook:HPPA/Full/Portage|Portage]] – [[Handbook:HPPA/Full/Networking|Networking]]
  
 +
<!--T:40-->
 
; <span id="IA64_Handbook">[[Handbook:IA64|IA64 Handbook]]</span>
 
; <span id="IA64_Handbook">[[Handbook:IA64|IA64 Handbook]]</span>
 
: IA64 is a 64-bit architecture designed by Intel and used in their Intel Itanium processor series. This architecture is not compatible with {{Keyword|x86}} or {{c|x86_64}} (a.k.a. {{Keyword|amd64}}) and is mostly found in medium and high-end server series. Variants include: Intel Itanium.
 
: IA64 is a 64-bit architecture designed by Intel and used in their Intel Itanium processor series. This architecture is not compatible with {{Keyword|x86}} or {{c|x86_64}} (a.k.a. {{Keyword|amd64}}) and is mostly found in medium and high-end server series. Variants include: Intel Itanium.
 
:* Full sections: [[Handbook:IA64/Full/Installation|Installation]] – [[Handbook:IA64/Full/Working|Working]] – [[Handbook:IA64/Full/Portage|Portage]] – [[Handbook:IA64/Full/Networking|Networking]]
 
:* Full sections: [[Handbook:IA64/Full/Installation|Installation]] – [[Handbook:IA64/Full/Working|Working]] – [[Handbook:IA64/Full/Portage|Portage]] – [[Handbook:IA64/Full/Networking|Networking]]
  
 +
<!--T:41-->
 
; <span id="MIPS_Handbook">[[Handbook:MIPS|MIPS Handbook]]</span>
 
; <span id="MIPS_Handbook">[[Handbook:MIPS|MIPS Handbook]]</span>
 
: Developed by MIPS Technologies, the MIPS architecture comprises multiple subfamilies (called revisions) such as MIPS I, MIPS III, MIPS32, MIPS64 and more. MIPS is most common in embedded systems. Variants include: MIPS32 1074K and R16000.
 
: Developed by MIPS Technologies, the MIPS architecture comprises multiple subfamilies (called revisions) such as MIPS I, MIPS III, MIPS32, MIPS64 and more. MIPS is most common in embedded systems. Variants include: MIPS32 1074K and R16000.
 
:* Full sections: [[Handbook:MIPS/Full/Installation|Installation]] – [[Handbook:MIPS/Full/Working|Working]] – [[Handbook:MIPS/Full/Portage|Portage]] – [[Handbook:MIPS/Full/Networking|Networking]]
 
:* Full sections: [[Handbook:MIPS/Full/Installation|Installation]] – [[Handbook:MIPS/Full/Working|Working]] – [[Handbook:MIPS/Full/Portage|Portage]] – [[Handbook:MIPS/Full/Networking|Networking]]
  
 +
<!--T:42-->
 
; <span id="PPC_Handbook">[[Handbook:PPC|PPC Handbook]]</span>
 
; <span id="PPC_Handbook">[[Handbook:PPC|PPC Handbook]]</span>
 
: PPC is a 32-bit architecture used by many Apple, IBM, and Motorola processors. They are most commonly found in embedded systems. Variants include: Apple OldWorld, Apple NewWorld, generi Pegasos, Efika, older IBM iSeries and pSeries.
 
: PPC is a 32-bit architecture used by many Apple, IBM, and Motorola processors. They are most commonly found in embedded systems. Variants include: Apple OldWorld, Apple NewWorld, generi Pegasos, Efika, older IBM iSeries and pSeries.
 
:* Full sections: [[Handbook:PPC/Full/Installation|Installation]] – [[Handbook:PPC/Full/Working|Working]] – [[Handbook:PPC/Full/Portage|Portage]] – [[Handbook:PPC/Full/Networking|Networking]]
 
:* Full sections: [[Handbook:PPC/Full/Installation|Installation]] – [[Handbook:PPC/Full/Working|Working]] – [[Handbook:PPC/Full/Portage|Portage]] – [[Handbook:PPC/Full/Networking|Networking]]
  
 +
<!--T:43-->
 
; <span id="PPC64_Handbook">[[Handbook:PPC64|PPC64 Handbook]]</span>
 
; <span id="PPC64_Handbook">[[Handbook:PPC64|PPC64 Handbook]]</span>
 
: PPC64 is the 64-bit variant of the PPC architecture, popular in both embedded as well as high-end performance servers. Variants include: IBM RS/6000s, IBM pSeries, and IBM iSeries.
 
: PPC64 is the 64-bit variant of the PPC architecture, popular in both embedded as well as high-end performance servers. Variants include: IBM RS/6000s, IBM pSeries, and IBM iSeries.
 
:* Full sections: [[Handbook:PPC64/Full/Installation|Installation]] – [[Handbook:PPC64/Full/Working|Working]] – [[Handbook:PPC64/Full/Portage|Portage]] – [[Handbook:PPC64/Full/Networking|Networking]]
 
:* Full sections: [[Handbook:PPC64/Full/Installation|Installation]] – [[Handbook:PPC64/Full/Working|Working]] – [[Handbook:PPC64/Full/Portage|Portage]] – [[Handbook:PPC64/Full/Networking|Networking]]
  
 +
<!--T:44-->
 
; <span id="RISCV_Handbook">RISC-V Handbook</span>
 
; <span id="RISCV_Handbook">RISC-V Handbook</span>
 
: RISC-V is an upcoming 32-bit, 64-bit, and 128-bit architecture with an open instruction set. Currently, the 64-bit RISC-V variant is supported by Gentoo.  
 
: RISC-V is an upcoming 32-bit, 64-bit, and 128-bit architecture with an open instruction set. Currently, the 64-bit RISC-V variant is supported by Gentoo.  
 
:* There is no RISC-V Handbook available at this time. See the [[Project:RISC-V|RISC-V project page]] for more information about Gentoo's support for RISC-V.
 
:* There is no RISC-V Handbook available at this time. See the [[Project:RISC-V|RISC-V project page]] for more information about Gentoo's support for RISC-V.
  
 +
<!--T:45-->
 
; <span id="SPARC_Handbook">[[Handbook:SPARC|SPARC Handbook]]</span>
 
; <span id="SPARC_Handbook">[[Handbook:SPARC|SPARC Handbook]]</span>
 
: The SPARC architecture is best known by its most common producers, Sun Microsystems (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. Variants include: E3000, Blade 1000, and Ultra 2.
 
: The SPARC architecture is best known by its most common producers, Sun Microsystems (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. Variants include: E3000, Blade 1000, and Ultra 2.
 
:* Full sections: [[Handbook:SPARC/Full/Installation|Installation]] – [[Handbook:SPARC/Full/Working|Working]] – [[Handbook:SPARC/Full/Portage|Portage]] – [[Handbook:SPARC/Full/Networking|Networking]]
 
:* Full sections: [[Handbook:SPARC/Full/Installation|Installation]] – [[Handbook:SPARC/Full/Working|Working]] – [[Handbook:SPARC/Full/Portage|Portage]] – [[Handbook:SPARC/Full/Networking|Networking]]
  
 +
<!--T:46-->
 
; <span id="X86_Handbook">[[Handbook:X86|X86 Handbook]]</span>
 
; <span id="X86_Handbook">[[Handbook:X86|X86 Handbook]]</span>
 
: X86 is 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). Variants include: i486, i686, AMD Athlon, Intel Core, and some Intel Atoms.
 
: X86 is 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). Variants include: i486, i686, AMD Athlon, Intel Core, and some Intel Atoms.

Revision as of 21:01, 27 October 2021

The Gentoo Handbook is an effort to centralize documentation into a coherent handbook. This handbook contains the installation instructions for an Internet-based installation and additional sections for working with Gentoo's native software tools such as the OpenRC init system and the Portage package manager.

The Gentoo Handbook

Architectures

Gentoo Linux is available for many computer architectures.

An instruction set architecture (ISA) (wikipedia) or short 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, etc...

A distribution as versatile as Gentoo supports many architectures. Below you will find a quick summary of the supported architectures and the abbreviation used in Gentoo. Most people that do not know the architecture of their PC system are likely interested in amd64.

Viewing the Handbook

The list below gives a high-level overview of the architectures supported by various Gentoo Linux projects. It is important to choose the correct architecture before proceeding with the associated Installation section of a Handbook. Be sure to verify the CPU's architecture before moving onward.

A rule of thumb for new Gentoo users: If the CPU was manufactured after 2015 and the manufacturer is either Intel or AMD, choosing the AMD64 Handbook is probably the correct route.

Note
The arm and arm64 architectures are supported by the Gentoo project but do not yet have Handbooks at their disposal due to too many variations in SoCs. It is simply not practical for the Handbook project to maintain a cohesive set of installation instructions. Please refer to the ARM or ARM64 project pages and bug #534376 for more information.

Equally, the riscv architecture is supported, however there is no separate Handbook for it (yet). More information can be found on the RISC-V project page.
Alpha Handbook
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. Variants include: ES40, AlphaPC, UP1000, and Noname.
AMD64 Handbook
AMD64 is a 64-bit architecture that is compatible with the x86 architecture (and thus also known as x86_64). 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. Variants include: AMD Athlon 64, Opteron, Sempron, Phenom, FX, Ryzen, Threadripper, and Epyc along with Intel Pentium 4, Core2, Core i3, i5, i7, i9, Xeon, and some Atoms.
ARM Handbook
ARM is a 32-bit architecture that is a very popular in embedded and small systems. Sub-architectures range from ARMv2 to ARMv6 (legacy), to ARMv6-M (Cortex), as well as ARMv8-R and ARMv8-M and are often found in smart phones, tablets, hand-held consoles, end-user GPS navigation systems, etc. Variants include: StrongARM and Cortex-M.
  • There is no ARM Handbook available at this time. Please see the ARM project page and bug #534376 for more information about Gentoo's support for ARM.
ARM64 Handbook
ARM64 is a 64-bit variant of ARM for embedded and server systems. The primary sub-architecture referred to as AArch64 (also known as ARMv8-A) is produced by a few manufacturers. AArch64 chips are seen in a variety of SoCs including developer boards, smart phones, tablets, smart TVs, etc. Variants include: ARM Holdings' Cortex-A53, A57, A72, A73, and Qualcomm's Kryo and Falkor.
  • There is no ARM64 Handbook available at this time. Please see the ARM64 project page and bug #534376 for more information about Gentoo's support for ARM64.
HPPA Handbook
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). Variants include: HP 9000 and PA-8600.
IA64 Handbook
IA64 is 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 (a.k.a. amd64) and is mostly found in medium and high-end server series. Variants include: Intel Itanium.
MIPS Handbook
Developed by MIPS Technologies, the MIPS architecture comprises multiple subfamilies (called revisions) such as MIPS I, MIPS III, MIPS32, MIPS64 and more. MIPS is most common in embedded systems. Variants include: MIPS32 1074K and R16000.
PPC Handbook
PPC is a 32-bit architecture used by many Apple, IBM, and Motorola processors. They are most commonly found in embedded systems. Variants include: Apple OldWorld, Apple NewWorld, generi Pegasos, Efika, older IBM iSeries and pSeries.
PPC64 Handbook
PPC64 is the 64-bit variant of the PPC architecture, popular in both embedded as well as high-end performance servers. Variants include: IBM RS/6000s, IBM pSeries, and IBM iSeries.
RISC-V Handbook
RISC-V is an upcoming 32-bit, 64-bit, and 128-bit architecture with an open instruction set. Currently, the 64-bit RISC-V variant is supported by Gentoo.
  • There is no RISC-V Handbook available at this time. See the RISC-V project page for more information about Gentoo's support for RISC-V.
SPARC Handbook
The SPARC architecture is best known by its most common producers, Sun Microsystems (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. Variants include: E3000, Blade 1000, and Ultra 2.
X86 Handbook
X86 is 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). Variants include: i486, i686, AMD Athlon, Intel Core, and some Intel Atoms.

Frequently asked questions

Can't the Handbook be dynamically generated for each installation choice?

The handbook maintainers have opted to write on a per-architecture level using Gentoo's default init system (OpenRC) and basic partitioning schemes. The point of the Handbook is to get a bare-bones Gentoo system up and running, not to cover all possible installation paths (irregular partitioning, init systems, kernel configuration, system management utilities, etc.).

Concepts such as advanced partitioning, non-generic kernel configuration, and alternate init systems are explained other areas around the wiki in publicly modifiable namespace (hint: anyone with wiki account can edit them!).

We ask our readers to search wiki and discover what is already available before requesting a new section or addition to be added to the Handbook. If you believe a new generic section is necessary to add to the Handbook, then propose a request by following the instructions below.

I cannot find stage1 information in the Handbook. Where do I look?

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

How do I improve the Handbook?

Suggestions, comments, or ideas on how to make the Handbook better can be reported to the Handbook project via the Discussion page of the respective article. Documentation is made for the community, so community feedback is well appreciated.

Note
Active handbook editors are down to only two or three members, so please provide some patience as we respond to new {{Talk}} entries. See below for instruction on how to suggest a new improvement to the handbook.

Be aware that most decisions made while developing documentation are based on a consensus-model. It is impossible to write or structure documentation in such a way that renders every reader happy.

Those who open discussions with the goal of improving the Handbook must be able to accept a "No" as an answer. Typically "No" is used when we believe the current implementation is beneficial for the majority of readers.

In order to properly track open issues we ask you to add the {{Talk}} template to each discussion you open. Something similar to what is seen in the following example will suffice:

CODE Example open discussion
{{Talk|open|date=March 28, 2017}}
 
Hi Handbook team,
 
I constructively think FOO part of the Handbook can be enhanced in BAR way. Here is an example of the code/text that will make the improvement:
 
(insert code or text to be improved here.)
 
Thank you for considering my suggestion. --~~~~

The --~~~~ code at the end of the example inserts a dated signature when the page is saved or previewed. This code can either be typed in manually or generated by using the Signature and timestamp button in the edit toolbar. Wiki editors will refer to this as 'signing a discussion.' Please remember to sign each comment made on discussion pages.