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 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:
 * 1) Performing final preparations for a chroot (setting mirrors, copying DNS, and mounting required system directories);
 * 2) Entering the chroot environment (after which, the  location will appear to be the true root directory of the filesystem);
 * 3) Installing an up-to-date (and authenticated) Portage tree;
 * 4) Ensuring that the base profile is set;
 * 5) Setting your timezone and locale;
 * 6) Setting your (post-boot) keymap;
 * 7) (Optionally) informing Portage about your CPU's specific features;
 * 8) Installing a tool to show parallel builds in progress, from the  overlay;
 * 9) Bootstrapping the toolchain (optional);
 * 10) Rebuilding everything in the  set using the new toolchain (optional);
 * 11) Verifying that all executables and libraries have been rebuilt (optional);
 * 12) Configuring your system to use authenticated Portage snapshots by default;
 * 13) Choosing whether to use  or  (some brief guidance is given to help you decide); then:
 * 14) * Either, setting the final target profile (for GNOME/);
 * 15) * Or, installing the necessary patchset overlays, and then setting the appropriate target profile (for GNOME/);
 * 16) Updating the  set to reflect the new profile (whether  or ).

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
We begin by setting up appropriate the server URIs, which portage will search when looking for source tarballs. To do this, we use the 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  file (as an assignment to the  variable):

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

and edit the file (deleting any line, if present, and changing  value to ) so it reads:

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

The above simply says that:
 * The main repository is set to be, for all other repositories (such as overlays) that do not specify masters;
 * The repository location is set to be (within the, that is);
 * The repository will not be synced during and  runs;
 * The repository is set to synchronize using the protocol (this is unauthenticated, but don't worry, in this tutorial, we won't actually call for any syncs to be performed in this manner, and have specified changing the  value to  in the above, to prevent it happening inadvertently).
 * The remaining settings in the above (from onward) are for use with the -based cryptographic verification scheme that is being rolled out within Portage. They are not relevant at the moment (as this new approach is in the process of being stabilized, at the time of writing), so you do not need to concern yourself with them now, but we retain them here for use in the future.

Next, we must specify the variable, which tells Portage where to look for the  server, when bringing your Portage tree of ebuilds up to date.

Issue:

Check that something appropriate was written to and :

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

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

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

Then, we need to ensure that the kernel information in, and the special files in and  are still available from inside the. We therefore mount on, and then bind-mount  and :

Finally, we ensure that the 's and  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:

Entering the
We're now ready to change root, 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 -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, and  directories, of course).

Per the handbook, we'll perform the in three steps:
 * 1) Enter the, using bash as the shell;
 * 2) Reload some settings, using ; and
 * 3) Redefine the console prompt (to remind us we are in a ).

Issue:

then :

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. However, because (at the time of writing) is not one of the pre-installed stage 3 binaries, after downloading the latest snapshot, we will have to verify its signature outside of the chroot (where  is available), and then (once verified) install it (inside the chroot again).

Begin by fetching a signed snapshot. To do so, issue:

This command locates and downloads the latest available Portage snapshot, digest and digital signature from one of your local mirrors (which we set up earlier). Take a note of the last reported snapshot date in 's output (i.e. the one closest to the line), as it will try 'counting back' from the current date, until it finds an available tarball set. This date is shown as 'YYYYMMDD' in the above &mdash; but of course will actually be a real date, such as e.g., '20170911'.

Now, hit followed by  to start a new virtual console in. This will open outside the chroot, which is what we want.

In the new virtual console, fetch the relevant public keys, as specified on the Release Engineering page. You need at least the ID of the key described as "Gentoo Portage Snapshot Signing Key (Automated Signing Key)":

You should next verify that the key's full fingerprint matches that listed on the Release Engineering page:

If that looks good, proceed to verify the snapshot. Issue:

Assuming that worked (the output reports 'Good signature'), close out this second virtual console using, thereby returning to your original virtual console (inside the chroot again).

We can now proceed to install the verified snapshot. Issue:

The install may take some time to complete. Once done, the command may recommend some software be updated, and tell you there is news to read: if so, you can safely ignore these for now (we're about to do a ground-up rebuild anyway, and we'll get to the news items shortly).

You can now remove the cached snapshot files, if you like, to save space (this step is optional). To do so, issue:

Now we have a valid Portage ebuild repository, we can use to install (or update, delete etc.) packages. Our first task is to ensure that Portage itself is up-to-date. Issue:

The 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 option informs Portage not to add itself to the set of 'explicitly-user-requested' packages in the 'world' file  (Portage is already part of the @system set, via the  package, so it would be redundant to add it here). The flag set makes  ask you before making any changes to your system, and produce verbose output (generally useful, and may be abbreviated to ).

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

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:

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

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

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

Ensuring that the Base Profile is Set
As was mentioned earlier, Gentoo uses profiles to set important variables (such as, , 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.0 profile (we should be): we'll change this to the 'real' profile post-bootstrap.

Issue:

Double-check that the 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).

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

to correct it.

You can see the various (cumulative) variables assignments (to etc.) associated with a profile by looking at its  file, and those of its parents. Specifically, the command creates a symbolic link at. If you follow this link, and then look at the files in that directory (and in any of the directories listed by the  text file therein (transitively)), you will see how it works. Note that flags accumulate ( 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).

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

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

Setting Up Timezone and Locale
We don't have a timezone or locale set yet. So let's fix that now.

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

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

Now, we need to reconfigure the package; this will pick up the value from  and reflect the correct value in. The latter is necessary for the system C library.

Secondly, we must set an appropriate locale. You must specify the locales you want to use in. Edit this file (using your favourite editor, such as ), 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:

Then append (for this example):

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

Next, we must run to create the locales, based on the information in the  file:

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

<span id="set_C_locale">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 / remote connection); we'll switch to your actual locale later on. Issue:

Now, reload your environment:

<span id="set_post_boot_keymap">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.

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:

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

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

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

<span id="set_cpu_features">Informing Portage of Processor-Specific Features (Optional)
In the last chapter, we left the as the default  in  (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 tool to help us.

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

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

Issue:

then copy the flags output by into the existing  definition (replacing ); for our example:

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

<span id="prep_for_parallel_emerge">Preparing to Run Parallel s
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, 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 and from the most recently updated build log (Portage builds its projects in  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).

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

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

and add the following content to that file:

Save, and exit.

The above simply specifies that:
 * The repository is called ;
 * It should be cloned to the 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 tree has priority -1000); and
 * It will be automatically synced during during or  runs.

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

<span id="overlay_hygiene">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:
 * 1) mask (blacklist) all packages from the ebuild repository, then
 * 2) unmask (whitelist) only those packages from the repository you explicitly know you want, then
 * 3) read the contents of those remaining, unmasked repository ebuilds before emerging (installing) them.

We'll begin by wildcard-masking everything from. As described earlier, we'll use a file in the directory for this. Issue:

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

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

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 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 directory for this, as described earlier. Issue:

Next, if you like, take a look through the 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, <span id="install_showem">we can now install the tool using the standard  command. Issue:

And that's installed! We're about to do quite a lot of building, so it'll be useful to <span id="second_virtual_console">set up a second virtual console, from which we can view the progress of using our new script. Assuming you are running (as discussed earlier), press  then  to start a new console. Then in that new console (which is back outside the, to begin with) enter:

followed by

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

<span id="bootstrapping_base_system">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:
 * 1) 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 set (Portage) package set; and then
 * 2) using that newly constructed toolchain to rebuild everything in the World set (Portage) 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 -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 ). 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.

In Gentoo parlance, people speak of three 'stages' of bootstrapping (and their corresponding file system tarballs):
 * 1) 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  script. This yields a:
 * 2) Stage 2 system. Here, we still need to  (build) the core World set (Portage) package set, using our new toolchain. This yields a:
 * 3) 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.

<span id="bootstrap_from_1_to_2">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 script wants to do:

then:

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

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

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

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

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. When done, save and exit.

Ensure that will do what we intended:

(The exact versions in your output may differ.)

<span id="cache_modified_config">Well, we have addressed the first problem (the output is now showing will be built for, not the virtual) - but a second remains. Specifically, the line  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) Q_applets utility to check if either is affected (this shows us which package 'owns' a given file):

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

Issue:

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

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

You can now switch back and forward between the two windows as you like (using then  to cycle forwards, and  then  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.

Assuming the 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 then ;  indexes consoles from zero), and issue:

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

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

Next, we'll run the script again, to ensure that everything in the toolchain (including early dependencies, such as  and ) have been rebuilt using the new compiler, and are then themselves used in a rebuild of that compiler:

Now, just as above, you can switch back and forth between the two 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:

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:

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

And finally, revert back to the root directory:

<span id="bootstrap_from_2_to_3">Gentoo Bootstrap Remix: Progressing from Stage 2 to Stage 3
We now need to build everything in the World set (Portage) package set, using our shiny new toolchain.

Before we start, we need to <span id="create_build_timestamp">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:

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

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

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

<span id="update_config">Assuming you modified your file and/or  file earlier (see here and here), then Portage will probably prompt you with:

in the output from the full run.

This is <span id="using_dispatch_conf">easily dealt with, using the Handbook:AMD64/Portage/Tools 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 variable (includes most files under  in a standard setup, you can use  to see the full details). Instead, it writes the new configs to .cfg0000_ files. lets you step through each of these conflicting files in turn, shows you a Wikipedia:Diff between your current version and what the install wanted to write, and asks you what you want to do.

Enter:

Then follow the prompts to review each proposed change. Assuming only the and/or  need modifying (should be the case at this stage), then you simply need to press  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 was initiated. Once this has been done, should exit automatically.

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.

<span id="troubleshooting_failed_build">Troubleshooting a Failed Build
Generally, s, even of the full World set (Portage) 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 (I was using the testing branch then, since GNOME 3 had not been stabilized at the time - nevertheless, it's an instructive example):



In this case, a build failure occurred while emerging the 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 and  will try to pick up where it left off, with all the same settings. Alternatively, you can try to resume the  with parallel  temporarily switched off; to do so, issue  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 . Alternatively, you might be running too many concurrent build jobs and / or compilations; in this case, go to and crank down the  and  parameters on your  and crank down the  and  options on . 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:
 * If you're still experiencing compiler processes axed by the OOM killer, you can try enabling and trying the build again as many times as necessary.  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 again (NB, but not using  here, since we've sync'd in between):  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 somewhere - indeed, in this example, the actual file is at . 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 is quite specific and suggestive. A Google search for "" 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, a problem with the package . In short, it appears that there is a problem with the default-use-flag build of , it's just that it shows itself in the build of . You can now try to:
 * 1) Work around the problem, per the information you have found. For example, in this case, you could try appending  to the  file (see this earlier discussion of atoms and ../Installing_the_Gentoo_Stage_3_Files if you're unclear as to what this means) and issuing the full   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).
 * 2) 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  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, by adding  to  (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  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.


 * If you have switched your Portage profile or upgraded GCC and some toolchain-related packages like refuse to build, try building  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  for, ,  and  in that order and then , 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 and looking in your output for the entries that correspond to, ,  and . If there are any updates to these packages, update them in the following order: first , then , then , and finally.


 * 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:
 * 1) Check that your  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:  (That's an 'ell', not a 'one'!) If it returns  (or ), then specify an appropriate one from the list presented; for example, to select the first configuration in the list, issue:  (That's a 'one' this time!) If you do change your  profile in this way, be sure to issue:  to update 's library locations, and to modify the settings in your current shell, before retrying any emerge.
 * 2) Check that your  libraries are up-to-date. This will not always be handled properly by Portage, but you can use  to bring things back in line. Issue:  If your system detects stale Perl libraries and they all fail to build, try rebuilding Perl itself:
 * 3) Ensure that  is set to the latest version, if it is present in your system (if the following  command returns an error, you do not). Certain things like  require an up-to-date version. Issue:  to see a list of available versions, and then:  to choose one.

Then re-attempt the failed.

<span id="verifying_bootstrap">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 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 set (Portage) package set), we'll check the datestamps of all relevant components against the we wrote before commencing the. 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:

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

This command finds all executable files (except beneath the EFI mountpoint at ; which will host a FAT filesystem &mdash; in which all files appear executable &mdash; when mounted, and the special pseudo-filesystem)), which aren't newer than the checkpoint file, then tests their file type using, 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)? 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. Therefore, to be double-sure, we'll run another test (this may take some time to complete):

This looks for any files which aren't newer than our checkpoint file, and which are recognized by 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!

<span id="default_authentication">Configuring Default Use of Authenticated Portage Snapshots
Now that the bootstrapping process is out of the way, we can (shadowing these instructions from the official Handbook) set up the target system to use authenticated snapshots by default. As a convenience, we will make use of the package, which will maintain a  keyring of sanctioned Release Engineering keys automatically for us. To install it, together with the package (which supplies ), issue:

This will install its keys into the directory.

Next, edit, and enable support for validating the signed Portage tree snapshots. Issue:

and append:

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

<span id="choose_systemd_or_openrc">Choosing between systemd or OpenRC Init
At this point, you need to choose which init system you want to use on your target machine: systemd or OpenRC.

is the default choice, since a 'vanilla' (unpatched) GNOME 3.8+ system requires it to run properly. It is currently the most widely adopted init system amongst Linux distributions.

However, please be aware that there is now an alternative, for those who would rather not use. This involves installing a patchset provided by Dantrell B., which enables Gentoo users to enjoy the full GNOME experience (including session tracking and power management) under Gentoo's own init system (OpenRC).

If you choose to go the route, and so use Dantrell's patchset for GNOME (full instructions for which are provided in this guide), please be aware that, as with any third-party overlay:
 * you may find it more difficult to get support via the normal Gentoo channels (the forums etc.) when using an 'unofficial' patchset such as this one;
 * security fixes etc. may take longer to be released, and the overlays may themselves contain security holes;
 * the patchset's author (Dantrell B.) may cease support for this patchset in the future.

Having said that:
 * the vast majority of the GNOME code is unaffected by the patches;
 * the patchset code itself is largely shared with Funtoo, who use it in their mainline distribution, so you will not be alone;
 * Dantrell B. has stated his intention to support this patchset for Gentoo (at least until either a proper answer for the GNOME/systemd issue is arrived at, he ceases to use GNOME, or the complexity gets out of control).

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

When you have decided, continue as below:
 * For, 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 users; or
 * For, 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 users.

<span id="choose_systemd_profile">Option 1: Setting a systemd Profile
OK, so let's <span id="set_systemd_profile">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:

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

To switch, issue:

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).

<span id="choose_openrc_profile">Option 2: Adding Dantrell's Ebuild Repositories (Overlays) and Setting an OpenRC Profile
To use GNOME with OpenRC, you will first need to install a few custom ebuild repositories (aka 'overlays'), to apply Dantrell B.'s patchset for GNOME (see the background reading section earlier for a brief overview of ebuild repositories).

At the time of writing there are seven repos to install: a 'common' one, and one for each of GNOME 3.14, 3.16, 3.18, 3.20, 3.22 and 3.24. We'll create configuration files in for each of these.

Begin with the 'common' ebuild repository; issue:

and enter the following text:

Save, and exit.

The above simply specifies that:
 * The (common GNOME) repository is called ;
 * It should be cloned to the directory;
 * It is a Wikipedia:Git_(software) archive, which may be synchronized via the URI https://github.com/dantrell/gentoo-overlay-dantrell-gnome.git;
 * It has 'priority' 150 (ebuilds with higher priority override those of lower priority, in the event of a name clash; the default tree has priority -1000); and
 * It will be automatically synced during during or  runs.

Next, the 3.14 ebuild repository. Issue:

and enter the following text:

Save, and exit. (The contents should be self-explanatory).

We can use this file as a basis for the other (3.16 &rarr; 3.24) variants, rather than entering them manually. To do so, issue: {{RootCmd }}
 * for ((R=16;R<=24;R+=2)); do cp -v /etc/portage/repos.conf/dantrell-gnome-3-{14,${R}&#125;.conf; sed -e "s/14/${R}/g" -i /etc/portage/repos.conf/dantrell-gnome-3-${R}.conf; done
 * prompt=<span style="color:gray;">(chroot) livecd <span style="color:royalblue;">/ #

Note that it is fine to have multiple versions installed, as the profile &mdash; which we will select shortly &mdash; will decide which takes precedence.

Now, pull in the ebuild repositories themselves (in this case, via HTTPS to GitHub):

{{Note|Assuming you have set up as specified earlier, this command will not cause the main Gentoo repo to be sync'd (as it has been marked with {{c|auto-sync = no}}).}}

The Dantrell ebuild repositories (aka 'overlays') we just installed provide (inter alia) a bundled set of Portage profiles; these allow you to conveniently set flags, masks etc. and thereby ensure that subsequent installation of GNOME proceeds smoothly.

Accordingly, we next <span id="set_openrc_profile">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:

{{RootCmd [1]  default/linux/amd64/13.0 (stable) [2]  default/linux/amd64/13.0/selinux (dev) ... additional output suppressed ... [12] default/linux/amd64/17.0 (stable) * ... additional output suppressed ... [51] dantrell-gnome:default/linux/amd64/13.0/desktop/gnome+plasma (stable) [52] dantrell-gnome:default/linux/amd64/17.0/desktop/gnome+plasma (stable) [53] dantrell-gnome-3-14:default/linux/amd64/13.0/desktop/gnome/3.14 (stable) [54] dantrell-gnome-3-14:default/linux/amd64/13.0/desktop/gnome/3.14/extended (stable) [55] dantrell-gnome-3-14:default/linux/amd64/17.0/desktop/gnome/3.14 (stable) [56] dantrell-gnome-3-14:default/linux/amd64/17.0/desktop/gnome/3.14/extended (stable) [57] dantrell-gnome-3-16:default/linux/amd64/13.0/desktop/gnome/3.16 (stable) [58] dantrell-gnome-3-16:default/linux/amd64/13.0/desktop/gnome/3.16/extended (stable) [59] dantrell-gnome-3-16:default/linux/amd64/17.0/desktop/gnome/3.16 (stable) [60] dantrell-gnome-3-16:default/linux/amd64/17.0/desktop/gnome/3.16/extended (stable) [61] dantrell-gnome-3-18:default/linux/amd64/13.0/desktop/gnome/3.18 (stable) [62] dantrell-gnome-3-18:default/linux/amd64/13.0/desktop/gnome/3.18/extended (stable) [63] dantrell-gnome-3-18:default/linux/amd64/17.0/desktop/gnome/3.18 (stable) [64] dantrell-gnome-3-18:default/linux/amd64/17.0/desktop/gnome/3.18/extended (stable) [65] dantrell-gnome-3-20:default/linux/amd64/13.0/desktop/gnome/3.20 (stable) [66] dantrell-gnome-3-20:default/linux/amd64/13.0/desktop/gnome/3.20/extended (stable) [67] dantrell-gnome-3-20:default/linux/amd64/17.0/desktop/gnome/3.20 (stable) [68] dantrell-gnome-3-20:default/linux/amd64/17.0/desktop/gnome/3.20/extended (stable) [69] dantrell-gnome-3-22:default/linux/amd64/13.0/desktop/gnome/3.22 (stable) [70] dantrell-gnome-3-22:default/linux/amd64/13.0/desktop/gnome/3.22/extended (stable) [71] dantrell-gnome-3-22:default/linux/amd64/17.0/desktop/gnome/3.22 (stable) [72] dantrell-gnome-3-22:default/linux/amd64/17.0/desktop/gnome/3.22/extended (stable) [73] dantrell-gnome-3-24:default/linux/amd64/13.0/desktop/gnome/3.24 (stable) [74] dantrell-gnome-3-24:default/linux/amd64/13.0/desktop/gnome/3.24/extended (stable) [75] dantrell-gnome-3-24:default/linux/amd64/17.0/desktop/gnome/3.24 (stable) [76] dantrell-gnome-3-24:default/linux/amd64/17.0/desktop/gnome/3.24/extended (stable) }} (Your output may vary.)
 * eselect profile list
 * prompt=<span style="color:gray;">(chroot) livecd <span style{{=}}"color:royalblue;">/ #
 * output=

The current (default) profile is shown marked with an asterisk. However, the safest profile for our purposes is the 'extended' variant whose version matches the current 'stable' version of GNOME in mainline Gentoo. To find out what version this is (version 3.22, at the time of writing), consult the table in, and look for the green box with a plus sign in it, under the heading (there may be more than one, in which case it is generally best to select the most modern 'plus signed' variant listed).

Having found the stable version of GNOME, select the appropriate profile; for example, to use GNOME 3.22 (matching one of the 'stable' Gentoo versions at the time of writing; adapt as appropriate), issue: {{RootCmd }}
 * eselect profile set "dantrell-gnome-3-22:default/linux/amd64/17.0/desktop/gnome/3.22/extended"
 * prompt=<span style{{=}}"color:gray;">(chroot) livecd <span style{{=}}"color:royalblue;">/ #

Check that the new profile is now active: {{RootCmd Current /etc/portage/make.profile symlink: dantrell-gnome-3-22:default/linux/amd64/17.0/desktop/gnome/3.22/extended }} The output you see may differ from the above, but should reflect the profile choice you just made.
 * eselect profile show
 * prompt=<span style{{=}}"color:gray;">(chroot) livecd <span style{{=}}"color:royalblue;">/ #
 * output=

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

<span id="update_world">Updating @world to Reflect the New Profile
Having chosen a target init system ( or ), and selected the appropriate profile, we must update 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).

Issue:

Here's <span id="world_update_params">what those parameters mean (see also the emerge manpage):

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

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

<span id="next_steps">Next Steps
Having successfully built the 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".