12a_Setting_up_the_GNOME_3_Desktop_under_OpenRC

<!-- Page: Setting_up_the_GNOME_3_Desktop_under_OpenRC -->

<span id="setup_gnome_desktop">In this section</span>, we'll be setting up {{Highlight|GNOME 3}} on your machine, using the modern [[:Wikipedia:Wayland_(display_server_protocol)|Wayland]] platform (including [https://wayland.freedesktop.org/xserver.html XWayland] support for legacy X11 applications).

GNOME 3 is a feature-rich desktop environment provided by the [https://www.gnome.org 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). Thanks to recent work on {{c|elogind}} within the official Gentoo tree,<ref name="elogind_gnome">Gentoo News: [https://gentoo.org/news/2019/03/27/gnome-330-openrc.html "Gentoo GNOME 3.30 for all init systems"]</ref> users can enjoy GNOME 3 under {{c|OpenRC}} with all features intact.

GNOME's user interface is known as the [[:Wikipedia:GNOME_Shell|"GNOME Shell"]]. It provides core user functions,<ref>[https://wiki.gnome.org/Projects/GnomeShell/CheatSheet GNOME Shell Cheat Sheet"</ref> such as:
* launching applications, 
* switching windows and desktops, 
* searching for programs and files,
* notification management, etc.
and uses accelerated, modern-looking graphics:

[[File:GNOME_Shell_3.24.png|thumb|none|400px|GNOME Shell v3.24 in Overview Mode]]

For more information about GNOME, see its [https://www.gnome.org official site] and [[:Wikipedia:GNOME|Wikipedia page]]. A list of GNOME releases may be found [[:Wikipedia:GNOME#Releases|here]].

GNOME requires graphical support scaffolding on which to run, and in previous versions of this guide, the [[:Wikipedia:X_Window_System|X Window System ("X11")]] fulfilled this role. Now, however, as the more modern, lightweight and secure [[:Wikipedia:Wayland_(display_server_protocol)|Wayland]] protocol has reached sufficient maturity for everyday use, we'll be leveraging that instead (with GNOME providing its own [[:Wikipedia:Compositing_window_manager|compositing window manager]], [[:Wikipedia:Mutter_(software)|{{c|mutter}}]]). As Kristian Høgsberg (one of the Wayland founders) writes in the project's FAQ:<ref name="wayland_faq">Høgsberg, K. [https://wayland.freedesktop.org/faq.html "Wayland FAQ"]</ref>

:: [[:Wikipedia:Wayland_(display_server_protocol)#Differences_between_Wayland_and_X|What’s different now]] is that a lot of infrastructure has moved from the [[:Wikipedia:Display_server|X server]] into the kernel (memory management, command scheduling, [[:Wikipedia:Mode-setting|mode setting]]) or libraries ([[:Wikipedia:Cairo_(graphics)|cairo]], pixman, [[:Wikipedia:Freetype|freetype]], [[:Wikipedia:Fontconfig|fontconfig]], [[:Wikipedia:Pango|pango]], etc.), and there is very little left that has to happen in a central server process. ... [An X server has] a tremendous amount of functionality that you must support to claim to speak the X protocol, yet nobody will ever use this. ... With Wayland we can move the X server and all its legacy technology to an optional code path.

Don't worry though &mdash; as we'll configure it here, you'll [[#x11_gnome_session|still have the option]] to log in to an old-school GNOME-on-X11 session if and when you want. Furthermore, even when using a GNOME-on-''Wayland'' session, applications that don't support Wayland natively will be handled using an integrated, rootless X11 server (under the so-called [[:Wikipedia:Wayland_(display_server_protocol)#Compatibility_with_X|XWayland]] approach).

{{Note|Performance notwithstanding, probably the strongest ''end-user'' reason to transition to a Wayland-based desktop is {{Highlight|security}}: unlike X11, by default Wayland enforces application isolation at the GUI level. You can read more about X11's vulnerability in this regard (and how to mitigate it, for legacy apps), in the [[../Sandboxing_the_Firefox_Browser_with_Firejail#x11_vulnerability{{!}}additional mini-guide, here]].}}

Accordingly, the process we'll be following in this section is:
# Adding a regular (non-root) user;
# Enabling the {{c|wayland}} USE flag (and additional dependencies) globally;
# Updating your system to reflect this, then installing an X11 server for legacy support, and baseline testing;
# Temporarily installing a simple X11 window manager, and a few applications, also for test purposes;
# Reconfiguring the kernel to include an appropriate [[:Wikipedia:Direct_Rendering_Manager|DRM]] graphics driver, recompiling using {{c|buildkernel}}, and rebooting;
# Verifying, upon restart, that the new DRM driver (which {{c|wayland}} requires) has been activated;
# Testing a simple X11 setup using [[:Wikipedia:Twm|{{c|twm}}]];
# Installing GNOME 3 and key applications, and testing under X11; then
# Testing GNOME 3 on {{c|wayland}}, and refining settings.

This section has no direct equivalent in the Gentoo Handbook (although the part about adding a user reflects the [[Handbook:AMD64/Installation/Finalizing#User_administration|"User Administration"]] section from Chapter 11, and the kernel DRM driver part has elements of the [[Handbook:AMD64/Installation/Kernel#Default:_Manual_configuration|"Default: Manual (Kernel) Configuration"]] section from Chapter 7). 

{{Note|You may find the article [[GNOME/Guide{{!}}"GNOME Configuration HOWTO"]] (from the Gentoo wiki) useful background reading.}}

{{Note|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 [[:Wikipedia:Controversy_over_GNOME_3{{!}}this Wikipedia article]] for example). And, until the advent of Dantrell B.'s patchset (and subsequent formal {{c|elogind}} support in the main Gentoo tree), forced you to use {{c|systemd}}...

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:
* [[:Wikipedia:LXDE{{!}}LXDE]] (via package {{Package|lxde-base/lxde-meta}}), 
* [[:Wikipedia:XFCE{{!}}XFCE]] (via package {{Package|xfce-base/xfce-meta}}) etc. 

A further alternative is to use [[KDE]] with OpenRC. Reportedly, it is possible to install this successfully (with EFI, secure boot etc.) by using this guide (together with the relevant [[KDE{{!}}Gentoo Wiki page]]) as a basis, but making the obvious changes where needed (e.g., selecting {{c|default/linux/amd64/17.0/desktop/kde}} as the profile etc.)

However, installing any of the above is currently beyond the explicit 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!

== <span id="add_regular_user">Adding a User for Daily Use</span> ==

Per the [[Handbook:AMD64/Installation/Finalizing#User_administration|Gentoo Handbook]], it is strongly recommended to set up a user for day-to-day use on your machine. Let's do that now. <span id="setup_regular_user">Issue (via the {{c|ssh}} connection from the helper PC)</span>:
{{RootCmd
|useradd --create-home --groups users,wheel,portage,lp,adm,audio,cdrom,disk,usb,video,cron --shell /bin/bash --comment "sakaki" sakaki
|passwd sakaki
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
New password: <enter your new password>
Retype new password: <enter your new password again>
passwd: password updated successfully
</pre>
}}
{{Note|Obviously, substitute your real name (for <code>"sakaki"</code>) and desired username (for <code>sakaki</code>)  in the above commands. You can also define multiple users at this point if you like.}}
{{Important|Be sure to write this password down somewhere safe! You will require it to log in later.}}
{{Note|Feel free to add or remove groups as required in the {{c|useradd}} command - the above set is a reasonable starting point for a 'power user' under {{c|OpenRC}} in Gentoo. See the description below for further information.}}

The meaning of those {{c|useradd}} options is as follows:

{| class="wikitable"
|-
! Parameter !! Short Form !! Meaning
|-
| {{c|--create-home}} || {{c|-m}} || Create the user's home directory if it does not already exist.
|-
| {{c|--groups}} || {{c|-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 [https://www.linode.com/docs/tools-reference/linux-users-and-groups#working-with-groups primary group]. The additional groups specified here have the following function:<ref>[https://www.debian.org/doc/manuals/securing-debian-howto/ch12.en.html#s-faq-os-users ''Securing Debian Manual'': Chapter 12: "Operating system users and groups"]</ref><ref>Ubuntu Wiki: [https://wiki.ubuntu.com/Security/Privileges "Privileges"]</ref><ref>Debian GNU/Linux Desktop Survival Guide: [http://www.togaware.com/linux/survivor/Standard_Groups.html "Standard Groups"]</ref><ref>Gentoo Handbook: [[Handbook:AMD64/Installation/Finalizing#Adding_a_user_for_daily_use|"Installation/Finalizing": Adding a user for daily use]]</ref>
{| class="wikitable"
|-
! Group !! Description
|-
| {{c|users}} || This is the standard group for users.
|-
| {{c|wheel}} || Members of this group can use {{c|su}} to masquerade as other users (including the {{c|root}} user), provided they know the appropriate password.
|-
| {{c|portage}} || Members of this group can perform {{c|emerge --pretend}} operations, and access {{c|portage}} log files.
|-
| {{c|lp}} || Members of this group can use printers attached to the system (important for Bluetooth printers too).<ref>ArchLinux Wiki: [https://wiki.archlinux.org/index.php/bluetooth#Installation "Bluetooth: Installation"]</ref>
|-
| {{c|adm}} || Members of this group have read access to many files in the {{Path|/var/log}} directory.
|-
| {{c|audio}} || Members of this group can access audio devices.
|-
| {{c|cdrom}} || Members of this group can administer printers attached to the system.
|-
| {{c|disk}} || Members of this group have 'raw' access to disks.
|-
| {{c|usb}} || Members of this group can access USB devices.
|-
| {{c|video}} || Members of this group can access video devices. Necessary for use of [[Xorg/Hardware_3D_acceleration_guide#Add_appropriate_user.28s.29_to_the_video_group|direct rendering]].
|-
| {{c|cron}} || Members of this group can setup their own [[:Wikipedia:Cron|crontab]] (for regularly scheduled tasks).
|}
|-
| {{c|--shell}} || {{c|-s}} || Specify the user's login shell. We've used [[:Wikipedia:Bash_(Unix_shell){{!}}bash]] here, as it is the default shell in Gentoo Linux.
|-
| {{c|--comment}} || {{c|-c}} || A short description of the login; most commonly the user's full name (such as "John Doe").
|}

{{Note|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{{!}}VirtualBox]], you'd need to add your user to the {{c|vboxusers}} group; if running this install as a VirtualBox ''guest'', you'd need to add your user to the {{c|vboxguest}} group. [https://wiki.archlinux.org/index.php/users_and_groups#Software_groups This wiki entry] has a useful list of this type of group (and instructions for how to add and remove users from a group).}}

== <span id="enabling_wayland">Enabling Wayland</span> ==

Next, we'll activate the {{c|wayland}} USE flag globally on your system (we'll rebuild any existing installed packages affected by these changes in the subsequent section). Issue:

{{RootCmd
|nano -w /etc/portage/make.conf
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

and ''append'' the following lines to that file:

{{FileBox|filename=/etc/portage/make.conf|title=Append the following lines, to enable {{c|wayland}}|lang=bash|1=
# Globally enable Wayland; use elogind rather than consolekit;
# support OpenGL for embedded systems.
USE="${USE} wayland"
}}

Leave the rest of the file as-is. Save, and exit {{c|nano}}.

== <span id="install_x11">Installing X11</span> ==

Next, we'll install an X11<ref name="x11_guide">Wikibooks: [https://en.wikibooks.org/wiki/Guide_to_X11 ''Guide to X11'']</ref> server.

{{Note|Although we'll using {{c|wayland}} as our primary graphical platform for GNOME, we need to ensure X11 is working too, because:
* apps not yet ported to use {{c|wayland}} will be hosted in a shared, rootless X11 server (the so-called '[[:Wikipedia:Wayland_(display_server_protocol)#Compatibility_with_X{{!}}XWayland]]' approach), and;
* we also want to allow the use of 'old-school' X11-based GNOME sessions as a fallback.}}

We need to set an additional <var>USE</var> flag for {{Package|media-libs/mesa}} (an OpenGL-like library which X pulls in as a dependency), so issue:

{{RootCmd
|echo -e "# required by standard X-server installation\nmedia-libs/mesa xa" >> /etc/portage/package.use/mesa
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

Here's what those flags do:

{| class="wikitable"
|-
! Package !! Use flag !! Description
|-
| {{Package|media-libs/mesa}} || {{c|xa}} || This enables the XA (X Acceleration) API for [[:Wikipedia:Gallium3D{{!}}Gallium3D]] (a device driver framework for 3D graphics chipsets) (you may also find this [http://www.linuxfromscratch.org/blfs/view/svn/x/mesa.html ''Linux from Scratch'' page] useful).
|}

As [[../Building_the_Gentoo_Base_System_Minus_Kernel#second_virtual_console|before]], since some of the next steps will involve lengthy emerges, we'll use {{c|screen}}, and <span id="another_second_console">setup a second virtual console</span>, which will be let us monitor progress using {{c|showem}}. Issue:
{{RootCmd
|screen
|export PS1{{=}}"(1) $PS1"
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
to start {{c|screen}}. Then, press {{Key|Ctrl}}{{Key|a}} then {{Key|c}} to start a new virtual console, and in that new console enter:
{{RootCmd
|export PS1{{=}}"(2) $PS1"
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
Now hit {{Key|Ctrl}}{{Key|a}} then {{Key|p}} to get back to the original console.

Next, update your existing package set to reflect the changed USE flags. Issue:

{{RootCmd
|emerge --ask --verbose --deep --with-bdeps{{=}}y --changed-use --update @world
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
</pre>
}}
{{Note|See these [[../Building_the_Gentoo_Base_System_Minus_Kernel#update_world{{!}}earlier notes]] for an explanation of the options used in the above command.}}
{{Note|Just as [[../Building_the_Gentoo_Base_System_Minus_Kernel#use_showem{{!}}before]], you can temporarily switch to the second console to watch the progress with {{c|showem}}, if you like. Use {{Key|Ctrl}}{{Key|a}} then {{Key|n}} to switch to the second console, and {{Key|Ctrl}}{{Key|a}} then {{Key|p}} to return back when done.}}

Wait for the update to complete, before continuing. It should not take too long on a modern machine (as we do not have many GUI-specific libraries or apps installed, yet). A few additional {{c|wayland}}-specific libraries will also be pulled in.

Now, since you have already set up the necessary [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable|<var>VIDEO_CARDS</var>]] and [[../Installing_the_Gentoo_Stage_3_Files#input_devices_variable|<var>INPUT_DEVICES</var>]] variables in {{Path|/etc/portage/make.conf}} [[../Installing_the_Gentoo_Stage_3_Files#setup_make_conf|earlier]], we can now proceed to install the X-server itself. Issue:
{{RootCmd
|emerge --ask --verbose --oneshot x11-base/xorg-server
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
</pre>
}}
and the X11 server will be downloaded, compiled and installed. Note that we use <code>--oneshot</code> here to avoid adding it to your [[World set (Portage){{!}}@world]] set (this is slightly cleaner, as it will become a dependency of GNOME, once it is installed later).

{{Tip|<span id{{=}}"virtualbox_hints">If you are installing onto a [[VirtualBox]] client</span> (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 <code>VIDEO_CARDS{{=}}"vesa"</code> when using VirtualBox with EFI emulation turned on.<ref>Red Hat Bugzilla: [https://bugzilla.redhat.com/show_bug.cgi?id{{=}}742695 "EFI install in VirtualBox results in text install "]</ref> You need to use <code>VIDEO_CARDS{{=}}"fbdev virtualbox vmware"</code> instead. Then, for best results, enable {{c|CONFIG_DRM_VMWGFX}} and {{c|CONFIG_DRM_VMWGFX_FBCON}} in the kernel, and opt to use {{c|VMSVGA}} (or, as a fallback, {{c|VboxSVGA}}) as the VirtualBox graphics controller.
* Under EFI boot, you may find it more reliable to use {{c|ALSA Audio Driver}} / {{c|Intel HD Audio}} on your virtual machine (selectable in the VirtualBox control panel, under "Audio").
* It is generally useful to {{c|emerge}} the {{Package|app-emulation/virtualbox-guest-additions}} in your guest (and set it to start on boot, via <code>emerge -v virtualbox-guest-additions && rc-update add virtualbox-guest-additions default</code>), 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 {{c|vboxguest}} group (with <code>gpasswd -a <username> vboxguest</code>).
* To get (standard) {{c|wayland}} support, {{c|CONFIG_DRM}} <u>must</u> be enabled in the kernel, along with {{c|CONFIG_DRM_TTM}}. The simplest way to do this (for a VirtualBox guest) is to enable support for one of the 'normal' graphics card drivers (e.g. {{c|CONFIG_DRM_VMWGFX}} or {{c|CONFIG_DRM_VIRTIO_GPU}}), in the [[#install_drm_driver{{!}}later]] kernel configuration section (this is safe to do, even if the enabled driver won't be directly used (as for e.g., {{c|CONFIG_DRM_VIRTIO_GPU}})).
* To show the graphical {{c|plymouth}} LUKS password splash screen at boot, enable {{c|CONFIG_FB_SIMPLE}} in the kernel.
* The VirtualBox video drivers are notoriously awkward to {{c|emerge}} with parallelism and it is possible they will break your {{Package|x11-base/xorg-server}} build. '''If''' this occurs, just retry as follows (note the explicit citation of {{Package|x11-base/xorg-drivers}}, to ensure that these are correctly built):
{{RootCmd
|MAKEOPTS{{=}}"" emerge --verbose --oneshot x11-base/xorg-drivers x11-base/xorg-server
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>}}}}

== <span id="temp_install_twm">Temporarily Installing an X11 Window Manager and Applications</span> ==

To be <span id="install_x_test_apps">able to test</span> out X11, we'll need to install a [[:Wikipedia:Window_manager|window manager]], and a few X11 applications.

Keeping things simple here, we'll use the (minimalist) [[:Wikipedia:Twm|Tab Window Manager (TWM)]] ({{Package|x11-wm/twm}}), and the following apps:
* {{Package|x11-apps/xsetroot}}: a background ('root') window parameter setting utility for X;
* {{Package|x11-apps/xclock}}: a simple clock display for X; and
* {{Package|x11-terms/xterm}}: the standard terminal emulator for X.

Issue:
{{RootCmd
|emerge --ask --verbose x11-wm/twm x11-terms/xterm x11-apps/xclock x11-apps/xsetroot
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
</pre>
}}
These are small programs, and shouldn't take long to download, compile or install.

== <span id="install_drm_driver">Enabling the Kernel DRM Driver for your Graphics Card</span> ==

Next, since {{c|wayland}} requires you to have an appropriate [[:Wikipedia:Direct_Rendering_Manager|Direct Rendering Manager]] ('DRM') kernel driver for your PC's graphics card installed, in this section we'll reconfigure your kernel accordingly, rebuild it, and then reboot.

{{Note|Technically, you don't ''need'' DRM for {{c|wayland}} itself, since it is e.g., also possible use the standalone {{Package|dev-libs/weston}} compositor to render to an {{c|fbdev}} &mdash; or alternatively to an X11 &mdash; back end. Nevertheless, for most PC use-cases (and for a sane configuration using GNOME's {{c|mutter}} compositor) the DRM route is ''strongly'' recommended, so that's what we'll follow here.<br>What's more, for most modern graphics cards, you'll need a DRM driver for efficient ''X11'' support too, which is why we're going to reconfigure and rebuild the kernel ''now'', before testing either platform.}}

{{Note|Your presently running kernel, the configuration of which was [[../Configuring_and_Building_the_Kernel#kernel_opts_set_by_buildkernel{{!}}based]] upon the Gentoo minimal install image's, does not currently have ''any'' DRM components enabled. We'll fix that problem in this section also.}}

Two commonly used [[:Wikipedia:Direct_Rendering_Manager|DRM]]/[[:Wikipedia:Direct_Rendering_Infrastructure|DRI]] [[:Wikipedia:Direct_Rendering_Manager#Kernel_Mode_Setting|KMS]] drivers are:
* the {{c|DRM_I915}} driver; this is needed for the integrated [[:Wikipedia:Intel_HD_and_Iris_Graphics|"HD Graphics"]] on many [[:Wikipedia:Ultrabook|Ultrabooks]] (such as the Panasonic CF-AX3); you'll need to activate it if you have an "{{c|intel}}", "{{c|intel i915}}" or "{{c|intel i965}}" [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] setting in {{Path|/etc/portage/make.conf}};
*the {{c|DRM_NOUVEAU}} driver; this is an open-source driver that [[:Wikipedia:Nouveau_(software)|supports]] many nVidia graphics cards (which are popular on desktop machines); you'll need to activate it if you have a "{{c|nouveau}}" [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] setting in {{Path|/etc/portage/make.conf}}.

(There are others too, of course, these are simply the most frequently encountered.)

{{Tip|To determine what graphics card you have (if unsure), you may find that issuing (as root):
{{RootCmd
|lspci {{!}} grep -i VGA
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
and
{{RootCmd
|hwinfo --gfxcard
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
provides useful information. Unfortunately, as of the time of writing, there is no reliable program which will query your hardware and generate an appropriate kernel configuration automatically.}}

<span id="make_menuconfig_intro">To kick off the kernel reconfiguration process, first ensure that the USB boot key</span> is inserted into the target machine, and then issue (from the {{c|ssh}}/{{c|screen}} virtual terminal):
{{RootCmd
|buildkernel --menuconfig
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
Because you have not specified <code>--ask</code> here, but you ''have'' specified <code>--menuconfig</code>, the process will run through by itself (assuming no errors) to the point where you can modify the kernel configuration using the standard {{c|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 [[Intel|this wiki page]]). If you require a different driver, modify these instructions accordingly.

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

{{Note|For more information on {{c|menuconfig}}, refer to Chapter 4 of Greg Kroah-Hartman's ''Linux Kernel in a Nutshell''<ref name{{=}}"kernel_in_nutshell">Kroah-Hartman, Greg. [http://www.kroah.com/lkn/ ''Linux Kernel in a Nutshell'' (ebook)]. O'Reilly, 2006</ref>, the Gentoo [[Kernel/Configuration{{!}}wiki page]], and Bruce Dubbs' "Considerations when configuring the Linux kernel" from ''Linux from Scratch''<ref>Dubbs, Bruce. [http://www.linuxfromscratch.org/hints/downloads/files/kernel-configuration.txt "Considerations when configuring the Linux kernel"]. 28 May 2009, Linux from Scratch.</ref>.}}

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

{{Note|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, {{c|menuconfig}} will tell you that your choice is restricted, and why.}}

To search, press {{Key|/}} 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 {{c|i915}} driver, press {{Key|/}} then type in {{c|i915}}, then press {{Key|Enter}} to see the search results:
{|style="background:transparent; color:black" 
|[[File:Menuconfig_2.png|thumb|none|400px|Searching for a Missing Driver...]]
|[[File:Menuconfig_3.png|thumb|none|400px|...And Reviewing the Results]]
|}

{{Note|As mentioned, the following assumes you want to add the Intel {{c|DRM_I915}} driver to your kernel. If your target PC requires a different driver, for example {{c|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 (your results may differ, depending on kernel version), of which the first and third ({{c|DRM_I915}}, and {{c|DRM_I915_USERPTR}}) are relevant;
* The output shows that (e.g.) the {{c|DRM_I915}} item (which will appear in the {{Path|/usr/src/linux/.config}} file as {{c|CONFIG_DRM_I915}}) is to be found under the {{c|Device Drivers}} menu, by following down into the {{c|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 {{c|DRM_I915}} name (it will actually appear as "{{c|Intel 8xx/9xx/G3x/G4x/HD Graphics}}").
* The dependencies of this driver are also shown (you can drag the {{c|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 ({{c|{{=}}y}}, the same as an asterisk) or modularized ({{c|{{=}}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: {{Highlight|an item will often not even appear in {{c|menuconfig}}'s top pane until its dependencies have been satisfied, even when it shows up in the results of a search}}. It would be nice if {{c|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 {{c|DRM_I915}} case as a concrete example. From the search just performed we can see that, of the requirements for {{c|DRM_I915}}, only the {{Highlight|{{c|DRM}}}} item is currently deselected. Well then, let's investigate {{c|DRM}}: we hit {{Key|Enter}} to exit current search, then {{Key|/}} to search again, and type in {{c|DRM}} and press {{Key|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 "{{c|Device Drivers -> Graphics support}}", that its prompt is "{{c|Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)}}", and that it is currently unselected ({{c|[{{=}}n]}}):

[[File:Menuconfig_40a.png|thumb|none|400px|Search Results for DRM (Dependency)]]

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

{{Tip|There's a handy shortcut you can often use when searching in {{c|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 ({{Key|1}}, {{Key|2}}, etc.) to jump ''directly'' to the item in question. Then, once you're done editing it, pressing {{Key|Esc}} then {{Key|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 <code>make menuconfig</code> flow.}}

{{Important|Remember, to use {{c|wayland}}, you '''must''' ensure that {{c|DRM}} is enabled!}}

{{Note|Further to the above, 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 that {{c|DRM_TTM}} must be enabled in the kernel, in order to use the {{c|vboxvideo}} out-of-tree kernel module. As it happens, selecting {{c|DRM_I915}} ''isn't'' sufficient to select this &mdash; to do so, you'll need to select a different dummy 'real' driver (I recommend modularizing {{c|CONFIG_DRM_VIRTIO_GPU}} for this purpose).}}

{{Note|There's no harm (other than increased kernel size) in selecting multiple DRM drivers, if you are unsure about which to use. Indeed, you may need to do so, if you have more than one type of graphics card in your system.}}

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

{|style="background:transparent; color:black" 
|[[File:Menuconfig_4.png|thumb|none|400px|Select Device Drivers Menu...]]
|[[File:Menuconfig_5.png|thumb|none|400px|...Then Graphics support Submenu]]
|}

{{Tip|If you are unsure of an item, you can press {{Key|?}} when it is highlighted; this will show its help information, including symbol name.

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

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

Now, move to the "{{c|Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)}}" item. This is the {{c|DRM}} symbol we want (as just mentioned, you can verify using {{Key|?}} if you like). Press {{Key|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 {{c|--->}} suffix that appears post-selection):

[[File:Menuconfig_300.png|thumb|none|400px|Selecting Direct Rendering Manager (XFree86 ...)...]]

{{Note|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. {{c|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).}}

{{Tip|Further to the above, for certain video cards which require a runtime firmware upload (such as more modern [[AMDGPU|AMD/ATI Radeon]] units using the "{{c|amdgpu radeonsi}}" [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] flags), it is actually ''preferable'' to specify the necessary kernel drivers as ''modules'' (rather than building them in). This avoids having to [[AMDGPU#Incorporating_firmware|explicitly compile firmware into the kernel]] ({{c|buildkernel}} copies all modules and firmware into the initramfs anyway, so this is safe to do).}}

{{Tip|If you have a Intel-CPU-based laptop that is badged as having a Radeon GPU (as does, for example, the Dell Inspiron 5567 15), you may find you need to proceed ''as if'' you had a system with standard integrated [[:Wikipedia:Intel_HD_and_Iris_Graphics|"Intel HD Graphics"]]; i.e., specifying "{{c|intel i965}}" for [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] in {{Path|/etc/portage/make.conf}} (then [[#update_vc_rebuild_world|rebuilding]] {{c|@world}} if necessary), turning on {{c|CONFIG_DRM_I915}} in your kernel etc.}}

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

{|style="background:transparent; color:black" 
|[[File:Menuconfig_302.png|thumb|none|400px|Causes Further Menu Items to Appear...]]
|[[File:Menuconfig_303.png|thumb|none|400px|...Such as the Intel i915 Driver]]
|}

You can verify that this is indeed the {{c|DRM_I915}} item, by using {{Key|?}} if you like; then, press {{Key|y}} to enable it:
{|style="background:transparent; color:black" 
|[[File:Menuconfig_304.png|thumb|none|400px|Finally, Select HD Graphics Driver (DRM_I915)]]
|}

And that's it, you're done. Hit {{Key|Esc}} then {{Key|Esc}} to come back out to the "{{c|Device Drivers}}" menu. Hit {{Key|Esc}} then {{Key|Esc}} again to come back out to the top-level menu. Finally, hit {{Key|Esc}} then {{Key|Esc}} again, to exit the program. When prompted, ensure {{c|<Yes>}} is selected, and press {{Key|Enter}} to save the new configuration and quit {{c|menuconfig}}:
[[File:Menuconfig_17.png|thumb|none|400px|Saving New Configuration and Exiting]]

Once you have exited {{c|menuconfig}}, {{c|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 "{{c|All done!}}"). Then issue:

{{RootCmd
|exit
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
which will close the first {{c|screen}} terminal, then:

{{RootCmd
|exit
|prompt=<span style{{=}}"color:gray;">(2)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
to close the second one. Then, ensure the boot USB key is still inserted in the target machine and restart it, by issuing:
{{RootCmd
|reboot
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|If you have problems rebooting with this new kernel, you can follow the instructions [[../Completing_OpenRC_Configuration_and_Installing_Necessary_Tools#revert_to_previous_kernel{{!}}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.}}
{{Note|<span id{{=}}"kernel_config_shorthand_note">It's useful to</span> 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{{!}}"intel"]] page on the wiki, we read that you need to enable the following kernel options:

{{KernelBox|title=linux-4.4|1=
        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 {{c|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 [[Kernel/Gentoo_Kernel_Configuration_Guide#Kernel_configuration_shorthand_notation{{!}}Gentoo wiki]].

In the later part of this tutorial, I will assume that you are able to translate these 'shorthand' kernel configuration recipes, using <code>buildkernel --menuconfig</code>, 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 [[../Final_Configuration_Steps_under_OpenRC#resume_after_menuconfig_tutorial{{!}}click here]] to return - otherwise, just continue reading!)
}}

When the machine restarts, as before, you will need to enter your LUKS keyfile {{c|gpg}} passphrase (the one you created [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#create_gpg_luks_keyfile|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 {{c|ssh}}:

{{Cmd
|ssh root@192.168.1.106
|prompt=user@pc2 $
|output=<pre>
Password: <enter root password>
... additional output suppressed ...
</pre>}}
{{Note|Substitute whatever IP address you got back from {{c|ifconfig}} [[../Completing_OpenRC_Configuration_and_Installing_Necessary_Tools#post_reboot_ip{{!}}earlier]] for <code>192.168.1.106</code> 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 {{c|ifconfig}} to find out the new address, then issue the above {{c|ssh}} command citing that address. As before, in such a case you may need to clean out any previous record of {{c|ssh}} connections to (other machines at) that new address (since the fingerprints will not match), using:
{{Cmd
|sed -i '/^[^[:digit:]]*192.168.1.106[^[:digit:]]/d' ~/.ssh/known_hosts
|prompt=user@pc2 $}}
obviously substituting the new address for <code>192.168.1.106</code> in the above. Then, be sure to check the fingerprint when prompted (by the subsequent {{c|ssh}} command), against those you noted down [[../Completing_OpenRC_Configuration_and_Installing_Necessary_Tools#note_new_fingerprints{{!}}earlier]].
}}
{{Note|If installing over WiFi, and you had to manually restart {{c|wpa_supplicant}} in the [[../Configuring_systemd_and_Installing_Necessary_Tools#manually_start_wpa_supplicant_systemd{{!}}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 {{c|ssh}} in.}}

Then, re-establish {{c|screen}} (enter all commands via the {{c|ssh}} console from the helper PC, unless otherwise stated). Issue:
{{RootCmd
|screen
|export PS1{{=}}"(1) $PS1"
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
to start {{c|screen}}. Then, press {{Key|Ctrl}}{{Key|a}} then {{Key|c}} to start a new virtual console, and in that new console enter:
{{RootCmd
|export PS1{{=}}"(2) $PS1"
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
Now hit {{Key|Ctrl}}{{Key|a}} then {{Key|p}} to get back to the original console.

== <span id="additional_wayland_qualification">Verifying the DRM Driver Is Activated</span> ==

Next, we'll check that your system now has an active DRM graphics driver (and not just e.g., a fallback {{c|fbdev}} framebuffer), as this is a prerequisite for running GNOME 3 over ''{{c|wayland}}''. Issue:

{{RootCmd
|hwinfo --gfxcard {{!}} grep "Driver:"
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
Driver: "i915"
</pre>
}}
The output ''you'' get will obviously depend upon your graphics card, for example, it might be <code>Driver: nouveau</code> instead, if you have an nVidia card.

{{Note|Remember, too, that this is the ''kernel'' driver name: it is not necessarily the same as the value(s) you need to set in the [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] variable via {{Path|/etc/portage/make.conf}} (which in turn controls e.g., some of the USE flags on {{Package|media-libs/mesa}}, thereby configuring its ''userland'' driver set).<br>For example, with a modern HD-graphics based PC, you'd probably have {{c|CONFIG_DRM_I915}} set in the kernel (as per our worked example), <code>hwinfo --gfxcard</code> would report <code>i915</code> as the active driver, yet you would have <code>VIDEO_CARDS{{=}}"intel i965"</code> set in {{Path|/etc/portage/make.conf}} (building {{c|mesa}} with the <code>video_cards_intel</code> and <code>video_cards_i965</code> <var>USE</var> flags thereby).}}

Next, search for messages from the DRM subsystem citing this driver name, in the kernel ring buffer. Issue:

{{RootCmd
|grep --ignore-case "i915" <(dmesg) {{!}} grep --fixed-strings '[drm]' 
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
[    0.371760] [drm] Initialized i915 1.6.0 20170818 for 0000:00:02.0 on minor 0
</pre>
}}
{{Note|Substitute the driver name you received from the <code>hwinfo --gfxcard</code> invocation for {{c|i195}} in the above command.}}

Again, the output you see will differ, but the important thing to verify is that that your DRM driver has been {{Highlight|initialized}}.
{{Note|If you have multiple graphics cards in your PC, and you want to use all of them under {{c|wayland}}, make sure a DRM driver has been successfully initialized for each one.}}

If, you see ''no'' matching <code>[drm]</code> message output from the {{c|grep}} (or if the earlier <code>hwinfo --gfxcard</code> produced an error), then you have ''not'' installed the correct driver. In this case, you need to go back to the [[#install_drm_driver|start of the previous section]] now, and try again.

However, assuming it ''did'' work (the more usual case), as a final sanity-check, list the activated {{c|DRM_}} components present in the configuration of your running kernel. Issue:

{{RootCmd
|zgrep 'CONFIG_DRM.*{{=}}' /proc/config.gz
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
CONFIG_DRM=y
CONFIG_DRM_MIPI_DSI=y
CONFIG_DRM_KMS_HELPER=y
CONFIG_DRM_KMS_FB_HELPER=y
CONFIG_DRM_FBDEV_EMULATION=y
CONFIG_DRM_I915=y
CONFIG_DRM_I915_USERPTR=y
CONFIG_DRM_PANEL=y
CONFIG_DRM_BRIDGE=y
</pre>
}}

{{Tip|If the above command returns an error, you may need to run (as root) <code>modprobe configs</code> first, in order to make the kernel configuration file visible within the special {{Path|/proc}} filesystem.<ref name{{=}}"modrobe_configs">SuperUser Forum: [https://superuser.com/a/1011993 "Obtain Kernel Config from Currently Running Linux System?"]</ref><br> For avoidance of doubt, most users should ''not'' need to do this, however.}}

Your output may well differ, depending on the configuration choices made [[#install_drm_driver|earlier]], but check that {{c|CONFIG_DRM}} and at least one specific driver (here {{c|CONFIG_DRM_I915}}, but yours might be {{c|CONFIG_DRM_NOUVEAU}}, etc.) are either built-in (shown as {{c|{{=}}y}}) or modularized (shown as {{c|{{=}}m}}).

{{Note|Users installing onto a VirtualBox target (and this ''won't'' apply to most readers, who will instead be installing onto a 'real' PC) will be looking for {{c|CONFIG_DRM_VMWGFX}} or {{c|CONFIG_DRM_VIRTIO_GPU}} here (which we suggested including [[#virtualbox_hints|above]]).}}

If that ''isn't'' the case, jump back to the [[#install_drm_driver|Enabling the Kernel DRM Driver for your Graphics Card]] section now, install an appropriate DRM driver, and try again.

However, if (as is likely) everything checked out fine, then keep reading!

== <span id="testing_x11">Testing X11</span> ==

Before we can try out X11, we need to instruct it which window manager to use, and what apps to launch, when starting up. The {{c|~/.xinitrc}} file is used for this purpose. As it's generally not a great idea to run an X server as root, we'll create this in the home directory of the regular user [[#add_regular_user|we've just created]] (and then invoke X as that user). Still via {{c|ssh}}/{{c|screen}} console, issue:
{{RootCmd
|su --login sakaki
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|Substitute the user name of the regular user you created in the [[#add_regular_user{{!}}earlier step]] for {{c|sakaki}} in the above command.}}

{{Note|The {{c|su}} command, when invoked with <code>--login</code> (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 ({{c|root}}), as here, no password is required.}}

<span id="setup_xinitrc">Next, edit the {{c|.xinitrc}} file</span> in the regular user's home directory. Issue:
{{Cmd
|nano -w ~/.xinitrc
|prompt=sakaki@koneko <span style{{=}}"color:royalblue;">~ $</span>
}}
{{Note|Obviously, the name that you see in the prompt will reflect that of the regular user you added (and which you just {{c|su}}-d to).}}
Put the following text in the {{c|.xinitrc}} (replacing the current contents, if any):
{{FileBox|filename=~/.xinitrc|title=A basic setup to start TWM and some simple applications|lang=bash|1=
#!/bin/sh
LANG=C 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 {{c|nano}}. 

The above shell script simply instructs X to:
* start the Tab Window Manager ({{c|twm}}) as a [[:Wikipedia:Background_process|background process]];
* set the background [[:Wikipedia:X11_color_names#Color_name_charts|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 ([[:Wikipedia:Exec_(computing)|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 finally ready to try out X11!</span>

{{Note|<span id{{=}}"update_vc_rebuild_world">Remember,</span> if you decided to ''change'' your [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] setting (''wrt'' that which you originally entered when [[../Installing_the_Gentoo_Stage_3_Files#setup_make_conf|setting up]] {{Path|/etc/portage/make.conf}}), then you will need to issue:
{{RootCmd
|emerge --verbose --deep --with-bdeps{{=}}y --changed-use --update @world
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
to reflect this (in e.g. {{Package|media-libs/mesa}}) before trying to {{c|startx}}.
}}

Still on the {{c|ssh}}/{{c|screen}} console, issue:

{{Cmd
|startx
|prompt=sakaki@koneko <span style{{=}}"color:royalblue;">~ $</span>
}}

If all goes well, the screen of your target PC should now be displaying something like the below:
[[File:Twm_screen.png|thumb|none|400px|Simple X11/TWM Desktop and Applications]]
(The actual layout will depend upon the geometry of your display.)

{{Tip|<span id{{=}}"xrandr_fix">If your screen appears ''rotated''</span> (perhaps because you are using a monitor in portrait, rather than landscape, orientation), then you can fix this using the {{c|xrandr}} utility. Although this is not critical to install at this stage &mdash; since we'll be replacing X with GNOME over Wayland shortly &mdash; you can do so if you wish. To do do, issue (as root):{{RootCmd
|emerge --verbose x11-apps/xrandr
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
}}Once this has been installed, you can then add add the following line to your {{Path|.xinitrc}}, after the <code>start twm&</code> line:
{{FileBox|filename=~/.xinitrc|title=Example monitor rotation fix (add after twm &) |lang=bash|1=
xrandr --rotate right
}}Leave the rest of the file as-is, and try <code>startx</code> again (other rotations are available besides <code>right</code>, please see the {{c|xrandr}} manpage).<br>For avoidance of doubt, most users will ''not'' be affected by this issue, and can safely ignore the contents of this tip.
}}

If you get an error instead, remember that {{Highlight|the most likely problem preventing X11 from starting up, is a missing kernel graphics driver}}. As such, simply go back to the previous [[#install_drm_driver|section]], and add the appropriate (DRM) driver now &mdash; it may be that you simply chose the wrong one the first time around. For avoidance of doubt, there's no harm (other than the impact on kernel size!) in enabling more than one such DRM driver, if you're not exactly sure which is correct.

{{Note|<span id{{=}}"update_vc_rebuild_world_2">Remember,</span> if you add or change kernel DRM drivers, you'll also need to modify (or simply augment) your [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] variable to match (in {{Path|/etc/portage/make.conf}}). Once done, you will then need to issue:
{{RootCmd
|emerge --verbose --deep --with-bdeps{{=}}y --changed-use --update @world
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
so that affected packages (such as e.g., {{Package|media-libs/mesa}}) are rebuilt to reflect this change, before trying to {{c|startx}} again. 
}}

{{Important|<span id{{=}}"may_need_suid_xorg">If you get a permissions error</span> trying to run {{c|startx}} as a regular user (following the instructions in the main body of the text above), try setting the SUID bit<ref name="suid_bit">Anne, Surendra. [https://www.linuxnix.com/suid-set-suid-linuxunix/ "What is SUID and how to set SUID in Linux/Unix?"]</ref> on {{Path|/usr/libexec/Xorg}},<ref name="xorg_suid_bit">Xorg Foundation Miscellaneous FAQ. [https://www.x.org/wiki/FAQMiscellaneous/#index2h2 "How do I set the correct permissions of my Xserver binary?"]</ref> by issuing:
{{RootCmd
|chmod u+s /usr/libexec/Xorg
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
Then, log in as your regular user ''directly'' at the target machine's keyboard (not over {{c|ssh}}, and not using {{c|su}}), and try issuing the {{c|startx}} from there. For avoidance of doubt, at the time of writing doing this was ''not'' necessary under {{c|OpenRC}}, but was under {{c|systemd}}, so I note the point here for reference.}}

{{Tip|This ''won't'' be necessary for most users but, if after having run through the [[#install_drm_driver{{!}}kernel configuration]]/rebuild/reboot and [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] settings loop a few times, you ''still'' can't get X11 to start up, have a look at the Gentoo wiki page on [[Xorg/Guide{{!}}X11 configuration]], which contains some useful pointers. You may also find the content of the {{Path|/var/log/Xorg.0.log}} log file helpful, when trying to determine in more detail what went wrong. ''Double check'' that you haven't introduced any obvious syntax errors in [[#setup_xinitrc{{!}}your {{Path|~/.xinitrc}} file]] as well.<br>To reiterate however: with a modern X setup, problems are almost always as a result of missing [[#install_drm_driver|kernel graphics drivers]] (or possibly incorrect [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] or [[../Installing_the_Gentoo_Stage_3_Files#input_devices_variable{{!}}<var>INPUT_DEVICES</var>]] variables in {{Path|/etc/portage/make.conf}}), rather than an erroneous X configuration per se.}}

Assuming you ''can'' see the simple desktop displayed, next check that you can move the cursor around (using the target machine's mouse or touchpad), and try typing some simple commands (e.g. "<code>ls /bin</code>") 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):
{{Cmd
|exit
|prompt=sakaki@koneko <span style{{=}}"color:royalblue;">~ $</span>
}}
On the {{c|ssh}}/{{c|screen}} console (at your helper PC), you should now see that the {{c|startx}} program has exited (and a lot of status output will have been written to the console too).
{{Note|If you have problems, the X server can always be closed from the {{c|ssh}} window, by typing {{Key|Ctrl}}{{Key|c}}.}}

If everything has checked out so far, then congratulations, GNOME 3 should be able to work fine over both X11 and Wayland on your system.

== <span id="install_gnome3">Installing GNOME 3</span> ==

The validation of prerequisites behind us, we will next perform some clean up, then proceed to the GNOME installation itself.

Let's begin by removing the temporary X window manager and applications (which we installed, for testing purposes only, [[#install_x_test_apps|earlier]]).

Issue (from the helper PC {{c|ssh}}/{{c|screen}} terminal):
{{Cmd
|exit
|prompt=sakaki@koneko <span style{{=}}"color:royalblue;">~ $</span>
}}
to get back to the {{c|root}} user, then:
{{RootCmd
|emerge --ask --verbose --depclean x11-wm/twm x11-terms/xterm x11-apps/xclock x11-apps/xsetroot
|output=<pre>
... additional output suppressed ...
Would you like to unmerge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
</pre>
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

{{Note|Using the <code>--depclean</code> option to {{c|emerge}} in this way is a common idiom to safely uninstall packages in Gentoo. If any of the specified [[../Installing_the_Gentoo_Stage_3_Files#atoms_etc{{!}}atoms]] happens to be a dependency of another (uncited) installed package (even transitively), it will not be removed.}}

<span id="tracker_disable">Next, decide whether you wish to disable</span> GNOME's "[[:Wikipedia:Tracker_(search_software)|{{c|tracker}}]]" file and search indexing framework (it is enabled in GNOME by default). Two reasons you may wish to do so are:
# it runs content-based indexing on your filesystem, which can create high CPU loading for densely-populated media;<ref name="tracker_cpu">Yao, M. [https://www.soimort.org/notes/171103/ "Go Away, {{c|tracker-store}}"]</ref><ref name="disable_tracker_how">Fedora Project Forum: [https://ask.fedoraproject.org/en/question/9822/how-do-i-disable-tracker-in-gnome/ "How Do I Disable Tracker in GNOME?"]</ref> and
# there is a self-evident privacy (and attack surface) issue presented by using such software.

{{Note|If {{c|tracker}} is disabled, the packages {{Package|gnome-extra/gnome-documents}}, {{Package|media-gfx/gnome-photos}} and {{Package|media-sound/gnome-music}} (which rely upon it) will ''not'' be installed as part of GNOME.}}

{{Note|With modern GNOME, even if you disable the {{c|tracker}} USE flag, it will still be installed as it is a hard dependency of {{Package|gnome-base/nautilus}}, the default file manager for the GNOME desktop. The further measure required to stop it running at all (should you elect) will be described [[#tracker_fully_off{{!}}later in the chapter]].}}

If you decide you'd rather retain {{c|tracker}}, click [[#ready_to_install_gnome|here]] to skip the following optional step.

Otherwise, to disable it, issue:
{{RootCmd
|nano -w /etc/portage/make.conf
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

and then ''append'' the following lines to that file:
{{FileBox|filename=/etc/portage/make.conf|title=Append lines to disable GNOME's tracker infrastructure|lang=bash|1=
# Globally disable GNOME's tracker software.
USE="${USE} -tracker"
}}

Leave the rest of the file as-is. Save, and exit {{c|nano}}.

{{Note|As the {{c|tracker}} USE flag is used by a number of applications, we set it globally here, rather than in {{Path|/etc/portage/package.use/gnome-extra-apps}}.}}

<span id="ready_to_install_gnome">Now we are ready</span> to install GNOME!

{{Note|It is '''not unusual''' for the following large {{c|emerge}} to '''fail to complete on the first attempt''', given the degree of build parallelism we are using. We will provide a strategy to address any build failures, however, so don't be concerned.}}
Issue:
{{RootCmd
|emerge --ask --verbose --keep-going gnome-base/gnome && echo "GNOME emerged OK" {{!}}{{!}} echo "GNOME emerge not yet completed"
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
</pre>
}}

{{Tip|If, when attempting the {{c|emerge}}, you are prompted with a series of missing package-specific keywords, USE flags, licences, or masks, followed by the question:
{{GenericCmd|
<pre>
... additional output suppressed ...
Would you like to add these changes to your config files? [Yes/No]
</pre>
}} you can answer {{Key|y}} and {{Key|Enter}}; this will append the proposed changes into (one or more of) the files {{Path|/etc/portage/package.{accept_keywords,license,unmask,use}/zzz_via_autounmask}} (as appropriate). You can then run {{c|dispatch-conf}} to review the changes. Press {{Key|u}} ("use new") to accept the changes for each modified file, if happy. Then try the {{c|emerge}} again. (For more detailed instructions on using {{c|dispatch-conf}}, see [[../Building_the_Gentoo_Base_System_Minus_Kernel#using_dispatch_conf{{!}}these notes]] earlier in the tutorial.)
}}
{{Note|
As [[../Building_the_Gentoo_Base_System_Minus_Kernel#use_showem{{!}}before]], you can switch to the second {{c|screen}} console we prepared [[#another_second_console{{!}}earlier]], to watch the progress (as the files download, build etc.). Hit {{Key|Ctrl}}{{Key|a}} then {{Key|n}} to switch to the second console (you can do this while the {{c|emerge}} is running), and issue:
{{RootCmd
|showem
|prompt=<span style{{=}}"color:gray;">(2)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

You can now switch back and forward between the two windows as you like (using {{Key|Ctrl}}{{Key|a}} then {{Key|n}} to cycle forwards, and {{Key|Ctrl}}{{Key|a}} then {{Key|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 {{c|showem}} program at any time by issuing {{Key|Ctrl}}{{Key|c}}.
}}

The {{c|emerge}} will take quite some time to complete! Note that the <code>--keep-going</code> option instructs {{c|emerge}} to build as much as possible, even if some errors are encountered. This is a useful approach in general with large builds (it can be omitted during the subsequent 'clean up' {{c|emerge}} runs, should any be necessary, as we shall see).

If the above {{c|emerge}} concluded with the output <code>GNOME emerged OK</code> then congratulations, you have successfully installed GNOME, and should now [[#gnome_built_ok|click here]] to skip to the next step.

If however, it concluded with <code>GNOME emerge not yet completed</code>, most likely accompanied by a message near the end of the output that:
{{GenericCmd|
... additional output suppressed ...
 <span style{{=}}"color:red;">*</span> The following <n> packages have failed to build, install, or execute postinst:
... additional output suppressed ...
}}
(or similar) then you have encountered a build issue, so read on.

Most often, any failures will be caused by the high level of {{c|make}} parallelism we are using. These glitches are often non-deterministic in nature and accordingly, as a first step it is worth simply retrying the build. Issue :
{{RootCmd
|emerge --ask --verbose gnome-base/gnome && echo "GNOME emerged OK" {{!}}{{!}} echo "GNOME emerge not yet completed"
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
</pre>
}}
For avoidance of doubt, any package dependencies that did build successfully first time will ''not'' be unnecessarily rebuilt by the above command.

'''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 ^-^

If, after working through this process, you are finally rewarded with the output <code>GNOME emerged OK</code> then congratulations, you have successfully installed GNOME &mdash; [[#gnome_built_ok|click here]] to skip to the next step.

If, on the other hand, you find yourself 'stuck' with one or more packages that seem to fail every time (and the build finishes by outputting <code>GNOME emerge not yet completed</code>), reissue the {{c|emerge}}, but this time ''without'' {{c|make}} parallelism:
{{RootCmd
|MAKEOPTS{{=}}"-j1" EMERGE_DEFAULT_OPTS{{=}}"--jobs{{=}}1" emerge --ask --verbose gnome-base/gnome && echo "GNOME emerged OK" {{!}}{{!}} echo "GNOME emerge not yet completed"
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
</pre>
}}
Again, you may need to repeat this step multiple times (and should do so as long as the 'packages to be installed' count keeps falling).

{{Note|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 the restricted parallelism {{c|emerge}} finishes with the output <code>GNOME emerged OK</code> then congratulations, you have successfully installed GNOME &mdash; [[#gnome_built_ok|click here]] to skip to the next step.

However, if, after all this, you ''still'' experience build errors emerging {{Package|gnome-base/gnome}} (the restricted parallelism {{c|emerge}} finishes by outputting <code>GNOME emerge not yet completed</code>), you may find it useful to refer to [[../Building_the_Gentoo_Base_System_Minus_Kernel#troubleshooting_failed_build{{!}}these earlier notes]]. It is also possible to {{c|emerge}} the smaller package {{Package|gnome-base/gnome-light}} (instead of {{Package|gnome-base/gnome}}), and then add applications later. You can also post a question to Leio's "official", sticky [https://forums.gentoo.org/viewtopic-t-1094796.html support thread] on the Gentoo forums, if you like. Take the necessary steps and then rejoin the tutorial here when ready: in what follows, I am going to assume that you '''have''' successfully installed GNOME.

<span id="gnome_built_ok">Once the build process has completed successfully,</span> ensure you are back in the virtual terminal from where you issued the {{c|emerge}} command (i.e., not the {{c|showem}} virtual terminal / console), and then issue the following to ensure your environment is up-to-date post-install:
{{RootCmd
|env-update && source /etc/profile && export PS1{{=}}"(1) $PS1"
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
Hit {{Key|Ctrl}}{{Key|a}} then {{Key|n}} to go to the second {{c|screen}} console, and do the same there. Issue:
{{RootCmd
|source /etc/profile && export PS1{{=}}"(2) $PS1"
|prompt=<span style{{=}}"color:gray;">(2)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
Then press {{Key|Ctrl}}{{Key|a}} then {{Key|p}} to switch back to the original console again.

You should also ensure that the {{Package|sys-auth/elogind}} daemon (which mimics the {{c|systemd}} project's {{c|logind}}) is added to the appropriate runlevel (and is also started now, if not already running). To do so, issue:
{{RootCmd
|pkill elogind
|rc-update add elogind boot
|openrc
|prompt=<span style{{=}}"color:gray;">(2)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

Make sure any regular users are members of the {{c|plugdev}} group (if it exists on your target machine; it now should). Issue:
{{RootCmd
|getent group plugdev && gpasswd -a sakaki plugdev 
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|Substitute the user name of the regular user you created in the [[#add_regular_user{{!}}earlier step]] for {{c|sakaki}} in the above command. If you add other regular users, be sure to add them to {{c|plugdev}} in a similar manner. This is to allow full access to {{c|NetworkManager}} services, which require the {{c|plugdev}} group.<ref>Gentoo Wiki: [[NetworkManager#Configuration{{!}}"NetworkManager": Configuration]]</ref>}}
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):
{{RootCmd
|getent group games && gpasswd -a sakaki games 
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|Again, substitute the user name of the regular user you created in the [[#add_regular_user{{!}}earlier step]] for {{c|sakaki}} in the above command.}}

Next, we need to log back in as our regular user, and try out our new desktop! Issue:
{{RootCmd
|su --login sakaki
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|Substitute the user name of the regular user you created in the [[#add_regular_user{{!}}earlier step]] for {{c|sakaki}} in the above command.}}

Next, edit the {{c|.xinitrc}} file in the regular user's home directory. Issue:
{{Cmd
|nano -w ~/.xinitrc
|prompt=sakaki@koneko <span style{{=}}"color:royalblue;">~ $</span>
}}
{{Note|Obviously, as before, the name that you see in the prompt will reflect that of the regular user you added (and which you just {{c|su}}-d to).}}

'''Delete''' the current contents of {{c|.xinitrc}} (you can use {{Key|Ctrl}}{{Key|k}} inside {{c|nano}} to delete a line at a time), and '''replace''' with the following text:
{{FileBox|filename=~/.xinitrc|title=Replace existing text with the below to start GNOME|lang=bash|1=
export XDG_MENU_PREFIX=gnome-
exec gnome-session
}}
Save and exit {{c|nano}}.
{{Note|Don't forget the hyphen at the end of {{c|gnome-}} (as shown above). Also, note that there is no need to start the file with a [[:Wikipedia:Shebang_(Unix){{!}}shebang]] this time.}}

OK, time to try it out! To begin with, we'll start GNOME running under X11, with no login manager. Issue:
{{Cmd
|startx
|prompt=sakaki@koneko <span style{{=}}"color:royalblue;">~ $</span>
}}

And hopefully you should be greeted with a (rather startlingly empty!) GNOME 3 desktop, somewhat similar to the below, on the target machine:
[[File:Gnome_first_run.jpg|thumb|none|400px|GNOME Shell Basic Desktop (via startx)]]

{{Note|Depending on your GNOME version, you ''might'' be prompted to enter the administrator password as part of the desktop start-up process (to e.g., allow creation of a colour profile). If so, simply enter the root password when prompted, and press {{Key|Enter}}. (The root password required here is the one you set up [[../Final_Preparations_and_Reboot_into_EFI#setup_new_root_password{{!}}earlier]] in the tutorial (and have used when {{c|ssh}}-ing in)).
}}

{{Important|As noted [[#may_need_suid_xorg{{!}}previously]], ''if'' you get a permissions error trying to run {{c|startx}} as a regular user (following the instructions in the main body of the text above), try setting (if you have not already) the SUID bit<ref name="suid_bit"/> on {{Path|/usr/libexec/Xorg}},<ref name="xorg_suid_bit"/> by issuing:
{{RootCmd
|chmod u+s /usr/libexec/Xorg
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
Then, log in as your regular user ''directly'' at the target machine's keyboard (not over {{c|ssh}}, and not using {{c|su}}), and try issuing the {{c|startx}} from there. For avoidance of doubt, at the time of writing doing this was ''not'' necessary under {{c|OpenRC}}, but was under {{c|systemd}}, so I note the point here for reference.}}

{{Note|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 {{Key|Ctrl}}{{Key|c}} at the helper PC {{c|ssh}}/{{c|screen}} terminal) and then running {{c|startx}} again.}}

You can try playing around with it briefly if you like (some simple instructions may be found [https://wiki.gnome.org/Projects/GnomeShell/CheatSheet 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 {{Key|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.

{{Tip|<span id{{=}}"set_gnome_display">If your screen appears</span> ''rotated'' when logged in under GNOME under {{c|wayland}}, you don't use {{c|xrandr}} to fix it (as described [[#xrandr_fix|earlier]]), instead press the {{Key|Windows Key}}, then type <code>displays</code> and press {{Key|Enter}}. You should then be able to choose an orientation for your primary display.}}

When you're done, kill the test instance, by issuing {{Key|Ctrl}}{{Key|c}} at the helper PC {{c|ssh}}/{{c|screen}} terminal (the one where you just issued {{c|startx}}).

== <span id="testing_gnome3">Testing GNOME 3 on Wayland (and Refining Settings)</span> ==

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 {{c|root}} again:

{{Cmd
|exit
|prompt=sakaki@koneko <span style{{=}}"color:royalblue;">~ $</span>
}}

Next, we must enable the [[:Wikipedia:NetworkManager|{{c|NetworkManager}}]] service (which will handle all network interaction under GNOME), and disable the {{c|dhcpcd}} service, which we started [[../Final_Preparations_and_Reboot_into_EFI#setup_dhcpcd_openrc|earlier]] (and whose functionality {{c|NetworkManager}} supplants). First, issue:
{{RootCmd
|rc-update del dhcpcd default
|/etc/init.d/dhcpcd stop
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

Next, if you are using '''WiFi''' for the install, you'll also have explicitly set up a {{c|wpa_supplicant}} configuration file [[../Final_Preparations_and_Reboot_into_EFI#start_wpa_supplicant|earlier in the tutorial]], and so you need to remove this again now (however, [[#start_nm|'''skip''' this step]] if installing over a '''wired Ethernet''' connection):
{{RootCmd
|mv -v /etc/wpa_supplicant/wpa_supplicant.conf /etc/wpa.conf
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

<span id="start_nm">Now we can ensure {{c|NetworkManager}}</span> comes up on boot (however, do not start it yet, since you may lose network connectivity when you do). Issue:
{{RootCmd
|rc-update add NetworkManager default
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

That having being done, we need to edit the <code>DISPLAYMANAGER</code> value in the {{Path|/etc/conf.d/xdm}} file, so that the [[:Wikipedia:GNOME_Display_Manager|GNOME Display Manager]] ({{c|gdm}}) is used. Issue:
{{RootCmd
|nano -w /etc/conf.d/xdm
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
and edit the <code>DISPLAYMANAGER</code> stanza, so that it reads:
{{FileBox|filename=/etc/conf.d/xdm|title=Specify the GNOME display manager, as follows|1=
# What display manager do you use ?  [ xdm {{!}} gdm {{!}} kdm {{!}} gpe {{!}} entrance ]
# NOTE: If this is set in /etc/rc.conf, that setting will override this one.
DISPLAYMANAGER="gdm"
}}
Leave the rest of the file as is. Save, and exit {{c|nano}}.

Now we configure {{c|xdm}} to run on boot, and also start up an instance now (the {{c|rc}} invocation will also bring up {{c|NetworkManager}}). Issue:
{{RootCmd
|rc-update add xdm default
|openrc
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}

Assuming that worked, <span id="login_to_gnome">you should now</span> be able to see a GNOME login screen on the target machine, similar to the below:
[[File:Gnome_login_OpenRC.jpg|thumb|none|400px|GNOME 3 Login Screen]]

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

{{Tip|If you modified your display settings when logged into GNOME [[#set_gnome_display|earlier]], for example to rotate the display orientation, then you can force these settings to be used by {{c|gdm}} also. To do so, simply copy the file {{Path|/home/<username>/.config/monitors.xml}} into the directory {{Path|/var/lib/gdm/.config/}}, and restart {{c|gdm}} (obviously, substitute <code><username></code> for your regular user here &mdash; it would be <code>sakaki</code> for our example system).<br>For avoidance of doubt, most users will ''not'' need to resort to this, as their {{c|gdm}} setup will be correct 'out of the box'.}}

Next, directly at the target machine, click on the (regular) user name tile, then click on the 'cogwheel' icon, and select {{Key|GNOME}} from the drop-down menu, as shown:
[[File:Gnome_login_wayland.jpg|thumb|none|400px|Using a Wayland Session with GNOME]]

{{Tip|<span id{{=}}"x11_gnome_session">If you wish to use GNOME on X11</span> for a particular session (perhaps because you need to use an application that doesn't yet work properly under {{c|wayland}} (even with [[:Wikipedia:Wayland_(display_server_protocol)#Compatibility_with_X{{!}}XWayland]] compatibility)), then simply choose {{Key|GNOME on Xorg}} from the drop-down menu here (NB: this '''isn't''' something you should do at this stage in the install, it is just presented here for future reference).<br>For avoidance of doubt, the {{Key|XSession}} menu item is ''not'' the correct entry to choose to run GNOME under X11 (as, ''inter alia'', it requires a separate program, {{Package|x11-apps/xsm}}, which we do not have installed).}}

Next, type in the (regular user) password you set up [[#setup_regular_user|earlier]], and click {{Key|Sign In}} (or just press {{Key|Enter}}).
{{Note|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 [[#gnome_keyboard_settings{{!}}below]].}}

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

<span id="verify_xdg_session_type">Once logged in</span>, you should verify that you are indeed running a {{c|wayland}} session. Directly at the target machine's keyboard, press the {{Key|Windows Key}} and type 'terminal', then press {{Key|Enter}}. A standard GNOME terminal window should open. Click in it, and then type (inside it):

{{Cmd
|echo "${XDG_SESSION_TYPE}"
|prompt=sakaki@koneko <span style{{=}}"color:royalblue;">~ $</span>
|output=<pre>
wayland
</pre>
}}

Assuming you see {{c|wayland}}, as above, all is well. Close out the terminal window now, then [[#gnome_wayland_running_ok|click here]] to proceed with the next step in the install.

However, if instead you saw {{c|x11}} returned, you have been launched into a legacy X11 GNOME session, ''not'' {{c|wayland}}. Given that [[#additional_wayland_qualification|you have an appropriate DRM kernel driver installed]], this indicates an error with your system's userland configuration.

{{Note|The following points should ''only'' be attempted if you could ''not'' start a {{c|wayland}}-based GNOME session (as confirmed by the <var>XDG_SESSION_TYPE</var> variable having the value {{c|x11}}, when [[#verify_xdg_session_type{{!}}tested]]).<br>To repeat: if you did manage to get GNOME on {{c|wayland}} running successfully, [[#gnome_wayland_running_ok{{!}}click here]] instead, to proceed with the next step in the install.}}

First, check that you have set the correct [[../Installing_the_Gentoo_Stage_3_Files#video_cards_variable{{!}}<var>VIDEO_CARDS</var>]] entry to match your kernel driver (this is important, because it e.g., sets up the driver-specific <var>USE</var> flags for the userspace {{Package|media-libs/mesa}} library). Modify this variable (in {{Path|/etc/portage/make.conf}}) if necessary, then (if you needed to make changes), issue (via your {{c|ssh}}/{{c|screen}} connection): {{RootCmd
|emerge --verbose --deep --with-bdeps{{=}}y --changed-use --update @world
|rc-service xdm restart
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
and try logging in again.

{{Note|If you are performing an install over WiFi, and have temporarily lost your connection when {{c|NetworkManager}} was started up ([[#start_nm{{!}}above]]), you can issue the above two commands at a root terminal opened directly on the machine from within GNOME.}}

Second, if that was not the problem, and if you have multiple graphics cards (or a 'hybrid graphics' system) installed in your target PC, then note that the time of writing, {{c|wayland}} does not officially support this configuration (and so GNOME will fall back to X11 mode if it is detected). You can override this default, by appending <code>MUTTER_ALLOW_HYBRID_GPUS=1</code> to the file {{Path|/etc/environment}}. Do so now, then reboot, and try logging in again.<ref name="mutter_hybrid_gpus">Arch Linux Forum: [https://bbs.archlinux.org/viewtopic.php?pid=1709012#p1709012 "GNOME 3.24 Always Loads X11 instead of Wayland"]</ref> (Warning: this setting may cause system instability, so don't set it unless you know you have a problem.)

If neither of those suggestions solved your {{c|wayland}} startup problem, then unfortunately it appears that (for some currently unknown reason) you cannot use GNOME with {{c|wayland}} on your machine. You can try posting a question in the [https://forums.gentoo.org Gentoo forums] for help (including in Leio's official [https://forums.gentoo.org/viewtopic-t-1094796.html support thread]). In the meantime, proceed with the rest of the tutorial [[#gnome_wayland_running_ok{{!}}immediately below]], using GNOME under X11 rather than {{c|wayland}} (your desktop will still be fully functional, just somewhat less secure).

<span id="gnome_wayland_running_ok">Now, and before our final reboot</span> (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:
# ensuring that network settings are correct;
# setting up keyboard settings are correct within GNOME (if required); and
# ensuring that our the system remembers our volume preferences between reboots.

=== <span id="gnome_network_settings">GNOME Network Settings</span> ===

You should now make sure that your network settings are correct under GNOME. Any wired connection will most likely 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 {{Key|Windows Key}}, then type "{{c|gnome-settings}}" (and press {{Key|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 {{Key|F1}}.

{{Note|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 (if you have been installing over Ethernet, and have a WiFi adapter on your target PC that isn't supported by the minimal install image's fairly minimal default kernel configuration), that are not working yet. That's because we haven't yet enabled all necessary kernel drivers &mdash; but we will address this in the [[../Final_Configuration_Steps_under_OpenRC|next chapter]]!}}
{{Note|Some users have commented that GNOME (and in particular, WiFi) does not come up properly, until their machine is restarted with {{c|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, [[#restart_to_gnome{{!}}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 {{Key|Windows Key}} and type 'Web', then press {{Key|Enter}} to start the first item shown. GNOME's default [[:Wikipedia:Web_(web_browser)|web browser]] will start up (if it initially opens full-screen, you can drag it down by the top bar to make it a normal-sized window). You can then type in a URL etc.:
{|style="background:transparent; color:black" 
|[[File:Gnome_web_app.jpg|thumb|none|400px|Searching for a Web Browser in GNOME...]]
|[[File:Gnome_with_browser.jpg|thumb|none|400px|...And Using the Default Browser]]
|}

{{Note|This browser (called {{c|epiphany}}) is quite basic; as of the time of writing it won't do a great job with more complex sites. For this, consider installing (and [[../Sandboxing_the_Firefox_Browser_with_Firejail{{!}}sandboxing]]) a full-scale browser such as {{Package|www-client/firefox}} once your system is fully configured and running (but please also have a look at [[../Using_Your_New_Gentoo_System_under_OpenRC#play_mp4_in_gnome{{!}}these later notes]], if your issue is only a lack of video in {{c|epiphany}}, when viewing sites like YouTube (unlikely to be an issue with modern systems).}}

=== <span id="gnome_keyboard_settings">GNOME Keyboard Settings</span> ===

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 {{Key|Windows Key}}, then type "{{c|region}}" (and press {{Key|Enter}}) and click on the {{c|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 "{{c|Region & Language}}" dialog.

Once an item <span id{{=}}"input_source_menu">has been added</span>, 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.

{{Note|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 "{{c|Region & Language}}" panel.}}
{{Note|GNOME has quite extensive context-sensitive help, which you can access by pressing {{Key|F1}} in any panel (for example, try it with "{{c|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.}}

=== <span id="gnome_volume_control">GNOME Volume Control</span> ===

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 {{Package|media-sound/alsa-utils}} (you can do this via the {{c|ssh}}/{{c|screen}} terminal on the helper PC):
{{RootCmd
|emerge --ask --verbose media-sound/alsa-utils
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
</pre>
}}
Once that completes, set the volume levels as you like them, then issue:
{{RootCmd
|alsactl store
|rc-update add alsasound boot
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
The settings should now be preserved across a reboot.

{{Note|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.}}

=== <span id="tracker_fully_off">Turning tracker Fully Off</span> ===

Next, if you wish to ensure that GNOME's {{c|tracker}} software is disabled completely for your current user (this step is optional), click on {{Key|Windows Key}}, then type "{{c|search}}" (and press {{Key|Enter}}; you may need to press twice). Then ensure the slider on the ''top bar'' of the shown dialog is turned '''off'''.

{{Tip|Instead of turning {{c|tracker}} off entirely, you can fine-tune the and apps that it queries using this dialog (and, via the 'cogwheel' icon, which file locations it indexes).}}

Close out the dialog window when done.

=== <span id="restart_to_gnome">Restarting into GNOME!</span> ===

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 {{c|ssh}}/{{c|screen}} terminal. Issue:
{{RootCmd
|exit
|prompt=<span style{{=}}"color:gray;">(1)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
which will close the first {{c|screen}} terminal, then:
{{RootCmd
|exit
|prompt=<span style{{=}}"color:gray;">(2)</span> koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
to close the second one, then:
{{RootCmd
|exit
|prompt=koneko <span style{{=}}"color:royalblue;">~ #</span>
}}
which will close out the {{c|ssh}} session itself.
{{Note|If installing over WiFi, it is possible that your {{c|ssh}} session may have hung when you temporarily lost connectivity due to starting {{c|NetworkManager}} above, making it impossible to enter the above {{c|exit}} commands. If this has happened to you, simply press {{Key|Enter}} followed by {{Key|~}} then {{Key|.}} (tilde then period) to terminate it,<ref>Plankers, Bob. [https://lonesysadmin.net/2011/11/08/ssh-escape-sequences-aka-kill-dead-ssh-sessions/ "SSH Escape Sequences (aka Kill Dead SSH Sessions)"]</ref> or alternatively close its surrounding terminal window on the helper PC.}}

Now, ensure that the USB boot key is inserted in the target PC, and reboot it, by clicking on GNOME's '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 {{c|gpg}} passphrase (the one you created [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#create_gpg_luks_keyfile|earlier]]), directly at the target machine keyboard to unlock the LUKS partition. You should then be presented directly with a GNOME login page (as [[#login_to_gnome|above]]). Directly at the target machine, click on your (regular) user name then, when prompted, type in the (regular user) password you set up [[#setup_regular_user|earlier]] (ensure you have the correct keyboard settings, if relevant, as discussed [[#input_source_menu|above]]). GNOME should remember the session type you selected last time (e.g., {{Key|GNOME}}), and default to using that.

Once logged in to GNOME, bring up a web browser: directly at the target machine's keyboard, press the {{Key|Windows Key}} and type 'Web', then press {{Key|Enter}} to start the first item shown. GNOME's default [[:Wikipedia:Web_(web_browser)|web browser]] will start up, (if it initially opens full-screen, you can drag it down by the top bar to make it a normal-sized window). You can then type in the URL for this tutorial (<span id="rejoin">[[{{SUBJECTPAGENAME}}#rejoin]]</span>), so that you can continue to follow it there.
{{Important|From this point on, all interaction with the target machine will be done directly (and not via the helper PC), unless otherwise noted.}}

Now, <span id="open_gnome_terminal">bring up a terminal window</span> in GNOME. Press the {{Key|Windows Key}} again, and type 'terminal', then press {{Key|Enter}}. A standard-issue terminal window should open. As we have some final installation work to do, become root:
{{Cmd
|su --login root
|prompt=sakaki@koneko <span style{{=}}"color:royalblue;">~ $</span>
|output=<pre>
Password: <enter root password>
</pre>
}}
The password required here is the one you set up [[../Final_Preparations_and_Reboot_into_EFI#setup_new_root_password|earlier]] in the tutorial (and have used when {{c|ssh}}-ing in).

== <span id="next_steps">Next Steps</span> ==

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. [[../Final_Configuration_Steps_under_OpenRC|Click here]] to go to the next chapter, "Final Configuration Steps under OpenRC".

== <span id="notes">Notes</span> ==
{{reflist}}

{| class="wikitable" style="margin: 1em auto 1em auto;"
|-
| [[../Configuring_Secure_Boot_under_OpenRC|< Previous]]
| [[../|Home]]
| [[../Final_Configuration_Steps_under_OpenRC|Next >]]
|}

[[Category:Sakaki's EFI Install Guide]]
[[Category:GNOME]]
[[Category:Localization]]
[[Category:X.Org]]