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

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, such as: and uses accelerated, modern-looking graphics:
 * launching applications,
 * switching windows and desktops,
 * searching for programs and files,
 * notification management, etc.



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

Right, let's get started!

Adding a User for Daily Use
Per the 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) :

The meaning of those useradd options is as follows:

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

We need to set a few USE flags for (an OpenGL-like library which X pulls in as a dependency), so issue:

and append:

Save and exit nano.

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

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</tt>. Issue:

to start screen</tt>. Then, press then  to start a new virtual console, and in that new console enter:

Now hit then  to get back to the original console.

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

and the X11 server will be downloaded and installed. Note that we use --oneshot</tt> 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).

<span id="temp_install_twm">Temporarily Installing an X11 Window Manager and Applications
To be <span id="install_x_test_apps">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), and the following apps:
 * : a background ('root') window parameter setting utility for X;
 * : a simple clock display for X; and
 * : the standard terminal emulator for X.

Issue:

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

Next, we need to tell X11 what window manager and apps to use whenever it starts up. The .xinitrc</tt> 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</tt>/screen</tt> console, issue:

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

Put the following text in the .xinitrc</tt>:

Save and exit nano</tt>.

The above shell script simply instructs X to:
 * start the Tab Window Manager (twm</tt>) 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.

<span id="first_try_startx">Now we are ready to try it out!

Still on the ssh</tt>/screen</tt> console, issue:

If all goes well, the screen of your target PC should now be displaying something like the below: (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</tt>") 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):

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

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.

<span id="if_x11_fails">Troubleshooting a Failed X11 Startup
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 <tt>DRM_I915</tt> driver; this is needed for the integrated "HD Graphics" on many Ultrabooks (such as the Panasonic CF-AX3);
 * the <tt>DRM_NOUVEAU</tt> 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 <tt>startx</tt> (the output in the <tt>ssh</tt>/<tt>screen</tt> virtual terminal, that is, not on your target machine's display).

If you see output such as:

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

To rectify this, we need to <span id="make_menuconfig_intro">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 <tt>ssh</tt>/<tt>screen</tt> virtual terminal):

to drop back to the <tt>root</tt> user.

Then:

to start the kernel rebuild process going. Because you have not specified <tt>--ask</tt> here, but you have specified <tt>--menuconfig</tt>, the process will run through by itself (assuming no errors) to the point where you can modify the kernel configuration using the standard <tt>curses</tt>-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 <tt>menuconfig</tt> system is a simple tool used to modify Linux kernel configurations (aka "<tt>.config</tt>" files) in a coherent manner. The tool will not let you make inconsistent choices, and has a useful search facility.

When <tt>menuconfig</tt> 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):

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, viz.:
 * <Select> enters a sub-menu, for items (in the top pane) ending with <tt>---></tt>, or brings up a text entry box for items which start with round brackets "<tt></tt>";
 * <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 then  to perform this action;
 * <Help> shows a help screen that is relevant to the (top pane) selection; you can also press 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:
 * <tt>[ ]</tt>, <tt>[*]</tt> : Square brackets indicate features that are deactivated (blank) or activated (asterisk). Press to toggle status, or  to activate,  to deactivate. Activated items are built directly into the kernel; deactivated items are omitted from it entirely.
 * <tt>< ></tt>, <tt><M></tt>, <tt><*></tt> : Angle bracketed items can similarly be deactivated (blank) or activated (asterisk), but can additionally be built as modules ("<tt>M</tt>"). In addition to, and , you can use  with such items to specify that they should be modularized.
 * <tt>{M}</tt>, <tt>{*}</tt> : Curly brackets indicate items which cannot be deactivated (due to another item's dependency). However, they may be activated or modularized (using, or , as before).
 * <tt>-M-</tt>, <tt>-*-</tt> : Similarly, hyphens indicate items whose status cannot be changed (their selection having been forced as the result of another item choice).

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 <tt>i915</tt> module, press then type in <tt>i915</tt>, then press  to see the search results:

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 two (<tt>DRM_I915</tt> and <tt>DRM_I915_KMS</tt>) are relevant;
 * The output shows that (e.g.) the <tt>DRM_I915</tt> item (which will appear in the file as <tt>CONFIG_DRM_I915</tt>) is to be found in the <tt>Graphics support</tt> submenu under the <tt>Device drivers</tt> submenu. We also see that its prompt in the upper-pane menu will (as is common with this software!) will be distinct from the <tt>DRM_I915</tt> name (it will actually appear as "<tt>Intel 8xx/9xx/G3x/G4x/HD Graphics</tt>").
 * The dependencies of this driver are also shown (you can drag the <tt>ssh</tt> 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 (<tt>=y</tt>, the same as an asterisk) or modularized (<tt>=m</tt>). 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 <tt>menuconfig</tt>'s top pane until its dependencies have been satisfied. It would be nice if <tt>menuconfig</tt> 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 <tt>DRM_I915</tt> case as a concrete example. From the search just performed we can see that, of the requirements for <tt>DRM_1915</tt>, the <tt>DRM</tt> and <tt>AGP_INTEL</tt> items are currently deselected. Well then, let's recursively investigate <tt>DRM</tt>: we hit to exit current search, then  to search again, and type in <tt>DRM</tt> and press. 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 "<tt>Device Drivers -> Graphics support</tt>", and that its prompt is "<tt>Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)</tt>". Next, let's recurse into <tt>AGP_INTEL</tt>. Press to exit the current search, then  to search again, and type in <tt>AGP_INTEL</tt> and press. Just one result this time, and again, all dependencies appear currently satisfied. Here, the location is "<tt>Device Drivers -> Graphics support -> /dev/agpgart (AGP Support)</tt>", and it will appear in the menu as "<tt>Intel 440LX/BX/GX, I8xx and E7x05 chipset support</tt>":

Now we know there are no further unsatisfied dependencies for <tt>DRM_I915</tt>, we can activate those we've discovered. We'll start with <tt>AGP_INTEL</tt>. Press to exit the current search, then use the arrow keys to navigate to the "<tt>Device Drivers</tt>" item (if not visible to begin with, the top pane will scroll as you arrow down), then press  to enter the submenu. Next, repeat the process to select the "<tt>Graphics support</tt>" item, and press :

Now, select the "<tt>/dev/agpgart (AGP Support)</tt>" item, and press to enter the submenu. Move down to the line starting "Intel 400LX/BX/GX", and press to enable it, as shown:

Now <tt>AGP_INTEL</tt> is set, we can proceed to enable <tt>DRM_I915</tt>'s other unmet dependency, <tt>DRM</tt>. Press then  to come back out one menu level (back to "<tt>Graphics support</tt>"), then select the line starting "<tt>Direct Rendering Manager</tt>" (remember, if you are unsure this is the item whose symbol is <tt>DRM</tt>, you can always check it first, by pressing  when highlighted). Press to enable it. This unlocks a set of subitems, which now appear:

One of these is what we're after - move down until the line starting "<tt>Intel 8xx/9xx/G3x/G4x/HD Graphics</tt>" is highlighted (this is in fact our original target, the <tt>DRM_I915</tt> item, which you can verify using if you like), then press  to enable it. Doing so causes yet more items to appear (feels rather like a 70's era adventure game!):

The first of these is <tt>DRM_I915_KMS</tt>, which is also necessary for X11 to start correctly. Move to it, and select it by pressing :

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

Once you have exited <tt>menuconfig</tt>, <tt>buildkernel</tt> 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 "<tt>All done!</tt>"). Then issue:

which will close the first <tt>screen</tt> terminal, then:

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

When the machine restarts, as before, you will need to enter your LUKS keyfile <tt>gpg</tt> 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 <tt>ssh</tt>:

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

to start <tt>screen</tt>. Then, press then  to start a new virtual console, and in that new console enter:

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

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

<span id="install_gnome3">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 <tt>ssh</tt>/<tt>screen</tt> terminal):

to get back to the <tt>root</tt> user, then:

Now for GNOME itself. There are two minor license exceptions (to our license group (<tt>@FREE</tt>), which we set earlier), that we'll need to allow for GNOME. These are benign (the license in question, "<tt>CC-Sampling-Plus-1.0</tt>" is essentially a free-use license, but is not currently included in <tt>@FREE</tt>; it may be viewed at ). Issue:

Then append:

Save and exit the <tt>nano</tt> editor.

As of the time of writing, there is a circular dependency which will prevent the installation of GNOME 3. To solve this, issue:

The package will be replaced by one with the correct USE flag set in the next step; we have used the <tt>--oneshot</tt> option in the above to prevent it being recorded in your <tt>@world</tt> set.

Now we are ready to install GNOME! Issue:

The <tt>emerge</tt> will take quite some time to complete! Note that the <tt>--keep-going</tt> option instructs <tt>emerge</tt> 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 <tt>make</tt> paralleism we are using. Accordingly, if, at the conclusion of the above <tt>emerge</tt>, near the end of the output you see a message that:

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

(Of course, if the original <tt>emerge</tt> completed successfully, there is no need to issue the above, but, due to the <tt>--noreplace</tt> flag, even if you do it will simply exit immediately, so it is always safe.)

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

Hit then  to go to the second <tt>screen</tt> console, and do the same there. Issue:

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

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

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

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

Save and exit <tt>nano</tt>.

OK, time to try it out! Issue:

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

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, or by pressing ), 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 at the helper PC <tt>ssh</tt>/<tt>screen</tt> terminal (the one where you just issued <tt>startx</tt>).

<span id="testing_gnome3">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 <tt>root</tt> again:

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

Next, if you are using WiFi for the install, you'll also have explicitly set up a <tt>wpa_supplicant</tt> 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):

<span id="start_nm">Now we can fire up <tt>NetworkManager</tt>. Issue:

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

Assuming that worked, <span id="login_to_gnome">you should now be able to see a GNOME login screen on the target machine, similar to the below:

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

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.

<span id="gnome_network_settings">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, then type "<tt>settings</tt>" (and press ), 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.

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 and type 'Web', then press  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.:

<span id="gnome_keyboard_settings">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, then type "<tt>region</tt>" (and press ) and click on the <tt>Region & Language</tt> 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 "<tt>Region & Language</tt>" dialog.

Once an item <span id="input_source_menu">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.

<span id="gnome_volume_control">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 (you can do this via the <tt>ssh</tt>/<tt>screen</tt> terminal on the helper PC):

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

The settings should now be preserved across a reboot.

<span id="restart_to_gnome">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 <tt>ssh</tt>/<tt>screen</tt> terminal. Issue:

which will close the first <tt>screen</tt> terminal, then:

to close the second one, then:

which will close out the <tt>ssh</tt> session itself. 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 <tt>gpg</tt> 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 and type 'Web', then press  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.

Now, <span id="open_gnome_terminal">bring up a terminal window in GNOME. Press the again, and type 'terminal', then press. A standard-issue terminal window should open. As we have some final installation work to do, become root:

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

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

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide: