Handbook Talk:Parts/Installation/Base
This is a Talk page - please see the documentation about using talk pages. Add newer comments below older ones, sign comments using four tildes (
~~~~), and indent successive comments with colons (:).
Add new sections at the bottom of the page, under a heading (== ==). Please remember to mark sections as "open for discussion" using {{talk|open}}, so they will show up in the list of open discussions.Use validated snapshots
The section Installing a portage snapshot should include snapshot validation.
There is Handbook:Parts/Installation/Media#Verifying_the_downloaded_files and mention of gpg in Handbook:Parts/Installation/Stage#Downloading_the_stage_tarball. But here in Installing a portage snapshot, validation gets lost. --Charles17 (talk) 07:12, 23 May 2015 (UTC)
- Very soon we hope to have the gentoo-keys keyring and the gkeys app as part of the install media and a stage4 which will contain them both. At that time, it will become possible to easily verify any downloads during the installation process as well as the early chroot work. Dol-sen (talk) 13:22, 23 May 2015 (UTC)
- For the time until that takes place the handbook should be restored according to bug #507774#c9 ("the old tar based way of unpacking the portage tree and explain how to verify it's keys").--Charles17 (talk) 07:49, 22 January 2016 (UTC)
- Closing this long standing discussion, since all versions of Portage syncs are now PGP verified... even the "webrsync" sync method. --Maffblaster (talk) 09:21, 21 July 2023 (UTC)
keeping the system prompt consistent
This page's Entering the new environment section includes running export PS1="(chroot) $PS1" to change the prompt to remind the user that s/he's in the chroot environment. However, at the end of this page, the user is instructed to source /etc/profile, which sets PS1 back to the system default, losing the change made earlier. There ought to be a reminder after the source /etc/profile step for the user to fix PS1 again. Median (talk) 06:57, 20 September 2015 (UTC)
- I have revised that part of the handbook to re-display the indication the prompt is based in the chroot. Thanks for the tip! --Maffblaster (talk) 11:17, 28 January 2016 (UTC)
Mirrorselect for Gentoo rsync mirrors
For the section Main Gentoo repository, after having copied/created the gentoo.conf file, why not also use mirrorselect the same way as described in the Mirrorselect article:
root #mirrorselect -i -r -o >> /etc/portage/repos.conf/gentoo.confBut, how could mirrorselect be used at all before it got installed? Is it part of stage3? I can't seem to find it in stage3-amd64-20160114.tar.bz2. --Charles17 (talk) 10:51, 21 January 2016 (UTC)
- I just looked into this. Thanks of the tip. I'll add a paragraph or so explaining that mirrorselect can be installed and used to update the URL. Will return here when I have finished. --Maffblaster (talk) 07:58, 28 January 2016 (UTC)
- The point is, mirrorselect cannot be used - not even optionally - before it got installed. And it cannot be installed before the portage snapshot is in place. Hence the first thing to happen is solving bug #572848. Imho the whole "optional" mirrorselect section should be moved to Installing tools as it needs not be done before the first reboot of a new system. --Charles17 (talk) 09:22, 28 January 2016 (UTC)
- That's not true. mirrorselect can be used if the live environment as it installed, which is true for this case. I just tested the official amd64 minimal install CD and mirrorselect is available. On another note, I'm not sure I want to add a paragraph about mirrorselect for gentoo.conf because it does not intelligently search and replace the
sync-uriline in the file. Someone working through the process would still have to manually edit (with a text editor) the gentoo.conf file and then use mirrorselect on it. Leaving the default mirror rotation is probably the best option for the majority of readers. Anyone who want to adjustsync-urishould know enough to figure out any problems they may get themselves into. Also, that bug that you references doesn't relate to this conversation much. That's a separate conversation. --Maffblaster (talk) 11:08, 28 January 2016 (UTC)
- That's not true. mirrorselect can be used if the live environment as it installed, which is true for this case. I just tested the official amd64 minimal install CD and mirrorselect is available. On another note, I'm not sure I want to add a paragraph about mirrorselect for gentoo.conf because it does not intelligently search and replace the
- You are right about the amd64 minimal install CD. But please bear in mind people could use alternative installation media like another installed linux distribution. Also I agree about "Leaving the default mirror rotation ...". So the whole Main Gentoo repository section - if it needs to stay in this chapter instead of being moved to Installing tools - could be reduced to the trailing TIP referring to the Sync article. --Charles17 (talk) 12:06, 28 January 2016 (UTC)
Typo
At this point, if a new system profile as been chosen
At this point, if a new system profile has been chosen
--FabianP (talk) 11:05, 18 November 2016 (UTC)
- Fixed. Thank you!. --Maffblaster (talk) 18:12, 18 November 2016 (UTC)
Once again Mirrorselect
In section Main Gentoo repository, it says
A second important step ...
and then
... Again, this is not recommended, ...
Please bear in mind, noobs are working through the installation chapter (In this part the reader learns how to install Gentoo on a system.) to get their systems running.
These special information for special cases IMHO could better be hosted in another place (maybe Handbook:Parts/Working/Portage) as it can easily be done - if ever needed - after first reboot. --Charles17 (talk) 11:27, 23 November 2016 (UTC)
- I have removed the paragraph. It mattered only a little to me and it more of an 'advanced' concept anyway. We'll leave this open for other areas of the wiki to cover. Perhaps the Complete Handbook will catch it one day. --Maffblaster (talk) 15:58, 20 April 2017 (UTC)
- Please also remove the Gentoo ebuild repository section which only referred to the paragraph you removed.--Charles17 (talk) 10:21, 1 November 2019 (UTC)
- Sorry, but we'll leave the parts about Gentoo ebuild repository. Thank you! --Maffblaster (talk) 09:23, 21 July 2023 (UTC)
GNOME
Consider the following sentence: "[...] will require many packages to be installed since the init system is changing from OpenRC to systemd, and the Gnome desktop environment framework will be installed."
Gnome should be replaced by GNOME (all uppercase).
Fturco (talk) 09:17, 14 May 2017 (UTC)
- Implemented as suggested. --Maffblaster (talk) 18:05, 15 May 2017 (UTC)
GTK+ and Qt
Let me quote: "For instance, some programs can be compiled with gtk-support, or with qt-support."
I would replace that with: "For instance, some programs can be compiled with support for GTK+ or with support for Qt."
Fturco (talk) 09:28, 14 May 2017 (UTC)
- Implemented as suggested. --Maffblaster (talk) 18:05, 15 May 2017 (UTC)
Other minor problems
- "For instance,
sslwill compile ssl-support in the programs that support it." should become "For instance,sslwill compile support for SSL in the programs that support it." - In the sentence "
gnome gtk -kde -qt4 -qt5will compile programs with GNOME (and GTK) support, and not with KDE (and Qt) support" we should replace GTK with GTK+. - In "As an example we show a USE setting for a KDE-based system with DVD, ALSA and CD Recording support" there's no need to capitalize Recording; CD recording is better
Fturco (talk) 09:35, 14 May 2017 (UTC)
- Implemented as suggested. --Maffblaster (talk) 18:05, 15 May 2017 (UTC)
KDE-based system
Consider the following file box:
/etc/portage/make.confEnabling USE for a KDE-based system with DVD, ALSA and CD recording supportUSE="-gtk -gnome qt4 kde dvd alsa cdr"
I would add the qt5 USE flag on a KDE-based system.
- Implemented as suggested. --Maffblaster (talk) 18:05, 15 May 2017 (UTC)
US/DE locales
Consider the following FileBox:
/etc/locale.genEnabling US and DE locales with the appropriate character formatsen_US ISO-8859-1
en_US.UTF-8 UTF-8
de_DE ISO-8859-1
de_DE@euro ISO-8859-15
At minimum I would also add the de_DE.UTF-8 UTF-8 locale, but in my opinion ISO-8859 locales don't make any sense any longer since UTF-8 can be easily enabled, so I would remove them too.
Fturco (talk) 09:54, 14 May 2017 (UTC)
- Removed
de_DE@euro ISO-8859-15and addedde_DE.UTF-8 UTF-8to the FileBox as suggested for the locale generation example. Thanks, Fturco! --Maffblaster (talk) 18:09, 15 May 2017 (UTC)
- Why does it still mention the ISO-8859-* stuff? Who needs it could refer to the Setting a locale in the localization guide.--Charles17 (talk) 10:38, 1 November 2019 (UTC)
- At least, there is still this line to be removed:
[8] de_DE.iso885915
--Charles17 (talk) 15:12, 6 April 2020 (UTC)
- Removed. See Special:Diff/1252955/1252967. Thank you! --Maffblaster (talk) 09:28, 21 July 2023 (UTC)
Warn against using USE="-*"
I think we should add a warning box under the "Ignoring default USE flags" filebox like:
Setting
-* is discouraged as carefully chosen defaults may be used in some packages to prevent conflicts and other errors.Comments and improvements are welcome. --Grknight (talk) 17:38, 24 May 2017 (UTC)
- Brian Evans (Grknight) , Sounds like a good improvement to add a little warning here. I'll add it. Also, for the future, feel free to add little snippets like this. You're a developer so you have the capability. :) --Maffblaster (talk) 18:12, 26 July 2017 (UTC)
Timezone update / setting
TIMEZONE: According to the text below, emerge --config sys-libs/timezone-data will update /etc/localtime. But in case /etc/localtime already exists as a symlink, it skips and does nothing. That's confusing. So after running the commands, one should make sure that /etc/localtime is either the right symlink or properly updated.
Next, reconfigure the sys-libs/timezone-data package, which will update the /etc/localtime file for us, based on the /etc/timezone entry. The /etc/localtime file is used by the system C library to know the timezone the system is in.
root #emerge --config sys-libs/timezone-data— The preceding unsigned comment was added by Stefan00 (talk • contribs) 30 June 2017
Department of Redundancy Department
Matthew Marchese (Maffblaster) You just added the text: "If the Gentoo installation is interrupted at some point after this point, it should possible to 'resume' the installation at this point. …" That's a little redundant. How 'bout something like: "If the Gentoo installation is interrupted anywhere after this point, it should possible to 'resume' the installation at this step." - dcljr (talk) 02:31, 26 July 2017 (UTC)
- That works. Changing it. --Maffblaster (talk) 18:04, 26 July 2017 (UTC)
Choosing profiles
The profile selection should be updated to 17.0, maybe with a warning about experimental state of profile 17.1 (see Handbook_Talk:AMD64/Installation/Base#Choosing_profiles).--Charles17 (talk) 20:13, 30 December 2017 (UTC)
- Completed by Michał Górny (mgorny) in this change. I may add a little more, but this should cover marking this discussion as closed. --Maffblaster (talk) 00:46, 9 January 2018 (UTC)
GTK+ is now known as GTK
I think we should replace every instance of "GTK+" with "GTK". See this for details. Fturco (talk) 16:38, 28 October 2019 (UTC)
- This was fixed at some point, I just can't see the diff for it. --Maffblaster (talk) 17:25, 5 November 2021 (UTC)
repos.conf
The whole section Gentoo ebuild repository is not needed for getting a working Gentoo system. For the sake of simplicity it should be removed. For inteterested readers there is the dedicated repos.conf wiki article.--Charles17 (talk) 15:42, 31 October 2019 (UTC)
- It is a subsection of "Optional: Selecting mirrors". So both your statement of "not needed" and the Handbook "Optional" agree. --Grknight (talk) 16:10, 31 October 2019 (UTC)
- I just see in that older discussion it should have been removed with this commit since it only refers to rsync mirrors but not to distfiles mirros.--Charles17 (talk) 10:14, 1 November 2019 (UTC)
(non-validated) emerge-webrsync
Doing emerge-webrsync as recommended in Installing an ebuild repository snapshot from the web does not provide Repository Verification as proposed in the Validated Gentoo repository snapshots section. Could this section be removed and Optional: Updating the Gentoo ebuild repository be renamed Fetching the Gentoo ebuild repository?--Charles17 (talk) 09:30, 24 November 2019 (UTC)
- The Installing an ebuild repository snapshot from the web does indeed (finally!) verify the OpenPGP Signature Status before applying the file, so this section actually accurate at this point. I will leave it in since it doesn't hurt to have an alternative method of syncing in the case of a HTTP proxy or firewall situation. Thank you! --Maffblaster (talk) 09:51, 21 July 2023 (UTC)
Remove qt4 example
This section has qt4 in examples.
Please update to realistic values.
--Jonas Stein (talk) 00:09, 24 May 2020 (UTC)
- This was fixed by Sam James (Sam) in these changes: Special:Diff/949866/1004785. --Maffblaster (talk) 17:20, 5 November 2021 (UTC)
Removing -* reference entirely in 'Configuring the USE variable'
After another "incident" in #gentoo, I think we should consider just removing the USE="-* ..." reference in the 'Configuring the USE variable' subsection.
It's too dangerous and we can shift the explanation to the "USE flags" section in "Working with Gentoo".
--Sam (talk) 23:41, 3 November 2021 (UTC)
- I removed it all together from this section and added a note on why using
-*could be dangerous. Let me know if this does not work for you: Special:Diff/1026177/1028241. --Maffblaster (talk) 20:31, 5 November 2021 (UTC)
Give guidance on common circular dependencies (for 'Updating the @world set')
Most desktop installs will hit the freetype<->harfbuzz circular dependency. I've started gathering workarounds to such issues at User:Sam/Portage_help/Circular_dependencies.
We should at least warn above the world update part of the handbook that a circular dependency is likely and explain how to avoid it/work around it. Users are having to either google the issue right now or consult e.g. reddit/IRC/forums.
--Sam (talk) 23:47, 3 November 2021 (UTC)
- Once there is a page explaining circular dependencies, might it be an idea to have Portage point to the documentation when this issue is encountered ?
- Should the documentation suggest general methods if a specific case is not listed, such as --backtrack, USE flag wrangling, ask on IRC... ? I'd add that this is a sort of bootstrapping problem, and not a weakness on the part of Portage :).
- What is the easiest way to reproduce the issue? Just try to choose a desktop target? I plan on doing a fresh VM install this winter to address some of the longstanding discussions that I really need a fresh installation environment to test... We need more install testing! --Maffblaster (talk) 20:27, 5 November 2021 (UTC)
CPU_FLAGS_X86
Should we mention that CPU_FLAGS_X86 is used for AMD64 and that there is no CPU_FLAGS_AMD64 ? (I think that is correct.)
Currently, because it says "replace ARCH with the relevant system architecture as appropriate" it seems that it may push some people into error.
-- Ris (talk) 11:26, 18 June 2022 (UTC)
- Added an "important" attention grabbing box as you suggested, so that readers do not get confused. Thanks, P.Fox (Ris) ! See Special:Diff/1252967/1252969. --Maffblaster (talk) 09:42, 21 July 2023 (UTC)
Do "Selecting mirrors" before chrooting
The Handbook:Parts/Installation/Base#Optional:_Selecting_mirrors section should come before Handbook:Parts/Installation/Base#Mounting_the_necessary_filesystems because mirrorselect is not available in the chrooted environment.
--Vaukai (talk) 08:38, 11 January 2024 (UTC)
- I've undone this in Special:Diff/1273605 to avoid confusion. Thanks! --Sam (talk) 18:03, 11 January 2024 (UTC)
Use "--changed-use" instead of "--newuse" while updating @world
"--changed-use" is better for daily Gentoo user. "--newuse" leads to unnecessary rebuild of packages which didn't really change since last build.
Recently, the cleanup of ABI_RISCV and related use flags caused rebuild of hundreds of packages, due to the widely use of "--newuse".
Many Gentoo users don't realize the existence of "--changed-use". They just follow the Handbook and keep using "--newuse".
I heard that "--newuse" was put here to remind base system team not to forget revbmp. But since this Handbook is mostly used by new users, maybe we can add a note about the difference between "--changed-use" and "--newuse" at least. And let the user choose which one they want to use.
Imrebuild (talk) 08:54, 17 October 2020 (UTC)
- I support this. Here is an excerpt from Upgrading_Gentoo#Updating_packages for reference:
--changed-usemay be used in place of--newuse, but only if you do not build binary packages.--changed-usewill not trigger reinstallation when disabled USE flags are added or removed from a package. See the Binary package guide.- — glibg10b 19:14, 2 April 2024 (UTC)
Missing mount point and wrong path for file
At point 2.1 the path to the file (at the top of the file box) is wrong, as at that point the installing person has already used chroot. So the leading "/mnt/gentoo" for the path should be omitted.
Skorbin 08:28, 08 February 2024 (UTC)
- Proposal: Search for
{{FileBox|filename=/mnt/gentoo/etc/portage/repos.conf/gentoo.conf|lang=ini|1=and replace it with
/etc/portage/repos.conf/gentoo.conf- — glibg10b 09:34, 8 April 2024 (UTC)
- Fixed in Special:Diff/1290100/1291469, thanks!
- --Xarvatium (talk) 16:34, 8 April 2024 (UTC)
Create a Blocks page for bootloader section
Currently some alternative architectures do not support UEFI (i.e. Alpha), yet still have instructions relating to creating the /efi directory. Therefore, having a Blocks page for each architecture's specific boot config would be beneficial in preventing users from being confused about this.
Are there any drawbacks to having this? I currently do not see any but I could be missing something.
--Xarvatium (talk) 20:18, 8 April 2024 (UTC)
- These are the Parts that contain references to EFI. I didn't check Blocks. Click [Expand] on the right to view them.
Handbook:Parts/Installation/Disks:
=== Filesystems ===
...
VFAT
...
It is mostly used for interoperability/interchange with other operating systems (Microsoft Windows or Apple's macOS) but is also a necessity for some system bootloader firmware (like UEFI). Users of UEFI systems will need an EFI System Partition formatted with VFAT in order to boot.==== EFI system partition filesystem ====
== Mounting the root partition ==
...root #mkdir --parents {{Handbook Variable|root-partition-live-env-mount-point}}
For EFI installs only, the ESP should be mounted under the root partition location:root #mkdir --parents {{Handbook Variable|root-partition-live-env-mount-point}}{{Handbook Variable|esp-mount-point}}
Continue creating additional mount points necessary for any additional (custom) partition(s) created during previous steps by using the mkdir command.Handbook:Parts/Installation/Base:
==== UEFI systems ====
Handbook:Parts/Installation/Kernel:
== Kernel configuration and compilation ==
...Tip
Kernel installation tasks such as, copying the kernel image to /boot or the EFI System Partition, generating an initramfs and/or Unified Kernel Image, updating bootloader configuration, can be automated with installkernel. Users may wish to configure and install sys-kernel/installkernel before proceeding. See the Kernel installation section below for more more information.==== Optional: Signing the kernel image (Secure Boot) ====
...
On arches that do not natively support decompressing the kernel (e.g. arm64 and riscv), the kernel must be built with its own decompressor (zboot):KERNEL zboot CONFIG_EFI_ZBOOTDevice Drivers ---> Firmware Drivers ---> EFI (Extensible Firmware Interface) Support ---> [*] Enable the generic EFI decompressor
...
To automatically sign EFI executables installed by other packages, enable the secureboot USE flag globally:=== Optional: Building an Unified Kernel Image ===
Handbook:Parts/Installation/System:
=== Partition labels and UUIDs ===
...
Output for an amd64 EFI system using the Discoverable Partition Specification UUIDs may like the following:==== UEFI systems ====
- — glibg10b 21:21, 8 April 2024 (UTC)
Proposal to change "profile" to "profile version" (this confused a user)
Section: Handbook:Parts/Installation/Base#Optional: Adding a binary package host
Proposal
# The architecture and profile targets within the <code>sync-uri</code> value ''do'' matter and should align to the respective computer architecture ({{Keyword|{{Handbook Variable|architecture}}}} in this case) and system profile selected in the {{HandbookLink|Installation/Base|section=#Choosing_the_right_profile|Choosing the right profile}} section.
# The architecture and profile targets within the <code>sync-uri</code> value ''do'' matter and should align to the respective computer architecture ({{Keyword|{{Handbook Variable|architecture}}}} in this case) and system profile version selected in the {{HandbookLink|Installation/Base|section=#Choosing_the_right_profile|Choosing the right profile}} section.
Rationale
<profile> in the following FileBox in that section should be a profile version like 23.0[1].
https://distfiles.gentoo.org/releases/<arch>/binpackages/<profile>/x86-64/
"profile" is ambiguous. One user on the gentoo-user mailing list first tried their eselect profile number (27), then their profile name (23.0/desktop/plasma). "profile version" is much better. — Waldo Lemmer 15:53, 15 April 2024 (UTC)