Sakaki's EFI Install Guide/Setting up the GNOME 3 Desktop

From Gentoo Wiki
Jump to: navigation, search

In this section, we'll be setting up GNOME 3 on your machine.

GNOME 3 is a feature-rich desktop environment provided by the Gnome Project. It is one of the most widely-used Linux desktops. Version 3 has now been stabilized on Gentoo, and the older version 2 is no longer supported (reflecting an upstream decision).

GNOME's user interface is known as the "GNOME Shell". It provides core user functions,[1] such as:

  • launching applications,
  • switching windows and desktops,
  • searching for programs and files,
  • notification management, etc.

and uses accelerated, modern-looking graphics:

GNOME Shell v3.24 in Overview Mode

For more information about GNOME, see its official site and Wikipedia page. A list of GNOME releases may be found here.

As of the time of writing, the X Window System ("X11") is still the most usual platform on which to deploy the GNOME 3 environment (although it is slowly being transitioned to use the more lightweight Wayland compositor).

Accordingly, the process we'll be following in this section is:

  1. Adding a regular (non-root) user;
  2. Installing X11;
  3. Temporarily installing a simple X11 window manager, and a few applications, for test purposes;
  4. Reconfiguring the kernel if necessary (to include missing graphic drivers etc.) and recompiling using buildkernel;
  5. Installing GNOME 3 and key applications; then
  6. Testing GNOME 3, and refining settings.

This section has no direct equivalent in the Gentoo Handbook (although the part about adding a user reflects the "User Administration" section from Chapter 11, and the X11 troubleshooting section has elements of the "Default: Manual (Kernel) Configuration" section from Chapter 7).

You may find the articles "GNOME Configuration HOWTO" and "systemd/Installing Gnome3 from scratch" (both from the Gentoo wiki) useful background reading.
The transition from GNOME 2 to 3 has caused some controversy in the Linux community, as it involves a significant shift away from the more 'traditional' desktop metaphor (see this Wikipedia article for example). And forces you to use systemd (unless of course you avail yourself of Dantrell B.'s overlays)...

If the newer look is not for you, don't despair. Although GNOME 2 is no longer supported in Gentoo, other similar desktops are; for example:

However, installing these is beyond the scope of this guide. In what follows, I'm going to assume you want to use the GNOME 3 desktop.

Right, let's get started!

Adding a User for Daily Use

Per the Gentoo Handbook, it is strongly recommended to set up a user for day-to-day use on your machine. Let's do that now. Issue (via the ssh connection from the helper PC):

koneko ~ #useradd --create-home --groups users,wheel,portage,lpadmin,lp --shell /bin/bash --comment "sakaki" sakaki
koneko ~ #passwd sakaki
New password: <enter your new password>
Retype new password: <enter your new password again>
passwd: password updated successfully
Obviously, substitute your real name (for "sakaki") and desired username (for sakaki) in the above commands. You can also define multiple users at this point if you like.
Be sure to write this password down somewhere safe! You will require it to log in later.
Feel free to add or remove groups as required in the useradd command - the above set is a reasonable starting point for a 'power user' under systemd in Gentoo. See the description below for further information.

The meaning of those useradd options is as follows:

Parameter Short Form Meaning
--create-home -m Create the user's home directory if it does not already exist.
--groups -G Specify a set of supplementary groups for the user. By default on Gentoo, when a user is created, a new group of the same name will also be created, and become that user's primary group. The additional groups specified here have the following function:[2][3][4]
Group Description
users This is the standard group for users.
wheel Members of this group can use su to masquerade as other users (including the root user), provided they know the appropriate password.
portage Members of this group can perform emerge --pretend operations, and access portage log files.
lpadmin Members of this group can administer printers attached to the system.
lp Members of this group can use printers attached to the system (important for Bluetooth printers too).[5]
--shell -s Specify the user's login shell. We've used bash here, as it is the default shell in Gentoo Linux.
--comment -c A short description of the login; most commonly the user's full name (such as "John Doe").
With the move to systemd, many of the old hardware-access groups (such as disk, network, audio, lp etc.) are no longer necessary, and may even cause problems if you add yourself to them. Other 'traditional' groups such as adm have no effect on modern systems.[6]
There are a number of other software groups that you may wish to add your user(s) to over time, as and when you emerge the specific packages. For example, if you use VirtualBox, you'd need to add your user to the vboxusers group; if running this install as a VirtualBox guest, you'd need to add your user to the vboxguest group. This wiki entry has a useful list of this type of group (and instructions for how to add and remove users from a group).

Installing X11

As we'll be using X11[7] as the underlying graphical platform for GNOME, we'll install it next.

We need to set a few USE flags for media-libs/mesa (an OpenGL-like library which X pulls in as a dependency), and while we're at it, set a few others that we'll need shortly for GNOME, so issue:

koneko ~ #echo -e "# required by standard X-server installation\n>=media-libs/mesa-9.1.6 xa gbm" >> /etc/portage/package.use/mesa
koneko ~ #echo -e "# required by GNOME\n>=media-libs/mesa-9.1.6 gles2" >> /etc/portage/package.use/mesa
koneko ~ #echo -e "# required by GNOME\n>=media-libs/cogl-1.18.2 gles2" >> /etc/portage/package.use/cogl
koneko ~ #echo -e "# required by GNOME\n>=media-libs/clutter-1.20.0 egl" >> /etc/portage/package.use/clutter
koneko ~ #echo -e "# required by GNOME 3.16+\n>=gnome-base/gnome-control-center-3.16.3 networkmanager" >> /etc/portage/package.use/gnome-control-center

Here are what those flags do (you may also find this Linux from Scratch page useful):

Package Use flag Description
media-libs/mesa xa This enables the XA (X Acceleration) API for Gallium3D (a device driver framework for 3D graphics chipsets).
gbm This enables support for the Graphics Buffer Manager for EGL on kernel mode setting.
gles2 This enables OpenGL for Embedded Systems (version 2) support.
media-libs/cogl gles2 Ditto.
media-libs/clutter egl Enables the EGL backend.
gnome-base/gnome-control-center networkmanager Enables support for NetworkManager.

As before, since some of the next steps will involve lengthy emerges, we'll use screen, and setup a second virtual console, which will be let us monitor progress using showem. Issue:

koneko ~ #screen
koneko ~ #export PS1="(1) $PS1"

to start screen. Then, press Ctrla then c to start a new virtual console, and in that new console enter:

koneko ~ #export PS1="(2) $PS1"

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

Now, since you have already set up the necessary VIDEO_CARDS and INPUT_DEVICES variables in /etc/portage/make.conf earlier, we can now proceed to install the X-server itself. Issue:

(1) koneko ~ #emerge --ask --verbose --oneshot x11-base/xorg-server
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

and the X11 server will be downloaded and installed. Note that we use --oneshot here to avoid adding it to your @world set (this is slightly cleaner, as it will become a dependency of GNOME, once it is installed later).

Just as before, you can temporarily switch to the second console to watch the progress with showem, if you like. Use Ctrla then n to switch to the second console, and Ctrla then p to return back when done.
If you are installing onto a VirtualBox client (and this won't apply to most readers, who will instead be installing onto a 'real' target PC), please note the following:
  • You cannot simply set VIDEO_CARDS="vesa" when using VirtualBox with EFI emulation turned on.[8] You need to use VIDEO_CARDS="virtualbox" instead.
  • Under EFI boot, you may find it more reliable to use ALSA Audio Driver / Intel HD Audio on your virtual machine (selectable in the VirtualBox control panel, under "Audio").
  • It is generally useful to emerge the app-emulation/virtualbox-guest-additions in your guest (and set it to start on boot), to enable enhanced services (this does not entail installing any binary blobs). Also, if you do use this package, also remember to add your user(s) to the vboxguest group.
  • The VirtualBox video drivers are notoriously awkward to emerge with parallelism and it is possible they will break your x11-base/xorg-server build. If this occurs, just retry as follows (note the explicit citation of x11-base/xorg-drivers, to ensure that these are correctly built):
(1) koneko ~ #MAKEOPTS="" emerge --verbose --oneshot x11-base/xorg-drivers x11-base/xorg-server

Temporarily Installing an X11 Window Manager and Applications

To be able to test out X11, we'll need to install a window manager, and a few X11 applications.

To keep things simple here, we'll use the (minimalist) Tab Window Manager (TWM) (x11-wm/twm), and the following apps:


(1) koneko ~ #emerge --ask --verbose x11-wm/twm x11-terms/xterm x11-apps/xclock x11-apps/xsetroot
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

These are small programs, and shouldn't take long to download, compile or install.

Next, reload your environment to avoid issues when starting the X server. Issue:

(1) koneko ~ #env-update && source /etc/profile && export PS1="(1) $PS1"

Press Ctrla then n to switch to the second virtual console, and do the same there:

(2) koneko ~ #source /etc/profile && export PS1="(2) $PS1"

Then press Ctrla then p to revert to the first virtual console again.

Next, we need to tell X11 what window manager and apps to use whenever it starts up. The .xinitrc file is used for this purpose. Also, as it's generally not a great idea to run an X server as root, we'll invoke it as the regular user we've just created. Still via ssh/screen console, issue:

(1) koneko ~ #su --login sakaki
Substitute the user name of the regular user you created in the earlier step for sakaki in the above command.
The su command, when invoked with --login (as here) provides a console environment similar to that which the specified user would have if s/he had logged in directly. When issued by the superuser (root), as here, no password is required.

Next, edit the .xinitrc file in the regular user's home directory. Issue:

sakaki@koneko ~ $nano -w ~/.xinitrc
Obviously, the name that you see in the prompt will reflect that of the regular user you added (and which you just su-d to).

Put the following text in the .xinitrc:

FILE ~/.xinitrcA basic setup to start TWM and some simple applications
twm &
xsetroot -solid CornflowerBlue &
xclock -geometry 100x100-1+1 &
xterm -geometry 80x50+494+51 &
xterm -geometry 80x20+494-0 &
exec xterm -geometry 80x66+0+0 -name login

Save and exit nano.

The above shell script simply instructs X to:

  • start the Tab Window Manager (twm) as a background process;
  • set the background colour to "CornflowerBlue" (also backgrounded, but will exit quickly);
  • show an analogue clock, of size 100x100 pixels, offset 1 pixel from the right side of the screen and 1 pixel from the top (as a background process);
  • show a terminal, of size 80x50 characters, offset 494 pixels from the left side of the screen and 51 pixels from the top (as a background process);
  • show a second terminal, of size 80x20 characters, offset 494 pixels from the left side of the screen and 0 pixels from the bottom; and
  • then execute a third terminal, of size 80x66 characters, offset 0 pixels from the left, top corner of the screen (replacing the calling process). This terminal has name 'login' and, when terminated, the X session will close.

Now we are ready to try it out!

The next command may very well fail, if the necessary graphics kernel drivers for your particular target PC haven't yet been built. This is in fact quite likely (given the small footprint of the minimal install image kernel, on which our current kernel has been based), but don't worry; full instructions to fix the issue (should it arise) are also provided.

Still on the ssh/screen console, issue:

sakaki@koneko ~ $startx

If all goes well, the screen of your target PC should now be displaying something like the below:

Simple X11/TWM Desktop and Applications

(If you get an error instead, see the following section "Troubleshooting a Failed X11 Startup". Any problems are most likely due to a missing kernel graphics driver, which is easy to fix, so don't panic!)

Check that you can move the cursor around (using the target machine's mouse or touchpad), and try typing some simple commands (e.g. "ls /bin") into any of the three terminal windows. When done, move your cursor into the longest (leftmost) terminal, so that it receives the focus (its cursor will switch to a filled rectangle), and type (directly at the target machine's keyboard):

sakaki@koneko ~ $exit

On the ssh/screen console (at your helper PC), you should now see that the startx program has exited (and a lot of status output will have been written to the console too).

If you have problems, the X server can always be closed from the ssh window, by typing Ctrlc.

If you were able to carry out this test, then congratulations, GNOME 3 should be able to work fine on your system. Jump over the troubleshooting section and install it.

If, however, X failed to start up properly, continue reading.

Troubleshooting a Failed X11 Startup

This troubleshooting section is necessary only if you had problems starting X11. To reiterate: if the above X11 test worked for you, then you should just skip to the next section now.

By far the most likely problem you will encounter with X is a missing graphics driver. Actually, if you've been following this tutorial, and have a reasonably modern machine, then it'll likely have happened to you. That's because the Gentoo minimal install image kernel (on which your current kernel's configuration has been based) does not have many graphics device drivers configured (either built into the kernel, or as modules) - in order to keep the size of the image small.

Two drivers that are conspicuous by their absence from the minimal install kernel configuration are:

  • the DRM_I915 driver; this is needed for the integrated "HD Graphics" on many Ultrabooks (such as the Panasonic CF-AX3);
  • the DRM_NOUVEAU driver; this is an open-source driver that supports many nVidea graphics cards (which are popular on desktop machines).

The easiest way to see if you have had a problem like this is to look at the output from your attempt to run startx (the output in the ssh/screen virtual terminal, that is, not on your target machine's display).

If you see output such as:

... additional output suppressed ...
modprobe: FATAL: Module i915 not found.
... additional output suppressed ...

then you know that you have a driver problem. In this case, it is complaining about the i915 driver module (dynamic library).

If you see more cryptic output, such as:
... additional output suppressed ...
Fatal server error:
(EE) no screens found(EE) 
... additional output suppressed ...
then it is still probably a driver problem at this stage; look in the log file /var/log/Xorg.0.log for more detailed output.

To rectify this, we need to turn on the appropriate drivers and rebuild our kernel. Ensure that the USB boot key is inserted into the target machine, and issue (from the ssh/screen virtual terminal):

sakaki@koneko ~ $exit

to drop back to the root user.

You may also find the content of the /var/log/Xorg.0.log log file useful. Additionally, entering (as root):
(1) koneko ~ #lspci | grep -i VGA


(1) koneko ~ #hwinfo --gfxcard
can provide more information about your graphics card. Unfortunately, as of the time of writing, there is no reliable program which will query your hardware and generate an appropriate kernel configuration automatically.

Ensure that the boot USB key is still inserted, and then issue:

(1) koneko ~ #buildkernel --menuconfig

to start the kernel rebuild process going. Because you have not specified --ask here, but you have specified --menuconfig, the process will run through by itself (assuming no errors) to the point where you can modify the kernel configuration using the standard curses-based editor GUI.

The configuration changes you need to make will vary depending on the driver(s) you need to enable. The following is a step-by-step guide for modern laptops (and other PCs) with Intel integrated HD graphics (following this wiki page). If you require a different driver, modify these instructions accordingly.

The menuconfig system is a simple tool used to modify Linux kernel configurations (aka ".config" files) in a coherent manner. The tool will not let you make inconsistent choices, and has a useful search facility.

For more information on menuconfig, refer to Chapter 4 of Greg Kroah-Hartman's Linux Kernel in a Nutshell[9], the Gentoo wiki page, and Bruce Dubbs' "Considerations when configuring the Linux kernel" from Linux from Scratch[10].

When menuconfig starts up, it will present you with a display similar to the below (your version may vary depending on currently selected options and kernel version):

Initial Display of make menuconfig Application

You can navigate the interface as follows:

  • Use the up and down arrow keys to move your selection (highlighted in blue) in the top pane;
  • Use the left and right arrow keys to traverse the bottom (horizontal) menu, which defines what happens when you press Enter, viz.:
    • <Select> enters a sub-menu, for items (in the top pane) ending with --->, or brings up a text entry box for items which start with round brackets "()";
    • <Exit> exits a sub-menu; if at the top level already, asks you whether to save changes (if you have made any) and exits the program; you can also press Esc then Esc to perform this action;
    • <Help> shows a help screen that is relevant to the (top pane) selection; you can also press h for this;
    • <Save> saves the current configuration; and
    • <Load> allows you to load a new configuration.

Items starting with non-round brackets represent features which can be enabled, as follows:

[ ], [*] 
Square brackets indicate features that are deactivated (blank) or activated (asterisk). Press Space to toggle status, or y to activate, n to deactivate. Activated items are built directly into the kernel; deactivated items are omitted from it entirely.
< >, <M>, <*> 
Angle bracketed items can similarly be deactivated (blank) or activated (asterisk), but can additionally be built as modules ("M"). In addition to Space, y and n, you can use m with such items to specify that they should be modularized.
{M}, {*
Curly brackets indicate items which cannot be deactivated (due to another item's dependency). However, they may be activated or modularized (using y, m or Space, as before).
-M-, -*- 
Similarly, hyphens indicate items whose status cannot be changed (their selection having been forced as the result of another item choice).
At times, you may find that certain choices are impossible, despite the bracket coding, because of other choices you have made. For example, you may not be able to activate an element, only modularize it, if one of its dependencies is modularized (rather than selected). In such cases, menuconfig will tell you that your choice is restricted, and why.

To search, press / and then type your search term. This is a very useful facility when looking for missing drivers etc. For example, since we are here looking for the missing i915 module, press / then type in i915, then press Enter to see the search results:

Searching for a Missing Driver...
...And Reviewing the Results
As mentioned, the following assumes you are adding the necessary Intel DRM_I915 driver. If your setup requires a different driver, for example DRM_NOUVEAU (for nVidia cards), you will need to modify these instructions accordingly.

You can scroll through the results using the arrow keys. Doing so in this case, we discover that (inter alia):

  • Four items are returned, of which the first and third (DRM_I915, and DRM_I915_USERPTR) are relevant;
  • The output shows that (e.g.) the DRM_I915 item (which will appear in the /usr/src/linux/.config file as CONFIG_DRM_I915) is to be found under the Device Drivers menu, by following down into the Graphics Support submenu. We also see that its prompt in the upper-pane menu will (as is common with this software!) will be distinct from the DRM_I915 name (it will actually appear as "Intel 8xx/9xx/G3x/G4x/HD Graphics").
  • The dependencies of this driver are also shown (you can drag the ssh terminal window on your helper machine wider to see any that may have been clipped off). Generally, for an item to be available for selection or modularization, all its dependencies must be satisfied: either selected (=y, the same as an asterisk) or modularized (=m). In some cases, items whose dependencies are unsatisfied will not be visible other than through a search like this.

This last point bears repeating, since it confuses many first-time users: an item will often not even appear in menuconfig's top pane until its dependencies have been satisfied. It would be nice if menuconfig would allow us to activate/modularize "an item and all its dependencies, transitively" from the search results screen, but it currently cannot, so we must perform this depth-first recursion manually.

OK, so let's work through the DRM_I915 case as a concrete example. From the search just performed we can see that, of the requirements for DRM_I915, only the DRM item is currently deselected. Well then, let's investigate DRM: we hit Enter to exit current search, then / to search again, and type in DRM and press Enter. The item we want here is the first result term. All its dependencies appear satisfied in the current configuration, and we note also that it appears under "Device Drivers -> Graphics support", and that its prompt is "Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)":

Search Results for DRM (Dependency)

Now we know there are no further unsatisfied dependencies for DRM_I915, we can activate DRM, and then DRM_I915 itself.

There's a handy shortcut you can often use when searching in menuconfig: if the result you are interested in has a parenthesised number shown by it near the left margin, such as (1), (2) etc., then you can simply press the corresponding number key (1, 2, etc.) to jump directly to the item in question. Then, once you're done editing it, pressing Esc then Esc will bring you back to the search results again. In the below text, we're going to do things the longhand way, for clarity, but using the number-key shortcuts is usually a better way to go, once you are familiar with the make menuconfig flow.

Begin by pressing Enter to exit the current search, then use the arrow keys to navigate to the "Device Drivers" item (if not visible to begin with, the top pane will scroll as you arrow down), then press Enter to enter the submenu. Next, repeat the process to select the "Graphics support" item, and press Enter:

Select Device Drivers Menu...
...Then Graphics support Submenu
If you are unsure of an item, you can press ? when it is highlighted; this will show its help information, including symbol name.m

One other point to bear in mind is that any symbol, for example DRM_I915, will have a CONFIG_ prefix attached when written out to a .config file. You will occasionally see these CONFIG_ prefixes appear in the help text too (in point of fact, the help for DRM_I915 refers to it as CONFIG_DRM_I915). However, don't be confused: CONFIG_DRM_I915 is the same as DRM_I915.

If you do press ? to view an item's help text, just press the Enter when you are finished reading, to close it and go back.

Now, move to the "Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)" item. This is the DRM symbol we want (as just mentioned, you can verify using ? if you like). Press y to enable it (this causes a number of subitems to appear, and also enables this entry itself as a submenu heading (not obvious unless you drag your window wider than the default 80 columns, so you can see the ---> suffix that appears post-selection):

Selecting Direct Rendering Manager (XFree86 ...)...
We're taking the approach of selecting required components directly (requesting they be built into the kernel itself), rather than modularizing them, but this is generally not mandatory. buildkernel copies all modules into the initramfs, so whether or not to modularize is ultimately up to you - it will have no effect on your ability to boot (certainly for elements like this that were disabled in the minimal install configuration to begin with).
Further to the above, for certain video cards which require a runtime firmware upload (such as more modern AMD/ATI Radeon units using the amdgpu radeonsi GRAPHICS_CARD flags), it is actually preferable to specify the necessary kernel drivers as modules (rather than building them in). This avoids having to explicitly compile firmware into the kernel (buildkernel copies all modules and firmware into the initramfs anyway, so this is safe to do).

So, now that we have set DRM, we can proceed to enable DRM_I915 itself. Navigate down the Graphics support menu, through the new items that appeared when you selected DRM, until you reach the Intel 8xx/9xx/G3x/G4x/HD Graphics item (if you think this feels rather like a 70's era adventure game, you're not alone!):

Causes Further Menu Items to Appear...
...Such as the Intel i915 Driver

You can verify that this is indeed the DRM_I915 item, by using using ? if you like; then, press y to enable it:

Finally, Select HD Graphics Driver (DRM_I915)

And that's it, you're done. Hit Esc then Esc to come back out to the "Device Drivers" menu. Hit Esc then Esc again to come back out to the top-level menu. Finally, hit Esc then Esc again, to exit the program. When prompted, ensure <Yes> is selected, and press Enter to save the new configuration and quit menuconfig:

Saving New Configuration and Exiting

Once you have exited menuconfig, buildkernel will automatically create a kernel with the newly created configuration, sign it, and copy it over to the boot USB key. Wait for the process to complete (you get the message "All done!"). Then issue:

(1) koneko ~ #exit

which will close the first screen terminal, then:

(2) koneko ~ #exit

to close the second one. Then, ensure the boot USB key is still inserted in the target machine and restart it, by issuing:

koneko ~ #systemctl reboot
If you have problems rebooting with this new kernel, you can follow the instructions given earlier to revert back to the backup (previous) version on the boot USB key - which won't have your configuration changes - and try again.
It's useful to relate the process just described to the 'kernel configuration shorthand' you will often see on the Gentoo wiki, and many other places on the web. For example, looking at the "intel" page on the wiki, we read that you need to enable the following kernel options:
KERNEL linux-4.4
        Device Drivers  --->
            Graphics support  --->
                <*> /dev/agpgart (AGP Support)  --->
                    --- /dev/agpgart (AGP Support)
                    -*-   Intel 440LX/BX/GX, I8xx and E7x05 chipset support
                <*> Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)  --->
                    --- Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)
                    [*]   Enable legacy fbdev support for your modesetting driver
                <*> Intel 8xx/9xx/G3x/G4x/HD Graphics
                [ ]   Enable preliminary support for prerelease Intel hardware by default
                -*- Backlight & LCD device support  --->

This is really just informing you of the menu locations (and prompts) of the options you need to choose, and how to set them (here, all have asterisks, so implying you should ideally select, rather than modularize). All of the above should be familiar from the process just described, those that we didn't cover are either selected by default on the current Gentoo minimal install kernel configuration, or are automatically selected by DRM_I915.

Generally speaking, when presented with a configuration list like this, you can just work through the menus in the order provided and enable the items - the author will have done the 'depth first' dependency pass for you. However, this isn't foolproof, so if an item referred to in such a list appears missing, simply search for it, and check that its dependencies are set, as we have done above.

Remember also that symbols do get dropped from (and obviously, added to) the kernel configuration set over time, so if you are working from an old set of instructions, a specified item may have been obsoleted and removed. Do an internet search if unsure.

There's some further information about the kernel configuration shorthand notation on the Gentoo wiki.

In the later part of this tutorial, I will assume that you are able to translate these 'shorthand' kernel configuration recipes, using buildkernel --menuconfig, without spelling out the process step-by-step. If in doubt, please re-read this section. (And if you are reading this now because you were jumped back to this section from a later chapter, you can click here to return - otherwise, just continue reading!)

When the machine restarts, as before, you will need to enter your LUKS keyfile gpg passphrase (the one you created earlier), directly at the target machine keyboard.

Once this has been completed successfully, and the target machine is restarted, from the helper PC, log back in again via ssh:

user@pc2 $ssh root@
Password: <enter root password>
... additional output suppressed ...
Substitute whatever IP address you got back from ifconfig earlier for in the above command. It is possible (although unlikely, with modern DHCP) that the target's IP address will have changed during the reboot. If so, log in directly at the target machine's keyboard, use ifconfig to find out the new address, then issue the above ssh command citing that address. As before, in such a case you may need to clean out any previous record of ssh connections to (other machines at) that new address (since the fingerprints will not match), using:
user@pc2 $sed -i '/^[^[:digit:]]*[^[:digit:]]/d' ~/.ssh/known_hosts

obviously substituting the new address for in the above. Then, be sure to check the fingerprint when prompted (by the subsequent ssh command), against those you noted down earlier.

If installing over WiFi, and you had to manually restart wpa_supplicant in the previous two chapters, then you'll need to do so again here (directly at the target machine's keyboard) before you'll be able to ssh in.

Then, re-establish screen (enter all commands via the ssh console from the helper PC, unless otherwise stated). Issue:

koneko ~ #screen
koneko ~ #export PS1="(1) $PS1"

to start screen. Then, press Ctrla then c to start a new virtual console, and in that new console enter:

koneko ~ #export PS1="(2) $PS1"

Now hit Ctrla then p to get back to the original console. Log back in as your regular user:

(1) koneko ~ #su --login sakaki
Substitute the user name of the regular user you created in the earlier step for sakaki in the above command.

And now rejoin the tutorial from the point where you attempted to run startx, above. Hopefully, all should be well this time. Good luck!

If you are using the i915 driver, you may find that you cannot change the screen brightness, and that the screen appears dim. This issue is addressed later in the tutorial.
If you still have problems, the Gentoo wiki page on X11 configuration may contain some useful pointers. With a modern X setup however, problems are almost always as a result of incorrect kernel configuration (or possibly incorrect VIDEO_CARDS or INPUT_DEVICES variables in /etc/portage/make.conf), rather than incorrect X configuration.

Installing GNOME 3

Now that we know X works, we can install GNOME! Let's begin by removing the temporary X window manager and applications (which we installed, for testing purposes only, earlier).

Issue (from the helper PC ssh/screen terminal):

sakaki@koneko ~ $exit

to get back to the root user, then:

(1) koneko ~ #emerge --ask --verbose --depclean x11-wm/twm x11-terms/xterm x11-apps/xclock x11-apps/xsetroot
... additional output suppressed ...
Would you like to unmerge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
Using the --depclean option to emerge in this way is a common idiom to safely uninstall packages in Gentoo. If any of the specified atoms happens to be a dependency of another installed package (even transitively), it will not be removed.

Now for GNOME itself. There are some additional USE flags we'll need here: to turn on UPnP audio/video streaming support for the media-plugins/grilo-plugins package, to ensure that the www-servers/apache web server works in a non-threaded fashion, to enable the Samba client, to turn on Python support (and/or, bindings) for certain applications, and to add some additional image format support to the media-libs/gegl image processing framework. To enable these, issue:

(1) koneko ~ #echo -e "# required for GNOME\n>=media-plugins/grilo-plugins-0.2.13 upnp-av" >> /etc/portage/package.use/grilo-plugins
(1) koneko ~ #echo -e "# required for GNOME\n>=www-servers/apache-2.2.31 apache2_mpms_prefork" >> /etc/portage/package.use/apache
(1) koneko ~ #echo -e "# required for GNOME\n>=net-fs/samba-4.2.14 client" >> /etc/portage/package.use/samba
(1) koneko ~ #echo -e "# required for GNOME\n>=sys-libs/ntdb-1.0-r1 python" >> /etc/portage/package.use/ntdb
(1) koneko ~ #echo -e "# required for GNOME\n>=sys-libs/tdb-1.3.8 python" >> /etc/portage/package.use/tdb
(1) koneko ~ #echo -e "# required for GNOME\n>=sys-libs/tevent-0.9.28 python" >> /etc/portage/package.use/tevent
(1) koneko ~ #echo -e "# required for GNOME\n>=media-libs/gegl-0.3.0 jpeg2k raw" >> /etc/portage/package.use/gegl

Now we are ready to install GNOME! Issue:

(1) koneko ~ #emerge --ask --verbose --keep-going gnome-base/gnome
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
If, when attempting the emerge, you are prompted with a series of missing package-specific keywords, USE flags, licences, or masks, followed by the question:
... additional output suppressed ...
Would you like to add these changes to your config files? [Yes/No]
you can answer y and Enter; this will place append the proposed changes into the files /etc/portage/package.accept_keywords/zzz_via_autounmask, /etc/portage/package.license/zzz_via_autounmask, /etc/portage/package.unmask/zzz_via_autounmask and /etc/portage/package.use/zzz_via_autounmask (as appropriate). You can then run dispatch-conf to review the changes. Press u ("use new") to accept the changes for each modified file, if happy. Then try the emerge again.

As before, you can switch to the second screen console we prepared earlier, to watch the progress (as the files download, build etc.). Hit Ctrla then n to switch to the second console (you can do this while the emerge is running), and issue:

(2) koneko ~ #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 emerge process as it progresses. You can exit the showem program at any time by issuing Ctrlc.

The emerge will take quite some time to complete! Note that the --keep-going option instructs emerge to build as much as possible, even if some errors are encountered. This is useful here because, due to the size of the build, it is possible that you may come across one or two failed packages.

Most often, any failures will be caused by the high level of make paralleism we are using. Accordingly, if, at the conclusion of the above emerge, near the end of the output you see a message that:

... additional output suppressed ...

* The following <n> packages have failed to build or install:

... additional output suppressed ...

then issue the following command, to re-attempt to build the failed packages, this time without make parallelism:

(1) koneko ~ #MAKEOPTS="-j1" EMERGE_DEFAULT_OPTS="--jobs=1" emerge --ask --verbose gnome-base/gnome
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

(Of course, if the original emerge completed successfully, there is no need to issue the above, but, as gnome-base/gnome is a meta-package, it is still safe to do so, and won't cause all the dependencies to be rebuilt.) You may need to repeat this step multiple times to get GNOME emerged successfully (I have found three or four iterations may be necessary). As long as the 'packages to be installed' count keeps falling, keep trying ^-^

With such a large emerge as this, it is — in case of a build failure — often actually worth trying the original command verbatim (i.e., without the MAKEOPTS="-j1" EMERGE_DEFAULT_OPTS="--jobs=1") first, since, if this clears the problem, the rest of the build will then proceed much faster. When you get more experienced with Gentoo, you'll be able to determine which types of build error are likely indications of an ephemeral parallelism problem, and which are just plain bugs (unlikely for packages on the 'stable' branch, but always possible).
If, after all this, you still experience build errors emerging gnome-base/gnome, you find it useful to refer to these earlier notes. It is also possible to emerge the smaller package gnome-base/gnome-light (instead of gnome-base/gnome), and then add applications later.

Once the process has completed, ensure you are back in the virtual terminal from where you issued the emerge command (i.e., not the showem terminal), and then issue the following to ensure your environment is up-to-date post-install:

(1) koneko ~ #env-update && source /etc/profile && export PS1="(1) $PS1"

Hit Ctrla then n to go to the second screen console, and do the same there. Issue:

(2) koneko ~ #source /etc/profile && export PS1="(2) $PS1"

Then press Ctrla then p to switch back to the original console again.

Make sure any regular users are members of the plugdev group (if it exists on your target machine). Issue:

(1) koneko ~ #getent group plugdev && gpasswd -a sakaki plugdev
Substitute the user name of the regular user you created in the earlier step for sakaki in the above command. If you add other regular users, be sure to add them to plugdev in a similar manner. This is to allow full access to NetworkManager services, which require the plugdev group.[11]

If you wish your regular user to be able to play the GNOME games (assuming you have chosen to install them), then issue (this is optional):

(1) koneko ~ #getent group games && gpasswd -a sakaki games
Again, substitute the user name of the regular user you created in the earlier step for sakaki in the above command.

Next, we need to log back in as our regular user, and try out our new desktop! Issue:

(1) koneko ~ #su --login sakaki
Substitute the user name of the regular user you created in the earlier step for sakaki in the above command.

Next, edit the .xinitrc file in the regular user's home directory. Issue:

sakaki@koneko ~ $nano -w ~/.xinitrc
Obviously, as before, the name that you see in the prompt will reflect that of the regular user you added (and which you just su-d to).

Delete the current contents of .xinitrc (you can use Ctrlk inside nano to delete a line at a time), and replace with the following text:

FILE ~/.xinitrcReplace existing text with the below to start GNOME
export XDG_MENU_PREFIX=gnome-
exec gnome-session

Save and exit nano.

Don't forget the hyphen at the end of gnome- (as shown above). Also, note that there is no need to start the file with a shebang this time.

OK, time to try it out! Issue:

sakaki@koneko ~ $startx

And hopefully you should be greeted with a (rather startlingly empty!) GNOME 3 desktop, somewhat similar to the below, on the target machine:

GNOME Shell Basic Desktop (via startx)
The precise layout etc. that you see may of course differ, due to version changes in GNOME. Also, you may experience some issues the first time you try running GNOME in this manner (strange display glitches etc.); if so, simply try quitting (by issuing Ctrlc at the helper PC ssh/screen terminal) and then running startx again.

You can try playing around with it briefly if you like (some simple instructions may be found here - or just get started by moving your mouse pointer up to the top left corner of the screen (and optionally, clicking on 'Activities'), or by pressing Windows Key), using the target machine keyboard and mouse / touchpad directly. Note, however, that this isn't a properly logged-in instance, so certain of the standard features will not function as you expect. You should be able to start a terminal etc. however. When you're done, kill the test instance, by issuing Ctrlc at the helper PC ssh/screen terminal (the one where you just issued startx).

Testing GNOME 3 (and Refining Settings)

Congratulations, GNOME 3 is now basically functional; we only need a few more steps to get it fully operational on your machine! So, let's continue. Come back out to be root again:

sakaki@koneko ~ $exit

Next, we must enable the NetworkManager service (which will handle all network interaction under GNOME), and disable the dhcpcd service, which we started earlier (and whose functionality NetworkManager supplants). First, issue:

(1) koneko ~ #systemctl stop dhcpcd
(1) koneko ~ #systemctl disable dhcpcd
As before, with systemd's systemctl command, you use:
  • stop to stop a running service immediately;
  • disable to ensure a service doesn't start at boot time;
  • enable to ensure a service will (try to) start at boot time; and
  • start to run running a service immediately.

Next, if you are using WiFi for the install, you'll also have explicitly set up a wpa_supplicant configuration file earlier in the tutorial, and so you need to remove this again now (however, skip this step if installing over a wired Ethernet connection):

(1) koneko ~ #mv -v /etc/wpa_supplicant/wpa_supplicant.conf /etc/wpa.conf

Now we can ensure NetworkManager comes up on boot (however, do not start it yet, since you may lose network connectivity when you do). Issue:

(1) koneko ~ #systemctl enable NetworkManager

That having being done, we need to make sure that the GNOME Display Manager (gdm) is configured to run on boot (and also, we'll start up an instance now, together with NetworkManager). Issue:

(1) koneko ~ #systemctl enable gdm
(1) koneko ~ #systemctl start NetworkManager && systemctl start gdm

Assuming that worked, you should now be able to see a GNOME login screen on the target machine, similar to the below:

GNOME 3 Login Screen
If you don't see your regular user's user name appear (as for 'sakaki' in the above screenshot), click on the "Not listed?" text, and type in the user name when prompted (directly at the target machine's keyboard)).
You may need to press Enter once or twice (directly on the target machine's keyboard) to see the login prompt, if the screen has blanked.
If you are installing via WiFi, you will temporarily lose connectivity (to ssh etc.) when bringing up NetworkManager in this manner, since it doesn't yet know your network settings. However, once NetworkManager is configured (as described next), you should be able to re-establish the ssh connection.

Directly at the target machine, click on the (regular) user name then, when prompted, type in the (regular user) password you set up earlier.

If your password is rejected, it may be because you do not (yet) have the correct keyboard settings in GNOME (particularly if you have a non-US keyboard, as the Panasonic CF-AX3 does, for example). You can click on the 'man in a circle' accessibility icon in the top bar, and use the on-screen keyboard to enter your password in this case. Afterwards, it is easy to change your keyboard setup via the 'Region & Language' settings panel in GNOME, as described below.

You should arrive back at the GNOME desktop (only this time, with a little more functionality, since this is a normal login session).

Before our final reboot (at which point, we will no longer require the helper PC, but will be using the target machine natively), there are three additional tasks we need to carry out:

  1. ensuring that network settings are correct;
  2. setting up keyboard settings are correct within GNOME (if required); and
  3. ensuring that our the system remembers our volume preferences between reboots.

GNOME Network Settings

You should now make sure that your network settings are correct under GNOME. Any wired connection should have been picked up fine, but if you have been installing using WiFi, you'll need to select an access point, and enter your wireless passphrase, to regain network connectivity.

To do that, simply click on the 'downwards pointing triangle' in very top right of the screen. This will show a drop-down menu, from which you can turn on WiFi, and select an access point (you'll be prompted for the passphrase). (Alternatively, you can press the Windows Key, then type "settings" (and press Enter), then click on the item titled 'Network' in the panel that appears.) It's a fairly self-explanatory interface, but if you need assistance, simply press F1.

If you start playing around with your system now, you'll probably find that there are a few things, like Bluetooth for example, and possibly even WiFi (depending on your setup), that are not working yet. That's because we haven't yet enabled all necessary kernel drivers - but we will address this in the next chapter!
Some users have commented that GNOME (and in particular, WiFi) does not come up properly, until their machine is restarted with gdm enabled. Therefore, if you are experiencing any problems with GNOME at this stage (such as your WiFi passphrase being rejected), it may be worth waiting, and trying again once we have rebooted in the final configuration (which we'll do very shortly, below).

Once you have the network set up, you should be able to browse the web etc. Try this now: directly at the target machine's keyboard, press the Windows Key and type 'Web', then press Enter to start the first item shown. GNOME's default web browser will start up, initially full-screen. You can drag it down by the top bar to make it a normal-sized window, type in a URL etc.:

Searching for a Web Browser in GNOME...
...And Using the Default Browser

GNOME Keyboard Settings

If you have a non-US keyboard (as in the case of the Panasonic CF-AX3), you will need to set this in GNOME. Press the Windows Key, then type "region" (and press Enter) and click on the Region & Language item in the list. This opens a control panel. Make sure the 'Language' and 'Formats' in the top pane are correct for your locale. Then, add the appropriate 'input source' in the bottom pane. Click on the 'plus' sign icon, and an "Add an Input Source" panel will appear. Click on the tile showing three stacked dots, and drag the panel slightly larger vertically (as otherwise the output will be hidden). You should now be able to click on the 'Other' tile that appears, and then select the required source from the full list, and then click on 'Add' (in my case, I actually added three: "English (UK)" (for my plug-in keyboard), "Japanese" for the machine's built-in keyboard, and "Japanese (Anthy)" for kanji and kana input - obviously, your requirements will probably differ). When done, close out the "Region & Language" dialog.

Once an item has been added, it can be activated via a drop down in the top bar of the screen. In the case of the CF-AX3, you'd want to select 'Japanese' from this list, so that the keyboard mapping is correct (even if you are typing everything in English!) Be sure to check this, if you have problems having your password accepted at the GNOME login screen.

If you have a standard US-layout machine and are using it in the US, this section will probably not apply to you. Nevertheless, you should still check that that the 'Language' and 'Formats' elements are set correctly in the "Region & Language" panel.
GNOME has quite extensive context-sensitive help, which you can access by pressing F1 in any panel (for example, try it with "Region & Language" open - you'll be able to read useful hints about switching layouts using keyboard accelerators, having a layout per window or one for all windows, and more.

GNOME Volume Control

You may find that although you can set sound levels using the 'speaker icon' menu in the GNOME top bar, these settings are lost on a reboot (and sound is muted each time). If this occurs on your system (it affects the CF-AX3), take the following steps. First, emerge media-sound/alsa-utils (you can do this via the ssh/screen terminal on the helper PC):

(1) koneko ~ #emerge --ask --verbose media-sound/alsa-utils
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

Once that completes, set the volume levels as you like them, then issue:

(1) koneko ~ #alsactl store

The settings should now be preserved across a reboot.

You may also need to change your output settings in the GNOME 'Sound' control panel to hear anything: on the CF-AX3, you need to choose the 'Analog Output' option, which is not selected by default.

Restarting into GNOME!

We are now ready to bid farewell to the services of the helper PC, as all further steps can now be done on the target machine directly. Close out the ssh/screen terminal. Issue:

(1) koneko ~ #exit

which will close the first screen terminal, then:

(2) koneko ~ #exit

to close the second one, then:

koneko ~ #exit

which will close out the ssh session itself.

If installing over WiFi, it is possible that your ssh session may have hung when you temporarily lost connectivity due to starting NetworkManager above, making it impossible to enter the above exit commands. If this has happened to you, simply close its surrounding terminal on the helper PC.

Now, ensure that the USB boot key is inserted in the target PC, and reboot it, by clicking on the 'power' icon (in the top right of the screen), clicking on the 'power' button in the dropdown menu that then appears, and then clicking on the 'Restart' button in the dialog.

The machine should then power cycle (you will be cleanly logged out of GNOME first). When the machine restarts, as before, you will need to enter your LUKS keyfile gpg passphrase (the one you created earlier), directly at the target machine keyboard to unlock the LUKS partition. You should then be presented directly with a GNOME login page (as above). Directly at the target machine, click on your (regular) user name then, when prompted, type in the (regular user) password you set up earlier (ensure you have the correct keyboard settings, if relevant, as discussed above).

Once logged in to GNOME, bring up a web browser: directly at the target machine's keyboard, press the Windows Key and type 'Web', then press Enter to start the first item shown. GNOME's default web browser will start up, initially full-screen. You can drag it down by the top bar to make it a normal-sized window. Do so, and type in the URL for this tutorial, so that you can continue to follow it there.

From this point on, all interaction with the target machine will be done directly (and not via the helper PC), unless otherwise noted.
Now that NetworkManager is running, even if you have been installing over WiFi, and had to manually restart wpa_supplicant in the previous two chapters, there should be no further need to do so. WiFi network access should now come online automatically after boot.

Now, bring up a terminal window in GNOME. Press the Windows Key again, and type 'terminal', then press Enter. A standard-issue terminal window should open. As we have some final installation work to do, become root:

sakaki@koneko ~ $su --login root
Password: <enter root password>

The password required here is the one you set up earlier in the tutorial (and have used when ssh-ing in).

Next Steps

Congratulations - if you have followed through to this stage, you have a basically functioning system! There is some final driver configuration left still to do, so let's address that now. Click here to go to the next chapter, "Final Configuration Steps".


< Previous Home Next >