Project:GNOME/GNOME3 upgrade guide

From Gentoo Wiki
Jump to:navigation Jump to:search

This is a guide for upgrading since GNOME 2.32.x to GNOME 3.8.x or newer

Introduction

General changes

GNOME 3 includes two desktop modes:

The choice of desktop mode is done by choosing the desired session at the login screen, and both modes need 3D graphics capabilities, otherwise a fallback mode relying on software rendering will be used. Both modes are incompatible with x11-wm/compiz.

There is a quick tour of standard mode's GNOME Shell available on the GNOME website. For an in-depth guide to using GNOME Shell, see the GNOME Shell cheat sheet. You can also open the documentation provided by gnome-extra/gnome-getting-started-docs to see more documentation about the new GNOME Shell experience (i.e: yelp /usr/share/help/C/gnome-help/getting-started.page).

GNOME Shell at first may feel alienating and limiting to an experienced GNOME 2 user. We strongly encourage users to persist and use it for a few days; those who take the time to get used to GNOME Shell's behavior usually will love it and don't want to go back to a GNOME 2-like desktop environment, if you still doesn't like it, you can try to enable some of the available extensions while running Standard mode before finally switching to Classic one.

General configurability and extensions

GNOME 3 is designed to appear significantly less configurable than GNOME 2. For example, by default there is no easily discoverable GUI for changing the Gtk+ theme. Many configuration settings are hidden, but can still be changed using the gnome-extra/gnome-tweaks GUI, or from gsettings (can be explored using gnome-base/dconf-editor). Discussion of most of these settings is outside the scope of this guide.

GNOME Shell's behavior can be significantly altered using extensions. Gentoo packages the extensions from the official GNOME repository as gnome-extra/gnome-shell-extensions. GNOME Shell comes with a browser plugin that allows users to install extensions from the https://extensions.gnome.org/ web interface; there are also numerous developers publishing extensions on various third-party websites, which come with their own installation instructions.

Gentoo uses eselect gnome-shell-extensions from app-eselect/eselect-gnome-shell-extensions to manage system defaults that control whether extensions that were installed system-wide (i.e. in /usr/share/gnome-shell/extensions) should be enabled. Run the following to list all installed extensions and their descriptions:

root #eselect gnome-shell-extensions list -v

Newly-installed system-wide extensions start out disabled by default and can be enabled by default for all users using

root #eselect gnome-shell-extensions enable alternative-status-menu@gnome-shell-extensions.gcampax.github.com apps-menu@gnome-shell-extensions.gcampax.github.com window-list@gnome-shell-extensions.gcampax.github.com

Defaults managed by eselect gnome-shell-extensions can be overridden on a per-user basis using the extensions.gnome.org web interface, via gnome-tweaks (Shell Extensions tab), or from the command line using gsettings from dev-libs/glib. For example, to load altermative-status, apps-menu and window-list extensions, and disabling all other extensions, a user can run

user $gsettings set org.gnome.shell enabled-extensions '["alternative-status-menu@gnome-shell-extensions.gcampax.github.com", "apps-menu@gnome-shell-extensions.gcampax.github.com", "window-list@gnome-shell-extensions.gcampax.github.com"]'

to enable alternative-status, apps-menu and window-list extensions (and disabling all others!) for the current user.

Important
The code quality of extensions is highly variable. Some extensions contain memory leaks and others can render GNOME completely unusable. Gentoo cannot offer support for problems caused by third-party extensions.

Installation

Using gnome/systemd subprofile

People are highly encouraged to switch to the desktop/gnome/systemd subprofile as it includes settings that will make the update easier (as it sets proper defaults for USE flags and masking to prevent dependency blockers and therefore provides a better desktop experience).

You can use

root #eselect profile list

to see the available profiles and

root #eselect profile set default/linux/amd64/13.0/desktop/gnome/systemd

for setting the proper profile.

Required software

PulseAudio

GNOME 3 requires media-sound/pulseaudio for audio support. Ensure that you have the pulseaudio USE flag enabled globally (it will be enabled by default if you use the desktop/gnome portage profile). For troubleshooting PulseAudio problems, see documentation on pulseaudio.org .

systemd

GNOME 3 requires systemd to be running to get it working properly, otherwise, you will get broken power management and multiseat handling, and also some more problems because upstream has moved away from the obsolete consolekit to logind (that needs systemd to be running to work).

You must follow the systemd guide to migrate from openRC+udev to it. systemd will be needed while running GNOME, then, you can simply prepare your kernel and system as the guide suggest and, then, upgrade all your system on a run with commands listed below. That way, you will end up with GNOME 3 and systemd installed and will be able to reboot once all is configured as systemd guide says.

3D support

GNOME 3 relies on proper 3D support, please ensure you have a working 3D setup in your machine and refer to Troubleshooting to know how to try to solve some problems.

Recommended software

GDM

Even if you can still login in GNOME using any other login manager, using gnome-base/gdm will give you better integration and it is the preferred way for starting Gnome. It will be installed by gnome-base/gnome meta package and, to run it at startup, you can enable the service as follows:

root #systemctl enable gdm

Installing GNOME 3

If you are installing it from scratch a simple:

root #emerge gnome

Should be enough just after having systemd configured and running.

If you are upgrading from Gnome2, at first, please look at systemd guide to ensure systemd pre-installation configuration steps are done before running following commands to update to GNOME 3 and systemd.

You should use gnome-base/gnome if possible to ensure you get a better experience. If you were running gnome-base/gnome-light and want to migrate away to the other meta you can run the following before updating your system:

root #emerge --deselect gnome-light

You will need to also run the following to avoid blockers with packages relying on old stuff:

root #emerge --deselect gnome-utils --deselect gnome-applets --deselect seahorse-plugins --deselect gnome-games --deselect gnome-pilot --deselect dev-cpp/libpanelappletmm --deselect gnome-extra/deskbar-applet --deselect gnome-extra/fast-user-switch-applet --deselect gnome-extra/file-browser-applet --deselect gnome-extra/gnome-hdaps-applet --deselect gnome-extra/gnome-swallow --deselect gnome-extra/libgail-gnome --deselect gnome-extra/lock-keys-applet --deselect media-gfx/byzanz --deselect net-analyzer/gnome-netstatus --deselect net-analyzer/netspeed_applet --deselect x11-misc/glunarclock --deselect gcalctool

Additionally, you could need to disable "gnome" USE for app-dicts/verbiste, app-i18n/im-ja, dev-ml/lablgtk.

And, finally, upgrade:

root #emerge -avuDN --keep-going @world gnome-base/gnome

(You can try to specify, for example, a higher backtracking value appending something like --backtrack=100 to try to avoid blockers)

After that, please remember you read elog messages logged by updated ebuilds (usually in /var/log/portage/elog/summary.log, depending on your portage configuration) and continue with systemd Post-installation configuration steps.

It's also required to take a look to the below section to not get unwanted surprises (like losing network due changes in the way NetworkManager is configured)

Most noticeable changes for current GNOME users

NetworkManager will use upstream plugin to handle configs

When running Systemd, NetworkManager will use upstream plugin to handle configs (called 'keyfile'), then, you probably will need to reconfigure your network settings. If you have problems with this migration (like NetworkManager failing to start), you need to verify that old 'ifnet' plugin is not referred from /etc/NetworkManager/NetworkManager.conf.

Languages and encodings

GNOME 3 obtains user language settings from sys-apps/accountsservice. The language can be set in GNOME from the My Account entry in the upper right corner menu. Alternatively, you can directly edit AccountsService user files. For example, to have user larry use British English, you can (as root) edit /var/lib/AccountsService/users/larry so it reads the following:

FILE /var/lib/AccountsService/users/larrySimple example of an AccountsService user file
[User]
Language=en_GB.utf8

But, normally, you won't need to change this if wanting to use the same language as the used system wide.

Keyboard layouts and input methods

GNOME 3 does not use traditional xorg.conf keyboard layout settings. Instead, keyboard layouts and input methods are configured via ibus which is integrated into GNOME Shell.

To add a keyboard layout, open System Settings (or gnome-control-center from the terminal) and go to Region & Language → Input Sources. That dialog will also tell you how to change keyboard layout to switch between multiple keyboard layouts.

Touchpad and other input device customization

Apart of the settings you can change in "Control Center -> Mouse", if you have "disable touchpad while typing" selected in "Control Center -> Mouse", the touchpad will be disabled for 1 second after a keyboard key is pressed. In GNOME 2, this interval was 500 milliseconds. If you like to disable the touchpad while typing, but prefer the shorter timeout interval like in GNOME 2, you can emerge gnome-base/gnome-settings-daemon with the short-touchpad-timeout USE flag enabled.

GNOME 3 allows setting a custom command for advanced customization of input device settings. For example, suppose that you want to configure your touchpad to enable two-finger scrolling (both vertical and horizontal) and edge scrolling (vertical only). You could set a new GNOME input device hotplug script using the terminal:

user $cp /usr/share/gnome-settings-daemon-3.0/input-device-example.sh ~/input-device.sh
user $chmod +x ~/input-device.sh
user $gsettings set org.gnome.settings-daemon.peripherals.input-devices hotplug-command ~/input-device.sh

and create the following file:

FILE input-device.sh
# If the device is a touchpad ...
if [[ -z "${device#*TouchPad*}" ]]; then
	# ... enable two-finger scrolling (vertical and horizontal) ...
	xinput set-prop "${device}" "Synaptics Two-Finger Scrolling" 1 1
	# ... and edge scrolling (vertical only, no horizontal, no coasting) ...
	xinput set-prop "${device}" "Synaptics Edge Scrolling" 1 0 0
fi
# All further processing will be disabled if $retval == 0
exit $retval
Note
If the custom hotplug command does not terminate with exit value 0, gnome-settings-daemon will set its own settings on the input device, likely clobbering the settings that the hotplug command had changed.

If, for whatever reason, you want to completely prevent GNOME 3 from automatically modifying your mouse and touchpad settings (note that this will also prevent custom input hotplug commands, such as input-device.sh above, from modifying mice and touchpads!), you can run the following:

user $gsettings set org.gnome.settings-daemon.plugins.mouse active false

Configure monitors and displays

GNOME 3 uses xrandr to setup the monitors.

Try to configure your displays with

user $gnome-control-center display

To apply the settings as a system-wide default, copy ~/.config/monitors.xml to /etc/gnome-settings-daemon/xrandr/monitors.xml.

Suspend/Hibernate items in status menu

GNOME Shell 3 always shows a Power Off menu item by default in the upper-right corner menu. The Suspend menu item becomes visible after clicking on the upper right corner menu and holding down the Alt key. Laptops can also be suspended simply by shutting the lid.

To change status menu default items, you should probably try the alternative-status-menu extension. To do so, emerge gnome-extra/gnome-shell-extensions and run

root #eselect gnome-shell-extensions enable 'alternative-status-menu@gnome-shell-extensions.gnome.org

to enable the extension for all users by default, or use gnome-tweaks (Shell Extensions tab) to enable it on a per-user basis.

This will offer you separated "Suspend" and "Hibernate" menu items.

Suspend on laptop lid close

GNOME 3 will, by default, suspend a laptop when the lid is closed. If you do not like this behavior, you need to change one parameter in /etc/systemd/logind.conf:

FILE /etc/systemd/logind.confDisable suspend on laptop lid close
HandleLidSwitch=lock

One of the most common reasons for not wanting to suspend on laptop lid close is to carry a laptop to another room without losing the network connection. To do so, you can install gnome-extra/office-runner, which allows temporarily inhibiting GNOME's suspend-on-lid-close behavior for up to 10 minutes.

Interaction with tabs

Since GNOME 3.0, some applications stopped switching tabs when scrolling over them. This intended behavior by upstream actually covers at least app-editors/gedit, gnome-base/nautilus and www-client/epiphany. This behavior will not be patched by the Gentoo GNOME team so if you find it annoying, please report it directly at the GNOME Bugzilla.

Interaction with windows

If you were used to move and resize windows using Alt+Middle click, GNOME 3.6 replaced the Alt key with the Super (Windows logo) key. If you wish to change back to the old behavior, this can be done using gnome-tweaks (Windows tab), or you can use the terminal to set Alt as modifier key for window interaction:

user $gsettings set org.gnome.desktop.wm.preferences mouse-button-modifier '<Alt>'

Interaction with notifications

For GNOME 3 this action has been updated to react to the force with which the pointer is pressed against the screen edge. Only a determined push will cause the Message Tray to open. This enhancement avoids accidental triggers and is quicker and more immediate. To open the tray usually moving mouse to the button and, either trying to move it even more down or sticking it there will work. You can also open the tray pressing Super key or clicking on notification shown when a new one arrives in Activities overview.

Also, notifications handling has changed a lot during GNOME 3 cycles [1] [2]. Since some commonly used applications are still not using notifications in this way, they can be hard to use. To let this applications behave more similar to GNOME 2 you can use gnome-extra/gnome-shell-extensions-topicons and, once you install that package, enable it as usual, for example:

root #eselect gnome-shell-extensions enable topIcons@adel.gadllah@gmail.com

Fonts

GNOME 3 uses media-fonts/cantarell as its default font. Unfortunately, Cantarell currently only includes a subset of Latin and Cyrillic characters. Users of languages with alphabetic writing systems which are not yet covered by Cantarell will probably want to switch to another font, such as media-fonts/dejavu. This can be done using gnome-tweaks (Fonts tab), or you can set DejaVu (size 10) as the default font from the terminal:

user $gsettings set org.gnome.desktop.interface font-name 'DejaVu Sans 10'
user $gsettings set org.gnome.desktop.interface document-font-name 'DejaVu Sans 10'
user $gconftool-2 -s -t string /apps/metacity/general/titlebar_font 'DejaVu Sans Bold 10'

Icons on the desktop

In GNOME 3, ~/Desktop folder is simply treated as a normal folder with files instead of its contents being shown in the GNOME desktop. If you want to manage your desktop files like in GNOME 2, you can change the corresponding setting in the gnome-tweaks GUI (Desktop tab), or use the gsettings command from the terminal to make Nautilus manage the desktop:

user $gsettings set org.gnome.desktop.background show-desktop-icons true

This change is not needed if you are using GNOME Classical mode.

Currently, it's not possible to create launchers in desktop (see upstream bug #702587), as a workaround, you can try to copy existing launchers from /usr/share/applications to your ~/Desktop.

Logs of the session

If you were used to finding the logs of the current session in ~/.xsession-errors or ~/.cache/gdm/session.log, they are now directly logged by journald and, then, you will need to run journalctl to see them (see man journalctl for learning more about its usage).

See also

  • GNOME 3 troubleshooting
    This page is based on a document formerly found on our main website gentoo.org.
    The following people contributed to the original document: eva, pacho, tetromino
    They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.
Retrieved from "https://wiki.gentoo.org/index.php?title=Project:GNOME/GNOME3_upgrade_guide&oldid=1244883"