User:Sakaki/Sakaki's EFI Install Guide/Building the Gentoo Base System Minus Kernel

In this section, we'll be following along with Chapter 6 of the Gentoo handbook, and installing the base system. However, we'll also be diverging considerably, as we will provide the option of using systemd (not Gentoo's more usual OpenRC) as the init system (since GNOME 3.8+ requires it to work properly^[1] unless patched), and bootstrapping the core system files (apart from the kernel, which will be addressed in the next section).

The process we'll be following in this section is:

Performing final preparations for a chroot (setting mirrors, copying DNS, and mounting required system directories);
Entering the chroot environment (after which, the /mnt/gentoo/ location will appear to be the true root directory of the filesystem);
Installing an up-to-date (and authenticated) Portage tree;
Ensuring that the base profile is set;
Setting your timezone and locale;
Setting your (post-boot) keymap;
(Optionally) informing Portage about your CPU's specific features;
Installing a tool to show parallel builds in progress, from the sakaki-tools overlay;
Bootstrapping the toolchain (optional);
Rebuilding everything in the @world set using the new toolchain (optional);
Verifying that all executables and libraries have been rebuilt (optional);
Configuring your system to use authenticated Portage snapshots by default;
Choosing whether to use OpenRC or systemd (some brief guidance is given to help you decide); then:
- Either, setting the final target profile (for GNOME/OpenRC);
- Or, setting the final target profile (for GNOME/systemd).

Instructions will also be provided for those who don't want to spend the time necessary to perform a full bootstrap. Let's get started!

Final Preparations for the chroot

We begin by setting up appropriate the server URIs, which portage will search when looking for source tarballs.^[2] To do this, we use the mirrorselect tool (shipped as part of the minimal install system), which allows you to choose the appropriate mirror(s) from a list, and then save the result to the make.conf file (as an assignment to the GENTOO_MIRRORS variable):

livecd ~ #

mirrorselect -i -o >> /mnt/gentoo/etc/portage/make.conf

<navigate through the list, and select all mirrors in your region>

Note
Use the cursor keys and Page Up and Page Down to navigate, and Space to toggle a mirror on and off; then Enter to save and exit when done. You do not need to select all available protocols for all servers in your region; generally, choosing the HTTP (or HTTPS, where available) protocol entry only (for each desired server) will suffice.

Make sure something appropriate was written to /mnt/gentoo/etc/portage/make.conf:

livecd ~ #

tail /mnt/gentoo/etc/portage/make.conf

Now, check that you have a sufficiently modern installation of sys-apps/portage in your new ('inner') system. Issue:

koneko ~ #

ls -d /mnt/gentoo/var/db/pkg/sys-apps/portage-*

/mnt/gentoo/var/db/pkg/sys-apps/portage-2.3.42

Your version will most likely differ from that shown above, but ensure it is no less than the version shown (2.3.42), as this is required for the modern rsync verification^[3] and failure quarantine^[4] features to be supported.

Important
If you have a lower version than 2.3.42 installed, stop now, and begin the process again (from here), using a more modern download of the Gentoo minimal install image.

Next, setup a /mnt/gentoo/etc/portage/repos.conf/gentoo.conf file (this specifies information about repositories in the system to Portage; see the earlier overview for a brief primer on the concepts involved). Issue:

livecd ~ #

mkdir -p -v /mnt/gentoo/etc/portage/repos.conf

livecd ~ #

cp -v /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf

livecd ~ #

nano -w /mnt/gentoo/etc/portage/repos.conf/gentoo.conf

and edit the file, so it reads:

FILE /mnt/gentoo/etc/portage/repos.conf/gentoo.confSetting up repository information for Portage

[DEFAULT]
main-repo = gentoo

[gentoo]
location = /var/db/repos/gentoo
sync-type = webrsync
#sync-type = rsync
sync-uri = rsync://rsync.gentoo.org/gentoo-portage
sync-webrsync-verify-signature = true
auto-sync = yes

sync-rsync-verify-jobs = 1
sync-rsync-verify-metamanifest = yes
sync-rsync-verify-max-age = 24
sync-openpgp-keyserver = hkps://keys.gentoo.org
sync-openpgp-key-path = /usr/share/openpgp-keys/gentoo-release.asc
sync-openpgp-key-refresh-retry-count = 40
sync-openpgp-key-refresh-retry-overall-timeout = 1200
sync-openpgp-key-refresh-retry-delay-exp-base = 2
sync-openpgp-key-refresh-retry-delay-max = 60
sync-openpgp-key-refresh-retry-delay-mult = 4

Any additional commented lines (e.g., regarding squashfs snapshots) present in the original file may be deleted or retained, at your option. Save and exit nano.

The above simply says that:

The main repository is set to be gentoo, for all other repositories (such as overlays) that do not specify masters;
By default,^[5] sync operations for this repo will use hardlinks^[4] to ensure that if a repo fails validation (see below) it will be safely left unchanged in its prior state (available as of Portage version 2.3.42);
The repository location is set to be /var/db/repos/gentoo (within the chroot, that is);
The repository is temporarily set to use webrsync, with signature verification (this is an efficient way to load the whole repository en bloc; but we will switch it back later to synchronize via the rsync protocol — the latter (rsync) is much more efficient for deltas, and Gentoo now provides its own signature checking for this protocol too, as discussed next);
The URI for use with the rsync protocol is set to rsync://rsync.gentoo.org/gentoo-portage — this will actually allocate a mirror dynamically, based on rotation. It is now the recommended handbook default, since using it provides a fail-safe in case a particular mirror is offline, and also allows for load-balancing across Gentoo infrastructure globally.
The repository will be synced during emerge --sync and emaint sync --auto runs;
The remaining settings in the above (from sync-rsync-verify-jobs... onward) are for use with the app-portage/gemato-based cryptographic verification scheme which Portage provides as of version 2.3.21 ^[3] (please see this news article for further details; we have here left them at their time-of-writing defaults). This technique provides assurance that the repository changes have not been corrupted or tampered with in transit.

Next up, we need to make sure our DNS information, which exists on our target machine's current host system at /etc/resolv.conf, is still available after we chroot; otherwise networking will stop working. Issue:

livecd ~ #

cp -v -L /etc/resolv.conf /mnt/gentoo/etc/

The -L option ensures we don't copy a symbolic link by mistake, since the host filesystem will become inaccessible once we chroot.

Next, if you are performing this install over a WiFi network, copy the /etc/wpa.conf configuration file for wpa_supplicant (which we setup earlier) into the chroot filesystem. Issue:

livecd ~ #

cp -v /etc/wpa.conf /mnt/gentoo/etc/

Note
If you are installing over wired Ethernet, you should skip this particular command. It isn't relevant to your ability to use WiFi in the final system, only during the install itself.

Then, we need to ensure that the kernel information in /proc, and the special files in /sys and /dev are still available from inside the chroot. We therefore mount /proc on /mnt/gentoo/proc, and then bind-mount /sys and /dev:^[6]

livecd ~ #

mount -v -t proc none /mnt/gentoo/proc

livecd ~ #

mount -v --rbind /sys /mnt/gentoo/sys

livecd ~ #

mount -v --rbind /dev /mnt/gentoo/dev

Finally, we ensure that the chroot's /sys and /dev are (recursive) slave mounts (meaning that mounts and unmounts in the 'outer' system's corresponding subtrees will propagate to them, but not vice-versa); issue:

livecd ~ #

mount -v --make-rslave /mnt/gentoo/sys

livecd ~ #

mount -v --make-rslave /mnt/gentoo/dev

Entering the chroot

We're now ready to change root (chroot), thereby entering our new system. After this is done, although we will still be running the minimal install kernel pro tem, commands issued from within the chroot-ed shell will only be able to 'see' and use files (including, but not limited to, executables, libraries, and configuration files) that lie within the stage 3 file structure we just unpacked (except for the special /proc, /sys and /dev directories, of course).

Per the handbook, we'll perform the chroot in three steps:

Enter the chroot, using bash as the shell;
Reload some settings, using source; and
Redefine the console prompt (to remind us we are in a chroot).

Issue:

livecd ~ #

chroot /mnt/gentoo /bin/bash

then:

livecd / #

source /etc/profile

livecd / #

export PS1="(chroot) $PS1"

Important
Remember that if you subsequently use the target machine directly at its keyboard (rather than through the ssh/screen combination as here), you'll be working outside of the chroot, and all your paths will be incorrect (e.g. the new system will still appear at /mnt/gentoo/). It's an easy mistake to make, hence the renaming of the prompts. Once the kernel is built and the machine rebooted, we'll be 'natively' inside the new system, at which point this path issue will disappear.

Installing an Up-to-Date Portage Tree

The next step is to install a Portage (repository tree) snapshot, a set of files (updated on a daily basis) informing Portage what software is available to install, what profiles are available, and so on.

For security, Portage snapshots are digitally signed by Gentoo Release Engineering. To securely update the necessary public keys, and then download and validate the latest snapshot, simply issue:

(chroot) livecd / #

emaint sync --auto

>>> Syncing repository 'gentoo' into '/var/db/repos/gentoo'...
 * Using keys from /usr/share/openpgp-keys/gentoo-release.asc
 * Refreshing keys from keyserver ...                                    [ ok ]
Fetching most recent snapshot ...
Trying to retrieve YYYYMMDD snapshot from <a_local_mirror> ...
Fetching file portage-YYYYMMDD.tar.xz.md5sum ...
Fetching file portage-YYYYMMDD.tar.xz.gpgsig ...
Fetching file portage-YYYYMMDD.tar.xz ...
Checking digest ...
Checking signature ...
gpg: Signature made <a_timestamp>
gpg:                using RSA key <a_key_id>
gpg: Good signature from "Gentoo ebuild repository signing key (Automated Signing Key) <infrastructure@gentoo.org>" [unknown]
gpg:                 aka "Gentoo Portage Snapshot Signing Key (Automated Signing Key)" [unknown]
gpg: WARNING: Using untrusted key!
Getting snapshot timestamp ...
Syncing local tree ...
... additional output suppressed ...
Action: sync for repo: gentoo, returned code = 0

This may take some time to complete, depending on the speed of your network connection, so please be patient. It may prompt you, once the update has been done, about news articles that are available to read. If so, just ignore these for now — we'll get to them very shortly.

Note
The warning above about the key being untrusted is normal, and may safely be ignored (you need to explicitly add (gpg) 'trust' to the keys yourself,^[7] if you want to suppress it, but rest assured that with the current setup, only valid keys can be used during the verification process).

Note
The above command will update all repositories whose auto-sync value (in /etc/portage/repos.conf/<reponame>.conf) has been set to yes — at this point in the install, that refers only to the gentoo repo.

Next, now that we have a baseline tree in place, we can switch to the more efficient rsync protocol to keep it updated going forward. Issue:

(chroot) livecd / #

nano -w /etc/portage/repos.conf/gentoo.conf

and edit the sync-type lines in that file, so they read:

FILE /mnt/gentoo/etc/portage/repos.conf/gentoo.confSwitching to rsync

#sync-type = webrsync
sync-type = rsync

Leave the rest of the file as-is. Save, and exit nano.

With that done, you can bring your Portage tree right up to date. Issue (again):

(chroot) livecd / #

emaint sync --auto

>>> Syncing repository 'gentoo' into '/var/db/repos/gentoo'...
 * Using keys from /usr/share/openpgp-keys/gentoo-release.asc
 * Refreshing keys from keyserver ...                                    [ ok ]
>>> Starting rsync with rsync://<ip_addr>/gentoo-portage...
... additional output suppressed ...
Action: sync for repo: gentoo, returned code = 0

Notice how rsync is used this time.

Note
What is happening under the covers here is interesting — the sync is actually first performed into a special /var/db/repos/gentoo/.tmp-unverified-download-quarantine subdirectory, using rsync's --link-dest option. This creates hardlinks to the original versions of unchanged files, which allows the quarantined copy to be constructed in a space-efficient manner (very similar to how the "TimeMachine" backup system works^[8]). Once complete, this quarantined copy is then checked using the app-portage/gemato signed hash verification tool and, if passed, the changes are then committed into the 'real' directory (/var/db/repos/gentoo), again using rsync, after which the quarantine directory is deleted. In the event of gemato detecting a problem, however, a non-zero (i.e., error) status will be reported, and the changes will not be committed up from the quarantine directory (which will then be preserved, for further analysis).

Now we have a known-valid current Portage ebuild repository, we can use emerge to install (or update, delete etc.) packages. But just before that, we need to ensure we also have a valid profile set.

Ensuring that the Base Profile is Set

As was mentioned earlier, Gentoo uses profiles to set important variables (such as USE, CFLAGS, etc.) relevant to your particular architecture and usage scenario (e.g., a machine running the GNOME desktop). Profiles also constrain the versions of packages that can be installed. This is all maintained on your behalf by the Gentoo developers.

At this point, we just need to check that we are running the baseline 17.1 amd64 profile (we should be): we'll change this to the 'real' profile post-bootstrap.

Note
Remember, on Gentoo, the amd64 architecture is appropriate for x86_64 processors from both AMD and Intel — the vendor-specific name is a (somewhat unfortunate) historical artefact.

Issue:

(chroot) livecd / #

eselect profile list

  [1]   default/linux/amd64/17.0 (stable)
  [2]   default/linux/amd64/17.0/selinux (stable)
... additional output suppressed ...
  [16]  default/linux/amd64/17.1 (stable) *
... additional output suppressed ...
  [21]  default/linux/amd64/17.1/desktop/gnome (stable)
  [22]  default/linux/amd64/17.1/desktop/gnome/systemd (stable)
... additional output suppressed ...
  [33]  default/linux/amd64/17.0/uclibc (exp)
  [34]  default/linux/amd64/17.0/uclibc/hardened (exp)

Note
The profile list (and numbering) shown on your machine may differ slightly from the above.

Double-check that the default/linux/amd64/17.1 entry is marked with an asterisk, indicating that it is active (the profile name is what is important, not its exact position on the list, which may be different on your system).

Important
Pay particular attention to the 'decimal-number' part of the asterisked profile in the output of the above command (the profile's version), and make sure it is 17.1. If not, particularly if reads as 13.0 or 17.0, you are most likely working from an out-of-date stage 3 tarball (perhaps one that you had lying around already, and reused to save on download time). Given that profile upgrades are non-trivial on Gentoo, in such a case I recommend you close out the chroot, backtrack to the previous chapter, download a fresh stage 3, and try again.
For avoidance of doubt, users who have been following along with these instructions step-by-step should not face this issue.

If the currently active (asterisked) profile is one of the 17.1 'family', but not default/linux/amd64/17.1 (which is very unlikely if you have been following these instructions), issue:

(chroot) livecd / #

eselect profile set "default/linux/amd64/17.1"

to correct it.

You can see the various (cumulative) variables assignments (to USE etc.) associated with a profile by looking at its make.defaults file, and those of its parents. Specifically, the eselect profile set N command creates a symbolic link at /etc/portage/make.profile. If you follow this link, and then look at the make.defaults files in that directory (and in any of the directories listed by the parent text file therein (transitively)), you will see how it works. Note that USE flags accumulate (USE being an incremental variable), but a flag prefixed by a minus sign gets removed from the list (and, as a special case, "-*" removes everything accumulated to that point).

Important
Don't be tempted to change anything inside the /etc/portage/make.profile directory; it'll be overwritten on the next Portage update.

You can also see the net effect of the profile, your make.conf, environment etc. by issuing (this is a useful sanity check):

(chroot) livecd / #

emerge --info

Lastly, if you are unsure of the meaning of any use flag, you can look it up as follows:

(chroot) livecd / #

grep -i useflag /var/db/repos/gentoo/profiles/use.desc

Note
Replace useflag in the above command with the flag you want to query, for example multilib.

Ensuring portage is Up-to-Date

Now we have a valid profile, we can ensure that Portage itself is up-to-date (again temporarily postponing reading those news articles ^-^). Issue:

(chroot) livecd / #

emerge --ask --verbose --oneshot portage

... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

The emerge command, without special options, asks Portage to (as necessary) fetch the source for, then patch, build, and install the latest version of the package specified, in this case the Portage system itself. The --oneshot option informs Portage not to add itself to the set of 'explicitly-user-requested' packages in the 'world' file (/var/lib/portage/world) (Portage is already part of the @system set, via the virtual/package-manager package, so it would be redundant to add it here). The --ask --verbose flag set makes emerge ask you before making any changes to your system, and produce verbose output (generally useful, and may be abbreviated to -av).

Now, if that emerge worked OK, (you eventually see "Jobs: n of n complete" in the output after you pressed y and Enter), congratulations: your Portage system is functional, and you should be able to proceed.

Tip
As a shortcut, you can generally just press Enter, rather than y then Enter, when confirming that you want to proceed with an emerge command.

If you were prompted about news items being available, please take the time to read them now: these are important, short announcements from developers to users, pushed out via the Portage tree. To view the current news items issue:

(chroot) livecd / #

eselect news list

You'll notice the items are numbered. To read a news item N, enter:

(chroot) livecd / #

eselect news read N

Note
Replace N in the above with the number of the news item you wish to read, such as 1, 2 etc.

You can purge (optional) all read news items with:

(chroot) livecd / #

eselect news purge

If you like, you can read more about the Gentoo news system on its manual page (using man news.eselect).

Setting Up Timezone and Locale

We don't have a timezone or locale set yet. So let's fix that now.

Note
If you elect to use systemd as your target init system (the choice comes later on this chapter), then note that some of these configuration options will need to be redone, in a systemd context, later in the tutorial. Nevertheless, we need to specify these basic elements now ahead of the bootstrap (as this will be performed in an OpenRC context).

First up is timezone. You can find the available timezone in /usr/share/zoneinfo (generally, you'll have to check the subdirectory too):

(chroot) livecd / #

ls /usr/share/zoneinfo

Choose an appropriate location, and place its relative path into /etc/timezone. For example, to set London, in the UK, you would use:

(chroot) livecd / #

echo "Europe/London" > /etc/timezone

Note
Please substitute the appropriate timezone for your own location in the above command.

Warning
Per the handbook's advice, please avoid using the /usr/share/zoneinfo/Etc/GMT* timezones, as their names do not indicate the expected offsets.

Now, we need to reconfigure the sys-libs/timezone-data package; this will pick up the value from /etc/timezone and reflect the correct value in /etc/localtime. The latter is necessary for the system C library.

(chroot) livecd / #

emerge -v --config sys-libs/timezone-data

Secondly, we must set an appropriate locale. You must specify the locales you want to use in /etc/locale.gen. Edit this file (using your favourite editor, such as nano), and uncomment those that you want. If necessary, add additional locales to the end of the list. For example, as there are no UK locales on the list (UK = United Kingdom, approximately the same ^-^ as Great Britain = GB) use we would need to add those as follows:

(chroot) livecd / #

nano -w /etc/locale.gen

Then append (for this example):

FILE /etc/locale.genAppend the following locales to the file (example only, adjust as needed)

en_GB ISO-8859-1
en_GB.UTF-8 UTF-8

Leave the rest of the file as-is. Save and exit the nano editor.

Warning
Per the handbook, it is strongly recommended that you include at least one UTF-8 locale in the list, since some applications may require it.

Note
The above is just an example. If your desired locales are already in the list (e.g., for systems in the USA, en_US ISO-8859-1 and en_US.UTF-8 UTF-8), simply uncomment them.

Note
More information about locale strings and the like can be found in the Localization Guide, please refer to that if you have any questions.

Next, we must run locale-gen to create the locales, based on the information in the /etc/locale.gen file:

(chroot) livecd / #

locale-gen

Assuming that completes successfully, you then must then specify the default locale to use. Find the system list with:

(chroot) livecd / #

eselect locale list

  [1]   C
  [2]   C.utf8
  [3]   POSIX
  [4]   en_GB
  [5]   en_GB.iso88591
  [6]   en_GB.utf8
  [ ]   (free form)

Note
Your output will probably differ from the above, depending on what entries you uncommented or added to /etc/locale.gen.

Note
You may also see some warnings output such as Cannot set LC_CTYPE to default locale; these may safely be ignored, as the next command will fix the issue.

Choose the appropriate value from the list. At this stage, you should use the 'C' (default) locale (other setups can cause issues with the indirect ssh/screen remote connection); we'll switch to your actual locale later on. Issue:

(chroot) livecd / #

eselect locale set "C"

Tip
You can also cite your desired selection by its number in the list (e.g., eselect locale set 1), which can be quicker than typing the full name sometimes. This holds for most eselect modules (see its user guide).

Now, reload your environment:

(chroot) livecd / #

env-update && source /etc/profile && export PS1="(chroot) $PS1"

Setting Up (Post-Boot) Keymap

We also need to setup a keymap, both for use post-boot, so that you will be able to type commands correctly when typing directly at your machine's keyboard.

Note
The virtual console keymap here does not replace that which we will subsequently set up for early-boot use in the initramfs (which is necessary to allow correct entry of the LUKS password); see this later comment.

We begin by displaying a list of keymaps, and filtering out those of interest. The Panasonic CF-AX3 has a Japanese layout, but obviously your machine may differ. Issue:

(chroot) livecd / #

ls /usr/share/keymaps/i386/qwerty

Note
If you use a non-qwerty layout, search inside the relevant directory instead; for example, /usr/share/keymaps/i386/azerty.

Review the list, and choose a keymap file relevant to your location. In my case for example, there is one appropriate result, jp106.map.gz. Strip off the .map.gz suffix to get the appropriate name: in my case jp106 (yours will obviously vary, depending on your actual keyboard). Now we can setup the (virtual console) keymap. Issue:

(chroot) livecd / #

nano -w /etc/conf.d/keymaps

and edit the keymap=... line, to cite the string you just found. For example, in my case:

FILE /etc/conf.d/keymapsSet the keymap as required

keymap="jp106"

Leave the rest of the file as-is (unless you know there are other changes you need to make here), and save and exit nano.

Note
Substitute for jp106 in the above with a value appropriate for your own keyboard! For example, a standard US layout would use keymap="us" here; a standard UK layout, keymap="uk".

Informing Portage of Processor-Specific Features (Optional)

In the last chapter, we left the CPU_FLAGS_X86 as the default ("mmx mmxext sse sse2") in /etc/portage/make.conf (you will recall that this variable is used to inform Portage about any processor-specific features (such as MMX, for example) available on your machine). Now, if you like, we will fill it out, using the app-portage/cpuid2cpuflags tool to help us.

Note
This is strictly optional: setting CPU_FLAGS_X86 can result in more efficient code in many cases, but, if you wish to build code for redistribution to others in binary form, you should skip this step, and leave it as-is (since, unless those users also have a machine with exactly the same processor feature set as you, your distributed binaries may crash on execution).

If you do want to set CPU_FLAGS_X86, first emerge the /proc/cpuinfo query tool (we'll use --oneshot here, to avoid adding it to your @world set):

(chroot) livecd / #

emerge --verbose --oneshot app-portage/cpuid2cpuflags

Now, run the tool and note its output (yours may well differ from the below, which is taken from the Panasonic CF-AX3):

(chroot) livecd / #

cpuid2cpuflags

CPU_FLAGS_X86: aes avx avx2 fma3 mmx mmxext popcnt sse sse2 sse3 sse4_1 sse4_2 ssse3

Issue:

(chroot) livecd / #

nano -w /etc/portage/make.conf

then copy the flags output by cpuid2cpuflags-x86 into the existing CPU_FLAGS_X86="mmx mmxext sse sse2" definition (replacing mmx mmxext sse sse2); for our example:

FILE /etc/portage/make.confModifying the CPU_FLAGS_X86 for more efficient compiled code

CPU_FLAGS_X86="aes avx avx2 fma3 mmx mmxext popcnt sse sse2 sse3 sse4_1 sse4_2 ssse3"

(Your values will most likely differ.) Leave the rest of the file as-is. Save and exit nano.

Preparing to Run Parallel emerges

We have (intentionally) set our Portage system up to maximize parallelism when emerging. However, a side-effect of this is that, because multi-job support is active, emerge does not show any console build output, just a summary progress display.

This is easily fixed, using a simple script, which will show us the latest lines from both the Portage background tarball download log (/var/log/emerge-fetch.log) and from the most recently updated build log (Portage builds its projects in /var/tmp/portage by default). I have provided this and some other necessary utilities for this tutorial in a GitHub ebuild repository (aka overlay), which makes them straightforward to install and keep up to date within Portage (for more details about ebuild repositories, see the background reading section earlier).

Note
As of version 2.2.16 of sys-apps/portage, a new plug-in sync system is available, which simplifies the use of ebuild repositories, and obviates the need for tools like layman (which was recommended in previous versions of this tutorial).

To begin with, we'll first install the git source code management software, as we'll need this to be able to synchronize the ebuild repository from GitHub. Issue:

(chroot) livecd / #

mkdir -p -v /etc/portage/package.use

(chroot) livecd / #

touch /etc/portage/package.use/zzz_via_autounmask

(chroot) livecd / #

emerge --ask --verbose dev-vcs/git

... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then Enter>
... additional output suppressed ...

Note
This may take some time to complete, as it'll bring in other packages transitively required by dev-vcs/git itself.

Note
We create the /etc/portage/package.use/zzz_via_autounmask file as a convenient receptacle for changes that you may, in future, request be automatically made to your package.use configuration to allow an emerge operation to complete successfully (it's good hygiene to have this in place before trying to install any significant packages, such as dev-vcs/git here). Per the emerge manpage (see particularly the --autounmask and --autounmask-write options), such changes are written to the "lexicographically last file" when /etc/portage/package.use is a directory (as here) — hence the "zzz_" prefix to the filename.

Next, we need to tell Portage about our ebuild repository, by adding an entry into the /etc/portage/repos.conf directory. Issue:

(chroot) livecd / #

nano -w /etc/portage/repos.conf/sakaki-tools.conf

and add the following content to that file:

FILE /etc/portage/repos.conf/sakaki-tools.confAdd the following text to specify the sakaki-tools ebuild repository

[sakaki-tools]

# Various utility ebuilds for Gentoo on EFI
# Maintainer: sakaki (sakaki@deciban.com)

location = /var/db/repos/sakaki-tools
sync-type = git
sync-uri = https://github.com/sakaki-/sakaki-tools.git
priority = 50
auto-sync = yes

Save, and exit nano.

The above simply specifies that:

The repository is called sakaki-tools;
It should be cloned to the /var/db/repos/sakaki-tools directory;
It is a git archive, which may be synchronized via the URI https://github.com/sakaki-/sakaki-tools.git;
It has 'priority' 50 (ebuilds with higher priority override those of lower priority, in the event of a name clash; the default gentoo tree has priority -1000); and
It will be automatically synced during during emerge --sync or emaint sync --auto runs.

Next, we'll pull in the ebuild repository itself. Issue:

(chroot) livecd / #

emaint sync --repo sakaki-tools

Note
After adding an ebuild repository (overlay), you may find (as in this case) you are prompted that new news items (supplied by that repository) are available. It's generally a good idea to take a look at these before proceeding; for brief instructions, please see these earlier notes.
Incidentally, for avoidance of doubt, there is no need to take action on any of the plymouth news items (2017-08-06 → 2017-08-13 inclusive) at this point, as the underlying issue has been addressed in the main Gentoo tree; nor is there any need to take action on the efivarfs item dated 2017-09-17 (that is already taken care of in this tutorial).

Whenever using a third-party ebuild repository such as this one, remember that it will (in general, due to the 'priority' setting) take precedence over your 'real' Portage tree (which it 'overlays', hence the historical name), in case of conflicting ebuilds. For this reason, it is prudent in such cases to:

mask (blacklist) all packages from the ebuild repository, then
unmask (whitelist) only those packages from the repository you explicitly know you want, then
read the contents of those remaining, unmasked repository ebuilds before emerging (installing) them.

Note
For more background details about ebuilds and other Portage internals, see this earlier primer.

We'll begin by wildcard-masking everything from sakaki-tools. As described earlier, we'll use a file in the /etc/portage/package.mask directory for this. Issue:

(chroot) livecd / #

mkdir -p -v /etc/portage/package.mask

(chroot) livecd / #

echo '*/*::sakaki-tools' >> /etc/portage/package.mask/sakaki-tools-repo

Note
This qualified atom specifies all versions of all packages in all categories, that are supplied from the sakaki-tools ebuild repository. For more details, refer to the background reading in the previous chapter.

Now we can unmask what we explicitly need (using, as described earlier, files in the /etc/portage/package.unmask directory). Issue:

(chroot) livecd / #

mkdir -p -v /etc/portage/package.unmask

(chroot) livecd / #

touch /etc/portage/package.unmask/zzz_via_autounmask

(chroot) livecd / #

echo "app-portage/showem::sakaki-tools" >> /etc/portage/package.unmask/showem

(chroot) livecd / #

echo "sys-kernel/buildkernel::sakaki-tools" >> /etc/portage/package.unmask/buildkernel

(chroot) livecd / #

echo "app-portage/genup::sakaki-tools" >> /etc/portage/package.unmask/genup

(chroot) livecd / #

echo "app-crypt/staticgpg::sakaki-tools" >> /etc/portage/package.unmask/staticgpg

(chroot) livecd / #

echo "app-crypt/efitools::sakaki-tools" >> /etc/portage/package.unmask/efitools

(chroot) livecd / #

echo "sys-kernel/genkernel-next::sakaki-tools" >> /etc/portage/package.unmask/genkernel-next

Note
When /etc/portage/<...> elements are used as subdirectories in this way, the contents are simply processed in alphabetical order - there is no 'magic' to the underlying file names used.

Note
Also, as above, we create a zzz_via_autounmask file as a convenient receptacle for changes that you may, in future, request be automatically made to your package.unmask configuration to allow an emerge operation to complete successfully.

Here is a brief summary of what the above (whitelisted) ebuilds are, and what they do:

Package	ebuild Location	Description
app-portage/showem	/var/db/repos/sakaki-tools/app-portage/showem/showem-1.0.3.ebuild	Provides a simple utility script (showem), which enables you to monitor the progress of a parallel emerge. A manpage is provided. The underlying source is available on GitHub.
sys-kernel/buildkernel	/var/db/repos/sakaki-tools/sys-kernel/buildkernel/buildkernel-1.0.37.ebuild	Provides a script (buildkernel) to build a kernel suitable for booting from a USB key in UEFI mode, together with an integral initramfs. Automatically sets the necessary kernel configuration parameters, including the command line, and signs the resulting kernel if possible. Has a interactive and non-interactive (batch) mode. (Will be used later in the tutorial.) On installation, attempts to automatically configure the /etc/buildkernel.conf settings file (to set the two variables `EFIPARTUUID` and `CRYPTPARTUUID`, which must be assigned before buildkernel is run). Manpages for the script and the configuration file are provided. The underlying source is available on GitHub.
app-portage/genup	/var/db/repos/sakaki-tools/app-portage/genup/genup-1.0.27.ebuild	Provides the genup script, to simplify the process of keeping your Gentoo system up-to-date. genup can automatically update the Portage tree (using gpg authentication, where (as here), it has been enabled), all installed packages, and kernel. Has interactive and non-interactive (batch) modes. (Will be used later in the tutorial (systemd, OpenRC).) A manpage is provided. The underlying source is available on GitHub.
app-crypt/staticgpg	/var/db/repos/sakaki-tools/app-crypt/staticgpg/staticgpg-1.4.16-r1.ebuild	The buildkernel tool (above) needs to be able to be able to place a copy of the gpg tool into the initramfs, so that the keyfile (which we created earlier) can be decrypted. Unfortunately, the version of gpg that is emerged by Portage by default is the 2.x variant. This requires a (rather convoluted) service known as pinentry to ask you for your password (even when compiled statically), and currently genkernel's initramfs builder (and init script) does not work correctly with it. Instead, genkernel expects to be using a version 1.x gpg which can query for passphrases itself, without invoking an outside agent. However, as the current app-crypt/gnupg is not SLOTted, we unfortunately can't install both a 1.x and 2.x version of gpg simultaneously into different SLOTs (as we can for say, dev-lang/python). The nuclear option is to roll our currently installed version of gpg back to 1.x of course (by placing the appropriate atom into /etc/portage/package.mask and re-emerging), but as gpg v2.x and pinentry are tightly integrated with GNOME, that's not a great idea. To work around this, I have provided the app-crypt/staticgpg ebuild in sakaki-tools. This is derived from the version 1.4.16 ebuild of app-crypt/gnupg (which does not rely on pinentry). However, this ebuild will always compile statically, has none of the standard 1.4.16 gpg's USE-flag driven options, and only installs one program, staticgpg (plus a placeholder manpage) when emerged. It can safely be installed beside a standard 2.x version of app-crypt/gnupg.
app-crypt/efitools	/var/db/repos/sakaki-tools/app-crypt/efitools/efitools-1.9.2.ebuild	This provides a lightly patched ebuild for app-crypt/efitools which fixes a small issue ^[9]; once this is addressed upstream, the main-tree version will be used in preference to this one.
sys-kernel/genkernel-next	/var/db/repos/sakaki-tools/sys-kernel/genkernel-next/genkernel-next-70.ebuild	At the time of writing, genkernel-next has been dropped from the main Gentoo tree (bug #719968), but is still required by buildkernel. As such, a version has been retained in the overlay as a workaround, until proper integration of the (less-capable) main-tree sys-kernel/genkernel has been carried out.

Note
If for some reason you don't wish to use these packages directly, then by all means review and adapt their underlying source independently. However, you won't be able to follow along directly with the text in that case: in what follows, I'll be assuming that you have chosen to install the ebuild repository.

Next, note that all user repository ebuilds (by stipulation) must specify that they are on the 'unstable' branch (since not yet fully tested). However, we are allowing (by default) only stable (amd64) packages (see above), we have to specify that for the above packages, the unstable/testing ('tilde') branch is acceptable. We use a file in the /etc/portage/package.accept_keywords directory for this, as described earlier. Issue:

(chroot) livecd / #

mkdir -p -v /etc/portage/package.accept_keywords

(chroot) livecd / #

touch /etc/portage/package.accept_keywords/zzz_via_autounmask

(chroot) livecd / #

echo "*/*::sakaki-tools ~amd64" >> /etc/portage/package.accept_keywords/sakaki-tools-repo

(chroot) livecd / #

echo -e "# all versions of efitools currently marked as ~ in Gentoo tree\napp-crypt/efitools ~amd64" >> /etc/portage/package.accept_keywords/efitools

(chroot) livecd / #

echo "~sys-apps/busybox-1.32.0 ~amd64" >> /etc/portage/package.accept_keywords/busybox

Note
For explanation of the qualified atoms used here, refer to the previous chapter.

Note
The only other keyworded packages here are a) app-crypt/efitools, which will be required to manipulate the secure boot keystores on the target machine later in the tutorial (we're not going to be installing (emerging) efitools yet, but we add the entry here so we don't have to come back to it further on); and b) sys-apps/busybox, where (at the time of writing) the 'testing' version is required for use with buildkernel.

Note
Again, as above, we create a zzz_via_autounmask file as a convenient receptacle for changes that you may, in future, request be automatically made to your package.accept_keywords configuration to allow an emerge operation to complete successfully.

Next, if you like, take a look through the ebuild files in the repository (and any patches), read the underlying sources, and satisfy yourself that everything is benign. It is good hygiene to do this, particularly prior to using a third-party ebuild repository for the first time.

Now, with that setup done, we can now install the showem tool using the standard emerge command. Issue:

(chroot) livecd / #

emerge --ask --verbose app-portage/showem

... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then Enter>
... additional output suppressed ...

And that's showem installed!

We're about to do quite a lot of building, so it'll be useful to set up a second virtual console, from which we can view the progress of emerge using our new script. Assuming you are running screen (as discussed earlier), press Ctrla then c to start a new console. Then in that new console (which is back outside the chroot, to begin with) enter:

livecd ~ #

chroot /mnt/gentoo /bin/bash

followed by

livecd / #

source /etc/profile

livecd / #

export PS1="(chroot:2) $PS1"

Now hit Ctrla then p to get back to the original console, and continue.

Bootstrapping the Base System (Optional but Recommended)

We are about to perform the bootstrap proper! In the below, we will follow the Gentoo FAQ's advice on how to recreate a 'stage 1' bootstrap in the modern age ^-^. (However, if you are content to rely on the shipped binaries, click here to skip this step.)

Note that here, bootstrapping refers to the process of:

building (from source) the standard toolchain (GCC compiler, linker, assembler, C library and a number of other items), i.e., the components necessary to build the other software and libraries that make up Gentoo's @world package set; and then
using that newly constructed toolchain to rebuild everything in the @world package set, from source.

And the point of this whole exercise? Simply put, it is to ensure the integrity of the end binaries, as far as we can. To reiterate: we will first build the core tools from source, using (by necessity) the existing toolchain binaries that are shipped as part of the minimal 'stage 3' filesystem (which we're currently chroot-ed inside of). We then use this newly built toolchain to rebuild (from source) all the shipped software in the stage 3 tarball (plus that which we've explicitly emerged, such as dev-vcs/git). Once this has been done, we verify that all libraries and binaries (apart from the kernel, which we haven't built yet) have indeed been regenerated, and that no old binaries or libraries are still lying around.

Note
The GCC compiler suite itself contains a 'bootstrap', which is triggered during this process, but it is of a slightly different nature.^[10] In the GCC bootstrap, a pre-existing (shipped system binary) compiler (S) (which in this case actually is also GCC, but need not be) is used, to build a simplified GCC compiler from source (A), which is then used to build the full GCC compiler (for C or C++) (B), and then the full compiler is built again (C) using the compiler just produced (i.e., S builds A, then A builds B, then B builds C). The binaries for the last two compilers (B and C) are then compared to ensure they are identical (modulo build timestamps and the like). Confusingly, this process is also called a '3 stage' bootstrap!

Note
There's only so much comfort you can get with recompilation, of course. Per Ken Thompson's 1983 Turing Award lecture, "Reflections on Trusting Trust", the use of any 'original' binary can potentially expose all 'downstream' code to a backdoor attack.^[11] For example, a compromised C compiler could 'infect' all subsequent compiled code - so even if the system were bootstrapped (as here), the malware would remain. Remember too, that you are still running under a kernel you didn't compile (that shipped with the minimal install image), although we'll get to building a new kernel from source shortly! Finally, even an open-source system relies on the probity of a lot of opaque firmware and microcode, not to mention the hardware itself (particularly, the IME). Nevertheless, although such attack vectors exist, they are relatively complex to exploit compared to the simplicity of producing and distributing a tainted high-level system binary (signatures notwithstanding). As such, there is still value to doing a ground-up rebuild, in my view. Should you not wish to do so, but would rather rely on the shipped stage 3 binaries, you can simply skip down to the section "Choosing between systemd or OpenRC Init". (Note though, that with Gentoo, you'll probably end up rebuilding most everything over time anyway!).

In Gentoo parlance, people speak of three 'stages' of bootstrapping (and their corresponding file system tarballs):

Stage 1: When starting from a stage 1 tarball, the base toolchain (GCC, standard C libary etc.) must be built using the existing (binary) host system toolchain, under direction of the /var/db/repos/gentoo/scripts/bootstrap.sh script. This yields a:
Stage 2 system. Here, we still need to emerge (build) the core @world package set, using our new toolchain. This yields a:
Stage 3 system, in which the toolchain has been bootstrapped, and the important system binaries and libraries have been compiled using it. A tarball of such a stage 3 system's directories is now provided as a default part of the Gentoo distribution (stage 1 and stage 2 tarballs are not available to end-users anymore).

Although we have already downloaded a stage 3 tarball, we're going to pretend we haven't, and instead build up from stage 1.

Gentoo Bootstrap Remix: Progressing from Stage 1 to Stage 2

Right, let's get going. First, we'll need to build ourselves a toolchain! We'll switch to the correct directory, and then do a dummy run to see what the supplied bootstrap.sh script wants to do:

(chroot) livecd / #

cd /var/db/repos/gentoo/scripts

then:

(chroot) livecd /var/db/repos/gentoo/scripts #

./bootstrap.sh --pretend

... additional output suppressed ...
-------------------------------------------------------------------------------
  [[ (0/3) Locating packages ]]
 * Using baselayout : >=sys-apps/baselayout-2
 * Using portage    : portage
 * Using os-headers : >=sys-kernel/linux-headers-4.19
 * Using binutils   : sys-devel/binutils
 * Using gcc        : sys-devel/gcc
 * Using gettext    : gettext
 * Using libc       : virtual/libc
 * Using texinfo    : sys-apps/texinfo
 * Using zlib       : zlib
 * Using ncurses    : ncurses
-------------------------------------------------------------------------------
... additional output suppressed ...
!!! CONFIG_PROTECT is empty
... additional output suppressed ...

The exact versions (and packages) shown in your output may differ.

Note
You can ignore any additional information/warnings about slot conflicts, packages forcing rebuilds etc. at this stage. The bootstrap is an extremely 'low level' build and will almost always go through successfully.

Note
The most direct way to make sense of the reported set of packages (and build order) output by the ./bootstrap.sh --pretend command, is to look at a minimal, ground-up Linux installation like Linux from Scratch - this has an excellent handbook, which runs though the process you'd be going through by hand, if Portage didn't exist!^[12]

The Gentoo FAQ suggests you may wish to edit the /var/db/repos/gentoo/scripts/bootstrap.sh script after reviewing it - and indeed, we will do so, because there are three 'gotchas' lurking in the above proposed emerge list. The first problem is that the C standard library that the bootstrap intends to rebuild is a virtual (virtual/libc); however, in Portage, emerging a virtual package does not, by default, cause any already-installed package that satisfies that virtual (in our case, sys-libs/glibc) to be rebuilt - which we want.

We'll edit bootstrap.sh so that it builds the underlying C library instead. Issue:

(chroot) livecd /var/db/repos/gentoo/scripts #

nano -w bootstrap.sh

Once nano opens, issue Ctrlw to start a search, and then type should never fail and press Enter. Navigate down to the line setting myLIBC and modify it so the block now reads:

FILE /var/db/repos/gentoo/scripts/bootstrap.shEnsuring glibc gets rebuilt during bootstrap

# This stuff should never fail but will if not enough is installed.
[[ -z ${myBASELAYOUT} ]] && myBASELAYOUT=">=$(portageq best_version / sys-apps/baselayout)"
[[ -z ${myPORTAGE}    ]] && myPORTAGE="portage"
[[ -z ${myBINUTILS}   ]] && myBINUTILS="binutils"   
[[ -z ${myGCC}        ]] && myGCC="gcc"
[[ -z ${myGETTEXT}    ]] && myGETTEXT="gettext"
[[ -z ${myLIBC}       ]] ; myLIBC="$(portageq expand_virtual / virtual/libc)"
[[ -z ${myTEXINFO}    ]] && myTEXINFO="sys-apps/texinfo"
[[ -z ${myZLIB}       ]] && myZLIB="zlib"
[[ -z ${myNCURSES}    ]] && myNCURSES="ncurses"

You only need modify the one line, replacing "&&" with ";" as shown above (this makes the following statement execute unconditionally). Leave the rest of the file as-is (and keep the file open in nano, for now).

The second problem is that, for modern versions of gcc, we need to allow the openmp USE flag. With the /var/db/repos/gentoo/scripts/bootstrap.sh file still open, issue Ctrlw to start a second search, and then type export USE="- and press Enter. Modify the line selected by adding openmp at the end, so it now reads:

FILE /var/db/repos/gentoo/scripts/bootstrap.shAllowing openmp USE flag during bootstrap

export USE="-* bootstrap ${ALLOWED_USE} ${BOOTSTRAP_USE} openmp"

Again, you need only modify that one line. Leave the rest of the file as is.

When done, save and exit nano.

Note
As this file exists as part of the main Gentoo ebuild repository, your changes will be overwritten next time you sync. As we only want to bootstrap our system now, that's not a problem (but you can of course make a copy of the modified bootstrap.sh file at this point, should you wish).

Ensure that will do what we intended:

(chroot) livecd /var/db/repos/gentoo/scripts #

./bootstrap.sh --pretend

... additional output suppressed ...
-------------------------------------------------------------------------------
  [[ (0/3) Locating packages ]]
 * Using baselayout : >=sys-apps/baselayout-2
 * Using portage    : portage
 * Using os-headers : >=sys-kernel/linux-headers-4.19
 * Using binutils   : sys-devel/binutils
 * Using gcc        : sys-devel/gcc
 * Using gettext    : gettext
 * Using libc       : sys-libs/glibc:2.2
 * Using texinfo    : sys-apps/texinfo
 * Using zlib       : zlib
 * Using ncurses    : ncurses
-------------------------------------------------------------------------------
... additional output suppressed ...
!!! CONFIG_PROTECT is empty
... additional output suppressed ...

Note
As before, you can ignore any additional information/warnings about slot conflicts, packages forcing rebuilds etc. at this stage. The bootstrap is an extremely 'low level' build and will almost always go through successfully.

(The exact versions in your output may differ.)

Well, we have addressed the first problem (the output is now showing sys-libs/glibc:2.2 will be built for libc, not the virtual) (and we know we have allowed openmp) - but a third remains. Specifically, the line !!! CONFIG_PROTECT is empty is telling you that the bootstrap process will not preserve any configuration files you may have modified, if any of the packages to be installed try to overwrite them. We have modified (as opposed to created from scratch) two such configuration files so far (here and here), so lets use the (supplied) qfile utility to check if either is affected (this shows us which package 'owns' a given file):

(chroot) livecd /var/db/repos/gentoo/scripts #

qfile /etc/locale.gen /etc/conf.d/keymaps

sys-apps/openrc (/etc/conf.d/keymaps)
sys-libs/glibc (/etc/locale.gen)

As the bootstrap is proposing to emerge the second of these packages, we will need to stash a temporary copy of the configuration file /etc/locale.gen, so it can be restored afterwards.

Note
In normal use, and as discussed later, Portage does not usually blindly overwrite changed configuration files in this manner, but rather warns you of the conflict, and allows you to merge any changes yourself. This issue only occurs during stage 1 bootstrapping, where CONFIG_PROTECT — a special variable containing a space-delimited list of directories where this protection applies — is (as the warning message denotes) temporarily held empty.

Issue:

(chroot) livecd /var/db/repos/gentoo/scripts #

cp -v /etc/locale.gen{,.bak}

Note
Although we did modify (rather than create from scratch) /etc/portage/make.conf earlier, this particular file is not owned by any package, as you can verify yourself using qfile, if you like.

OK, now we are good to go, so let's start the bootstrap for real:

(chroot) livecd /var/db/repos/gentoo/scripts #

./bootstrap.sh

This will take a while! You can now switch to the second screen console we prepared earlier, and see what is going on (as the files download, build etc.). Hit Ctrla then n to switch to the second console (you can do this while the bootstrap is running), and issue:

(chroot:2) livecd / #

showem

You can now switch back and forward between the two windows as you like (using Ctrla then n to cycle forwards, and Ctrla then p to cycle backwards - identical in function here where we only have two windows active), which should give you a good overview of the bootstrap process as it progresses.

Running a Stage 1 Bootstrap in One Console...

...And Watching the Logs with showem in Another

Note
The output you see will most likely be slightly different from the screenshots above, as new versions of software get released etc.

Assuming the bootstrap.sh script completes successfully, you next need to check your GCC configuration (since we just rebuilt the compiler, and possibly upgraded it too). Switch back to the first console (hit Ctrla then 0; screen indexes consoles from zero), and issue:

(chroot) livecd /var/db/repos/gentoo/scripts #

gcc-config --list-profiles

If (and only if) the output tells you your current config is invalid, per these notes, issue the following to fix it:

(chroot) livecd /var/db/repos/gentoo/scripts #

gcc-config 1

(chroot) livecd /var/db/repos/gentoo/scripts #

env-update && source /etc/profile && export PS1="(chroot) $PS1"

(chroot) livecd /var/db/repos/gentoo/scripts #

emerge --ask --verbose --oneshot sys-devel/libtool

... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then Enter>
... additional output suppressed ...

(That's a one as an argument to gcc-config by the way, not an 'ell'!)

Warning
It is very important that you ensure your GCC profile is correct. Failure to do so can break subsequent builds in a mildly spectacular fashion.

Note
If you did find it necessary to update gcc-config, you may then also, at this point, wish to switch to your second virtual console with Ctrla then n, stop any running showem with Ctrlc, then issue:

(chroot:2) livecd / #

source /etc/profile && export PS1="(chroot:2) $PS1"

finally restarting showem if desired, then switching back to the first virtual console again with Ctrla then p.
However, provided you are only going to run emerge operations from the first virtual console, using the second to run showem, sourcing /etc/profile in the second virtual console may safely be omitted, as I have done in the main body of the text.

Next, we'll run the bootstrap.sh script again, to ensure that everything in the toolchain (including early dependencies, such as sys-devel/gettext and sys-libs/zlib) have been rebuilt using the new compiler, and are then themselves used in a rebuild of that compiler:

(chroot) livecd /var/db/repos/gentoo/scripts #

./bootstrap.sh

 * System has been bootstrapped already!
 * If you re-bootstrap the system, you must complete the entire bootstrap process
 * otherwise you will have a broken system.
 * Press enter to continue or CTRL+C to abort ..
<press Enter>
... additional output suppressed ...

Now, just as above, you can switch back and forth between the two screen consoles, to review the progress.

Once the toolchain bootstrap has completed (for the second time), we're nearly ready to rebuild all the other binaries using it. Firstly however, although you shouldn't need to reset the GCC profile this time around, to be on the safe side, double-check it is valid:

(chroot) livecd /var/db/repos/gentoo/scripts #

gcc-config --list-profiles

With that done, restore the configuration file you backed-up above, and regenerate the locale information (as this will also have been purged by the bootstrap). Issue:

(chroot) livecd /var/db/repos/gentoo/scripts #

mv -v /etc/locale.gen{.bak,}

(chroot) livecd /var/db/repos/gentoo/scripts #

locale-gen

Double-check that your current locale is still set to 'C' (as was specified earlier):

(chroot) livecd /var/db/repos/gentoo/scripts #

eselect locale show

LANG variable in profile:
  C

And finally, revert back to the root directory:

(chroot) livecd /var/db/repos/gentoo/scripts #

cd /

Gentoo Bootstrap Remix: Progressing from Stage 2 to Stage 3

We now need to build everything in the @world package set, using our shiny new toolchain.

Before we start, we need to write a null 'timestamp' file, which we'll use as a marker when checking later that all our executables and libraries have indeed been rebuilt. Issue:

(chroot) livecd / #

touch /tmp/prebuild_checkpoint

Right, with that done, we are finally ready to build everything in the @world package set (including all the other packages upon which they depend to build or run), as follows:

(chroot) livecd / #

emerge --ask --verbose --emptytree --with-bdeps=y @world

... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then Enter>
... additional output suppressed ...

Note
The above process may complain about some kernel flags not being set correctly. That's because they aren't - yet! Ignore this for now, as we will build a kernel with the correct flags shortly.

Note
For avoidance of doubt, the @world set includes the @system set.

Here's what those emerge parameters mean (see also the emerge manpage):

Parameter	Short Form	Meaning
--ask	-a	Before performing the operation, show what would take place, and then ask whether to confirm or abort. It's usually a good idea to leave this set.
--verbose	-v	Provide more information about the emerge operation (e.g. USE flags that will be applied for each package, in the information provide by --ask).
--emptytree	-e	Build and install all the targets (in this case, everything in the world set), and their entire deep dependency tree, as though nothing were currently installed.
--with-bdeps=y	N/A	Include build-time dependencies that are not strictly required when calculating the deep dependency graph.
@world	N/A	Specifies what should be emerged, in this case the world set of packages (the '@' prefix indicates that a set of packages is being referred to, rather than a single package). This includes the transitive dependency closure of everything you asked be installed (listed in /var/lib/portage/world) together with the @system set.

Tip
The emerge will take quite some time; as before (when we undertook the stage 1 -> stage 2 bootstrap), you can use Ctrla then n to switch to screen's second virtual console, and review the ongoing build using showem; switch back to the original console with Ctrla then p. If you like (since the build will take several hours), you can even disconnect screen pro tem. To do this, hit Ctrla then d. You are then back in your original ssh session, and you can log out of that too if you like, using Ctrld. The target machine will continue doing its thing in the background. Then, at some later point, you can ssh back in again, and execute

livecd ~ #

screen -D -R

to reconnect to screen — your two virtual consoles will still be there. Quite neat! Of course, if you like, there is no need to do any of this, you can simply stay connected all the way through the build.

Note
By default, Gentoo will also write a high-level summary log file to /var/log/emerge.log.

Note
This command will not just rebuild existing binaries; it'll upgrade them too (if a newer version ebuild is available, since the stage 3 image was created).

Note
As this is a regular emerge, we don't need to backup /etc/locale.gen as we did earlier. Portage will handle any file conflicts for us, as we will discuss next.

After some time, the build will hopefully complete successfully (if it does not, please see the troubleshooting section, below).

Tip
If the bootstrap emerge appears to be hung, with no change in the number of jobs completed for many hours (be careful about concluding this though, check your showem output also, in the second screen console window), you can try first killing it, by pressing Ctrlc (in the first screen window, the one showing the "Jobs:..." output), and then issuing:

(chroot) livecd / #

emerge --resume

to restart it where it left off.
For avoidance of doubt, it is generally not necessary to restart the @world emerge in this manner.

Assuming you modified your /etc/locale.gen file and/or /etc/conf.d/keymaps file earlier (see here and here), then Portage will probably prompt you with:

... additional output suppressed ...
 * IMPORTANT: 2 config files in '/etc' need updating.
 * See the CONFIGURATION FILES section of the emerge
 * man page to learn how to update config files.
... additional output suppressed ...

in the output from the full emerge run.

Note
Depending upon your version of Portage, you may only be warned about changes to one file — /etc/locale.gen — and not /etc/conf.d/keymaps. This is nothing to worry about: if it happens to you, just cat the file /etc/conf.d/keymaps, to reassure yourself your changes (if any) have been preserved.

This is easily dealt with, using the dispatch-conf tool (and it's good hygiene to run this anyway, after a large build session). This utility exploits the fact that Portage does not install packages directly to the filesystem, but rather uses a sandbox approach. As a result, it will not directly overwrite files in directories protected by the CONFIG_PROTECT variable (includes most files under /etc/ in a standard setup, you can use emerge --info | grep CONFIG_PROTECT to see the full details). Instead, it writes the new configs to ._cfg0000_<name> files. dispatch-conf lets you step through each of these conflicting files in turn, shows you a diff between your current version and what the install wanted to write, and asks you what you want to do.

Enter:

(chroot) livecd / #

dispatch-conf

Then follow the prompts to review each proposed change. Assuming only the /etc/locale.gen and/or /etc/conf.d/keymaps need modifying (should be the case at this stage), then you simply need to press z for each file when prompted. This means (rather non-obviously) 'zap-new' - or in other words keep the version of the file that was there before the emerge was initiated. Once this has been done, dispatch-conf should exit automatically.

Note
If no configuration files are affected, then dispatch-conf will simply exit immediately. However, there's no harm in running it.

Tip
For each configuration file (if any) that does have pending changes, dispatch-conf will first show you a diff of the proposed new version against what is currently on disk. Somewhat confusingly, if that diff is too large to fit in one page, it will be shown to you in 'less' mode (where you can press Page Up and Page Down to navigate) — in this case, you have to press q to dismiss the diff, before dispatch-conf will prompt you whether you want to use the changes, merge them, zap them etc. However, if the diff is small enough to fit on a single page (the more usual case), you will be prompted for what to do immediately (no need to press q).

Tip
When using it day-to-day, although there's no totally foolproof way to determine what to do with config file changes displayed by dispatch-conf, the following hints may be of some assistance as a rough guide:

if only comment or version lines will be changed (you can see this from the diff output provided by dispatch-conf), it is safe to press u when prompted, to use the newer version of the config file in question;
if non-comment/version lines will be deleted or changed, but they are only to do with an upstream bug report, it is also safe to press u when prompted;
however, if non-comment/version lines will be changed, which are not to do with an upstream bug report, you will probably lose functionality if you use the new, 'factory-default' version of the file (since that will drop some of your existing config), so you should press z instead (to keep the existing version and 'zap' the changes)
if some mix of the above, you'll need to press m to merge the changes (accepting and rejecting others); for which, please see the following tip.

Tip
Although not necessary at this stage in the install, it is useful to familiarize yourself with dispatch-conf's 'merge' functionality, since often, on a package update, you will want to take the new version's documented additions to its configuration file(s), while still leaving your own customizations in place. To perform a merge, press m when prompted by dispatch-conf — you will then be shown an 'old vs new' view for each block of changes for the file in question, at which point you can either elect to keep the original (press 1 then Enter) or updated (press 2 then Enter) variants (it is useful to have your terminal set reasonably wide when doing this, so that you can view the two variants side by side, rather than wrapped). Once all blocks have been marked as either 'use old' (1 then Enter) or 'use new' (2 then Enter), you are shown the diff view again, but this time using your selected hunkset.^[13] Review this new diff (pressing Page Up, Page Down and finally q to exit, if necessary), and then, if satisfied, press u ('use new'), when prompted, to commit your (net) changes.
For avoidance of doubt, you won't need to use this functionality now, it is presented here for future reference only.

Tip
You can also consider using the etc-update tool — it performs the same function as dispatch-conf, but some may find its interface easier to work with.

Note
Once you have got the full @world emerge to work successfully, you can easily redo it again (should you wish, or your paranoia dictate) by issuing

(chroot) livecd / #

emerge --depclean && emerge --ask --verbose --emptytree --with-bdeps=y @world

once more.

If everything worked fine, then you can skip ahead to the next section; otherwise, here are a few tips on how to rectify any problems that may have occurred.

Troubleshooting a Failed Build

Generally, emerges, even of the full @world set, go without a hitch. However, if you elected earlier to use the '~amd64' (aka 'testing') phase ebuilds, issues will sometimes pop up. For example, here's a problem that happened during the writing of this guide, when attempting the stage 2 -> stage 3 emerge (I was using the testing branch then, since GNOME 3 had not been stabilized at the time - nevertheless, it's an instructive example):

media-libs/mesa Build Error during emerge

In this case, a build failure occurred while emerging the media-libs/mesa-9.2.5 package. Here are some steps you can take if this kind of thing happens to you (this is not an in-depth guide - for that see this section from the Gentoo handbook):

Sometimes, intermittent issues occur due to the very parallel build architecture we have specified. These issues will often resolve themselves if the build is recommenced. Fortunately, there's a flag for that. Issue
(chroot) livecd / #emerge --resume
and emerge will try to pick up where it left off, with all the same settings. Alternatively, you can try to resume the emerge with parallel make temporarily switched off; to do so, issue
(chroot) livecd / #MAKEOPTS="-j1" EMERGE_DEFAULT_OPTS="--jobs=1" emerge --resume
If that works OK, great, you're done. If not, proceed to the next step.
If you are building on a system with little RAM (e.g. an old computer or a virtual machine) or your build log ends with a killed compiler process, you might be running out of memory. On a VM, consider shutting it down, giving it more RAM, starting it again, and chrooting back into your installation if you still don't have a bootable system; you will be able to resume your build with emerge --resume. Alternatively, you might be running too many concurrent build jobs and / or compilations; in this case, go to /root/.bashrc and crank down the --load-average=Y and --jobs=Z parameters on your EMERGE_DEFAULT_OPTS and crank down the -j and -l options on MAKEOPTS. If your build still fails, try creating a paging file on your hard drive and enabling it to have at least some extra virtual memory as follows:
(chroot) livecd / #dd if=/dev/zero of=/pagefile bs=1M count=1024
(chroot) livecd / #mkswap /pagefile
(chroot) livecd / #swapon /pagefile
If you're still experiencing compiler processes axed by the OOM killer, you can try enabling ccache and trying the build again as many times as necessary. ccache in the context of Portage functions as a checkpointing tool, and allows you to quickly resume a failed build where it stopped before by saving a copy of each compiled file to a directory in your hard disk, and by later fetching previously compiled files from said cache instead of compilling them from scratch when you kick off the failed build again. For further info, read Gentoo Handbook: Working with Portage: Features: Caching compilation objects.
Since you are (at the moment) running on a fairly 'vanilla' system, it's likely that others will have seen the build problem you're experiencing, and have already reported it. Gentoo has a pretty quick turnaround for fixes, which are posted to the Portage (ebuild) tree when signed off. Therefore, the next-lowest-overhead way to fix a build problem is simply to a day or so (if it's a major issue, you shouldn't have to wait long), then resync Portage (using the instructions given above, to ensure authentication), and try the emerge again (NB, but not using --resume here, since we've sync'd in between):
(chroot) livecd / #emerge --ask --verbose --emptytree --with-bdeps=y @world
Hopefully, that fixed your problem. If not (or you don't want to wait), keep going...
Look at the full build log. As the build has failed, this will still be in /var/tmp/portage somewhere - indeed, in this example, the actual file is at /var/tmp/portage/media-libs/mesa-9.2.5/temp/build.log. Have a read. Having done so, try searching for any appropriate-sounding errors using Google (or, if you want to use an anyonymized wrapper around the Google search engine, Startpage). For example, here the text
Makefile:603: recipe for target 'all-recursive' failed
is quite specific and suggestive. A Google search for "Gentoo ~amd64 emerge media-libs/mesa-9.2.5 Makefile:603: recipe for target 'all-recursive' failed" yields a relevant hit: a post on the Gentoo discussion forums: "mesa-9.2.5 fails, egl_gallium/llvm related". A quick perusal shows us we have found the correct problem, and that it is related to bug #488216, a problem with the package sys-devel/llvm. In short, it appears that there is a problem with the default-use-flag build of sys-devel/llvm-3.4, it's just that it shows itself in the build of media-libs/mesa-9.2.5. You can now try to:

Work around the problem, per the information you have found. For example, in this case, you could try appending ~sys-devel/llvm-3.4 -ncurses to the /etc/portage/package.use file (see this earlier discussion of atoms and /etc/portage/package.use if you're unclear as to what this means) and issuing the full @world emerge again. Just don't forget that you have that you have made this change - and do try to come back and see if you can revert the fix later! (were a new ebuild for LLVM to be released, for example).
Try using an earlier version of the affected package (this is, in fact, the approach I adopted at the time, although it was rendered moot by the stabilization of GNOME 3). You can do this using the /etc/portage/package.mask file (discussed earlier), which tells Portage the versions of software not to allow. Here, we could try preventing Portage from using the 3.4 version of sys-devel/llvm, by adding =sys-devel/llvm-3.4 to /etc/portage/package.mask (forcing Portage to reject it), then re-emerging. In this case, from the online package information grid for LLVM, we can see this will drop us back to version 3.3-r3 (remember, I was on the testing branch). This approach generally works, but be warned - you may end up rolling back quite a lot of other packages when you mask in this way. Furthermore, if you adopt this approach, always be sure only to mask the specific version that has the problem (use '=' at the start of the /etc/portage/package.mask line, per our earlier discussion of atoms), as this means when a new (hopefully, fixed) ebuild is released (with a higher version number), Portage will automatically attempt to try to use that instead.

Note
Whatever you do, do not downgrade glibc. Forcing a downgrade will literally break your system the very second you put the older version in service. The official ebuild has actually been specially crafted to never let you downgrade glibc and exit with error status if a downgrade attempt is detected. If you can't build glibc, fix your system instead. For further info, read Downgrade Glibc from the Gentoo Wiki archive.

If you have switched your Portage profile or upgraded GCC and some toolchain-related packages like glibc refuse to build, try building gcc first, as major toolchain upgrades and some profiles like hardened require rebuilding the toolchain with different USE variables. Depending on your attention to detail, you can just issue a simple emerge -DNau --with-bdeps=y for libtool, gcc, binutils and glibc in that order and then emerge -DNau --with-bdeps=y @world, or you can outright bootstrap your system again. Refer to Hardened FAQ: How do I switch to the hardened profile for further info.

Related to the previous suggestion, especially if you're installing from an older tarball (e.g. you didn't want to wait to download ~300 MB and used instead an old stage 3 tarball you had lying around), try updating your toolchain first. An outdated toolchain can cause mysterious compilation failures, especially if a major Gentoo update has been issued since your tarball was created. You can check if your toolchain has any updates with emerge --search gcc binutils glibc libtool and looking in your output for the entries that correspond to sys-devel/gcc, sys-devel/binutils, sys-libs/glibc and sys-devel/libtool. If there are any updates to these packages, update them in the following order: first libtool, then gcc, then binutils, and finally glibc.

November 30, 2017 saw the release of a new version of the base Gentoo system profiles. This is a major upgrade, because profiles determine how your entire system is built. As a result, if you're building from an older tarball, you should follow the upgrade instructions before you do anything else or you will get mysterious build failures. Refer to the following news item for further details:New 17.0 profiles in the Gentoo repository. For avoidance of doubt, if you are working with a Jan 2018 (or later) tarball, you need take no action; the correct profile is already set.

Finally, here are some miscellaneous hints that you may find useful:

Check that your gcc configuration is set correctly, especially if you have recently upgraded your GCC installation - if it is invalid, builds will often fail in hard-to-debug ways. To do so, issue:
(chroot) livecd / #gcc-config -l
(That's an 'ell', not a 'one'!) If it returns Active gcc profile is invalid (or No gcc profile is active!), then specify an appropriate one from the list presented; for example, to select the first configuration in the list, issue:
(chroot) livecd / #gcc-config 1
(That's a 'one' this time!) If you do change your gcc profile in this way, be sure to issue:
(chroot) livecd / #env-update && source /etc/profile && export PS1="(chroot) $PS1"
(chroot) livecd / #emerge --verbose --oneshot sys-devel/libtool
to update sys-devel/libtool's library locations, and to modify the settings in your current shell, before retrying any emerge.
Check that your perl libraries are up-to-date. This will not always be handled properly by Portage, but you can use perl-cleaner to bring things back in line. Issue:
(chroot) livecd / #perl-cleaner --reallyall
If your system detects stale Perl libraries and they all fail to build, try rebuilding Perl itself:
(chroot) livecd / #emerge -a dev-lang/perl
Ensure that ruby is set to the latest version, if it is present in your system (if the following eselect ruby list command returns an error, you do not). Certain things like net-libs/webkit-gtk require an up-to-date version. Issue:
(chroot) livecd / #eselect ruby list
to see a list of available versions, and then:
(chroot) livecd / #eselect ruby set 3
to choose one.
Note
Replace the 3 in the above command with the index of the most recent ruby version, as reported in the output of eselect ruby list, above.

Then re-attempt the failed emerge.

Verifying the Bootstrap (Optional but Recommended)

Congratulations - by this point you have performed a 'stage 1' bootstrap, and so all the (binary) applications and libraries within the current chroot should have been recompiled. Just to make sure that nothing has sneaked through (i.e., an app or library somehow included in the stage 3 tarfile we downloaded earlier, but not present in the deep transitive dependency closure of the @world package set), we'll check the datestamps of all relevant components against the /tmp/prebuild_checkpoint we wrote before commencing the emerge. We aren't worried about any text executables (such as scripts) since, in principle, these can be audited to ensure they are not malicious.

First, remove any installed packages that are not part of the dependency tree, so that the following test is not confused. Issue:

(chroot) livecd / #

emerge --depclean

Let this process run through to completion (it may take a little while). Then issue:

(chroot) livecd / #

find / -type d -path /boot/efi -prune -o -path /proc -prune -o -type f -executable -not -newer /tmp/prebuild_checkpoint -print0 2>/dev/null | xargs -0 file --no-pad --separator="@@@" | grep -iv '@@@.* text'

This command finds all executable files (except beneath the EFI mountpoint at /boot/efi; which will host a FAT filesystem — in which all files appear executable — when mounted, and the special /proc pseudo-filesystem)), which aren't newer than the checkpoint file, then tests their file type using file, and prints them if they are not recognized as some form of text file (script, source code etc.). It should produce no output (as all files of this type should have been recreated, if our bootstrap was complete).

So much for executable binaries - what about libraries (shared or static)?^[14] On Gentoo, we'll have already checked most shared ('.so') libraries, since they have their execute bits set. However, this is not true for all flavours of Linux, and furthermore, static ('.a') libraries (and '.o' object files) do not have the execute bits set.^[15] Therefore, to be double-sure, we'll run another test (this may take some time to complete):

(chroot) livecd / #

find / -type d -path /boot/efi -prune -o -path /proc -prune -o -type f -not -executable -not -newer /tmp/prebuild_checkpoint -print0 2>/dev/null | xargs -0 file --no-pad --separator="@@@" | grep  '@@@.*\( ELF\| ar archive\)'

This looks for any files which aren't newer than our checkpoint file, and which are recognized by file as ELF or ar archives; it may take some time to complete (as there are a lot of files to check). Again, it should produce no output. If so, and the previous check also worked, then congratulations, you have fully rebuilt all executable binaries and libraries on your machine!

Double-Checking Portage's Authentication Settings

Earlier in this chapter — having started with a properly verified (and sufficiently modern) stage 3 filesystem — we initially populated its Gentoo tree using a (gpg-verified ) repository webrsync snapshot, then brought this fully up-to-date using (gemato-verified) rsync.

And, the way we left things, rsync remains the mechanism that will be used to keep this tree up-to-date going forward. Now, although earlier versions of this guide suggested mandating the use of verified webrsync snapshots at this point instead (by setting webrsync-gpg in FEATURES, following these instructions from the official Handbook), I now regard this step as unnecessary, because:

rsync is generally more efficient, if you update regularly (it only transfers changed files), and;
rsync verification^[3] — with failure quarantine^[4] — is now provided in Portage.

Users wishing to follow this updated recommendation, and so retain rsync, should simply click here to jump the following (optional) step.

However, if you'd rather use webrsync snapshots instead, then simply issue:

(chroot) livecd / #

nano -w etc/portage/repos.conf/gentoo.conf

and edit the sync-type lines in that file, so they read:

FILE /mnt/gentoo/etc/portage/repos.conf/gentoo.confSwitching back to using snapshots

sync-type = webrsync
#sync-type = rsync

Leave the rest of the file as-is (in particular, don't change the sync-webrsync-verify-signature or sync-openpgp-key-path lines). Save, and exit nano. You can switch between these two sync types at any time (but, to reiterate, I recommend just sticking to rsync, now Portage does proper tree verification).

Note
With a modern Portage setup, even if you do want to use snapshots, there is no need to modify FEATURES in /etc/portage/make.conf, and nor should emerge-webrsync ever be called directly — just use emerge --sync or emaint sync --auto as required, once the sync-type has been appropriately set up (as just described).

Choosing between systemd or OpenRC Init

At this point, you need to choose which init system you want to use on your target machine: OpenRC or systemd.

Gentoo's own init system (OpenRC) is now the default choice in this guide, as GNOME 3 can now be used successfully (with full session tracking and power management) under it without any patchsets applied, (given recent work^[16] on elogind in the official tree).

The alternative is, of course, systemd, which is the most widely adopted^[17] init system amongst Linux distributions.

Important
Don't stress out about making this choice! If:

you want to use Gentoo's original init system, select OpenRC; but
if you want to maximise familiarity against other mainstream distros (for example, Arch), choose systemd instead.

Ultimately, as with all things Gentoo, the choice is yours ^-^

When you have decided, continue as below:

For OpenRC, follow the "Option 1" text below, and then read the rest of this guide following the 'default' flow. Do not follow "Option 2" or read any of the 'alternative track' chapters (they are clearly marked). Be sure also to follow any specific instructions in chapters 8 and 9 that are marked for the attention of OpenRC users; or
For systemd, follow the "Option 2" text below, and then read the rest of this guide, following the 'alternative track' for Chapters 10 onwards (you will see the branch point clearly marked at the end of Chapter 9). Be sure also to follow any specific instructions in chapters 8 and 9 that are marked for the attention of systemd users.

Option 1: Setting an OpenRC Profile

Note
Remember: if you want to use systemd as your init system, please do not carry out the instructions in this section, but read "Option 2" instead.

Note
You no longer require Dantrell B.'s excellent patchset for GNOME in order to use it under OpenRC, as this option is now officially supported in the main tree.^[16] Some users may still wish to use this patchset, as it provides e.g. additional aesthetic enhancements; should you wish to do so, please refer to these notes for further details.

Accordingly, we next set our profile to the version we actually want to use going forward (we avoided doing so earlier, to minimize the scope of the bootstrap).

Issue:

(chroot) livecd / #

eselect profile list

  [1]   default/linux/amd64/17.0 (stable)
  [2]   default/linux/amd64/17.0/selinux (stable)
... additional output suppressed ...
  [16]  default/linux/amd64/17.1 (stable) *
... additional output suppressed ...
  [21]  default/linux/amd64/17.1/desktop/gnome (stable)
... additional output suppressed ...
  [33]  default/linux/amd64/17.0/uclibc (exp)
  [34]  default/linux/amd64/17.0/uclibc/hardened (exp)

The current (default) profile is shown marked with an asterisk. However, the most correct profile for our purposes is the 17.1 'desktop' variant that cites GNOME (but not systemd). In the above list, this is number 21 (but your output may differ).

Note
The output shown is just an example and will change over time. Note also that the 'dev' profiles are for Gentoo internal development; if you just want to develop regular software on your system, you don't need to select one of these.

To switch, issue:

(chroot) livecd / #

eselect profile set "default/linux/amd64/17.1/desktop/gnome"

Now, continue reading at "Updating @world to Reflect the New Profile", below (i.e., please skip the "Option 2" text below, as it does not apply).

Option 2: Setting a systemd Profile

Note
Remember: if you want to use OpenRC as your init system, please do not carry out the instructions in this section, but read "Option 1" instead.

OK, so let's set our Portage profile to the version we actually want to use going forward (we avoided doing so earlier, to minimize the scope of the bootstrap).

Issue:

(chroot) livecd / #

eselect profile list

  [1]   default/linux/amd64/17.0 (stable)
  [2]   default/linux/amd64/17.0/selinux (stable)
... additional output suppressed ...
  [16]  default/linux/amd64/17.1 (stable) *
... additional output suppressed ...
  [22]  default/linux/amd64/17.1/desktop/gnome/systemd (stable)
... additional output suppressed ...
  [33]  default/linux/amd64/17.0/uclibc (exp)
  [34]  default/linux/amd64/17.0/uclibc/hardened (exp)

The current (default) profile is shown marked with an asterisk. However, the most correct profile for our purposes is the 17.1 'desktop' variant that cites GNOME and systemd. In the above list, this is number 22 (but your output may differ).

Note
The output shown is just an example and will change over time. Note also that the 'dev' profiles are for Gentoo internal development; if you just want to develop regular software on your system, you don't need to select one of these.

To switch, issue:

(chroot) livecd / #

eselect profile set "default/linux/amd64/17.1/desktop/gnome/systemd"

Having now successfully set up the appropriate custom profile, continue reading below.

Updating @world to Reflect the New Profile

Having chosen a target init system (OpenRC or systemd), and selected the appropriate profile, we must update @world set, to pull in (and build from source) any new packages required, and to reflect any USE flag changes to existing packages (by rebuilding them as necessary).

Note
(systemd users only) It is no longer necessary to do a two-stage sys-apps/dbus/sys-apps/systemd emerge (as you will sometimes see reported); the circular dependency on sys-fs/udev-init-scripts-25 was broken by moving it to PDEPEND, as of revision 1.9 of the systemd-208-r2.ebuild.^[18]

Issue:

(chroot) livecd / #

emerge --ask --verbose --deep --with-bdeps=y --newuse --update @world

... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then Enter>
... additional output suppressed ...

Here's what those emerge parameters mean (see also the emerge manpage):

Parameter	Short Form	Meaning
--ask	-a	Before performing the operation, show what would take place, and then ask whether to confirm or abort. It's usually a good idea to leave this set.
--verbose	-v	Provide more information about the emerge operation (e.g. USE flags that will be applied for each package, in the information provide by --ask).
--deep	-D	Consider the full transitive closure of the build dependency graph, not just the immediate dependencies.
--with-bdeps=y	N/A	Include build-time dependencies that are not strictly required when calculating the deep dependency graph.
--newuse	-N	Include packages whose use flags have changed since they were last built.
--update	-u	Update packages to the best version available in the Portage ebuild tree (as of the last time you sync'd), subject to masking etc.
@world	N/A	Specifies what should be emerged, in this case the world set of packages (the '@' prefix indicates that a set of packages is being referred to, rather than a single package). This includes the (newly expanded, due to your changed profile) @system set, plus any packages you requested be installed.

Note
Do not worry if you are warned about kernel configuration options not being set correctly, we will create an appropriate kernel in the next chapter.

Note
This emerge will take some time. While it is running, as we discussed earlier in the bootstrapping section, you can switch to the second screen virtual console and review progress with showem, if you like.

Note
If your emerge exits with an error, see the section "Troubleshooting a Failed Build" above, for some hints. In particular, make sure you always try restarting the emerge at least once (with emerge --resume) if it does not complete successfully on the first attempt.

Note
Because of the profile change, the emerge command may tell you there are news items to read. Feel free to read any fresh news items now, if you like, following the earlier instructions.

Tip
If you do not want to rebuild packages whose available USE flags have been changed, but where those changes are orthogonal to your currently installed version's configuration (e.g., the addition of a non-default USE flag), then you can specify --changed-use instead of the (more conservative) --newuse in the above command.

Whether or not emerge warns you that you have configuration files that need updating as a result of the above update, it is good hygiene to run:

(chroot) livecd / #

dispatch-conf

Then follow the prompts to review each proposed change, if any.

Note
Assuming no configuration files have been modified (in a manner that cannot be mechanically reconciled) by the update (the most likely scenario), then dispatch-conf will simply exit immediately, printing nothing. However, there's no harm in running it. (OpenRC users may find they are notified that the file /etc/conf.d/keymaps needs modifying: in such a case, as before simply press z, to 'zap' (discard) the changes, and keep your original, edited version which you created earlier.)

For proposed modifications to files other than /etc/locale.gen or /etc/conf.d/keymaps — should you be presented with any by dispatch-conf — it is generally safe, at this stage in the install, to press u to use the newer version of the file (for example, systemd users may be presented with a proposed change to /etc/udev/udev.conf, and if so should follow the u route for this file).

The dispatch-conf tool is discussed in more detail in the bootstrapping section above.

Next Steps

Having successfully built the @world set for our new profile, we can now turn our attention to the heart of the system: the Linux kernel itself. Click here to go to the next chapter, "Configuring and Building the Kernel".

Notes

↑ Gentoo Wiki: "GNOME/3.8-upgrade-guide", Systemd section
↑ Gentoo Development Guide: "Mirrors"
↑ ^3.0 ^3.1 ^3.2 Gentoo News: "Portage rsync tree verification"
↑ ^4.0 ^4.1 ^4.2 Gentoo News: "Portage rsync hardlink support"
↑ author "Gentoo rsync hardlink support"
↑ SuperUser Forum: "mount dev, proc, sys in a chroot environment"
↑ Information Security Stack Exchange: "Ways to sign gpg public key so it is trusted?"
↑ Pond, James. "How Time Machine Works its Magic: Hard Links"
↑ Gentoo Forums: "I cannot compile efitools"
↑ GNU: "Installing GCC: Building"
↑ Thompson, Ken. "Reflections on Trusting Trust". 1983 Turing Award lecture
↑ Beekmans, Gerard. Linux from Scratch. Burgess, Matthew et. al. eds. 2017
↑ Stack Overflow: "Hunk #1 FAILED at 1. What's that Mean?"
↑ Ippolito, Greg. "Static, Shared Dynamic and Loadable Linux Libraries"
↑ Unix & Linux Stack Exchange Forum: "Why are .so files executable?"
↑ ^16.0 ^16.1 Gentoo News: "Gentoo GNOME 3.30 for all init systems"
↑ Wikipedia: "systemd: Adoption and reception"
↑ Portage Attic: Diff between v1.9 and v1.8 of /sys-apps/systemd/systemd-208-r2.ebuild

< Previous	Home	Next >

[gnome_systemd_runtime_dep-1] Gentoo Wiki: "GNOME/3.8-upgrade-guide", Systemd section

[2] Gentoo Development Guide: "Mirrors"

[gemato-3] 3.0 ^3.1 ^3.2 Gentoo News: "Portage rsync tree verification"

[portage_hardlink-4] 4.0 ^4.1 ^4.2 Gentoo News: "Portage rsync hardlink support"

[sync_hardlinks-5] uthor "Gentoo rsync hardlink support"

[6] SuperUser Forum: "mount dev, proc, sys in a chroot environment"

[7] Information Security Stack Exchange: "Ways to sign gpg public key so it is trusted?"

[time_machine-8] Pond, James. "How Time Machine Works its Magic: Hard Links"

[glyph-patch-9] Gentoo Forums: "I cannot compile efitools"

[10] GNU: "Installing GCC: Building"

[11] Thompson, Ken. "Reflections on Trusting Trust". 1983 Turing Award lecture

[12] Beekmans, Gerard. Linux from Scratch. Burgess, Matthew et. al. eds. 2017

[13] Stack Overflow: "Hunk #1 FAILED at 1. What's that Mean?"

[14] Ippolito, Greg. "Static, Shared Dynamic and Loadable Linux Libraries"

[15] Unix & Linux Stack Exchange Forum: "Why are .so files executable?"

[elogind_gnome-16] 16.0 ^16.1 Gentoo News: "Gentoo GNOME 3.30 for all init systems"

[17] Wikipedia: "systemd: Adoption and reception"

[18] Portage Attic: Diff between v1.9 and v1.8 of /sys-apps/systemd/systemd-208-r2.ebuild

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

[14]

[15]

[16]

[17]

[18]