summary refs log tree commit diff
path: root/nixos/doc/manual/configuration/x-windows.chapter.md
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/configuration/x-windows.chapter.md')
-rw-r--r--nixos/doc/manual/configuration/x-windows.chapter.md337
1 files changed, 337 insertions, 0 deletions
diff --git a/nixos/doc/manual/configuration/x-windows.chapter.md b/nixos/doc/manual/configuration/x-windows.chapter.md
new file mode 100644
index 00000000000..2c80b786b26
--- /dev/null
+++ b/nixos/doc/manual/configuration/x-windows.chapter.md
@@ -0,0 +1,337 @@
+# X Window System {#sec-x11}
+
+The X Window System (X11) provides the basis of NixOS' graphical user
+interface. It can be enabled as follows:
+
+```nix
+services.xserver.enable = true;
+```
+
+The X server will automatically detect and use the appropriate video
+driver from a set of X.org drivers (such as `vesa` and `intel`). You can
+also specify a driver manually, e.g.
+
+```nix
+services.xserver.videoDrivers = [ "r128" ];
+```
+
+to enable X.org's `xf86-video-r128` driver.
+
+You also need to enable at least one desktop or window manager.
+Otherwise, you can only log into a plain undecorated `xterm` window.
+Thus you should pick one or more of the following lines:
+
+```nix
+services.xserver.desktopManager.plasma5.enable = true;
+services.xserver.desktopManager.xfce.enable = true;
+services.xserver.desktopManager.gnome.enable = true;
+services.xserver.desktopManager.mate.enable = true;
+services.xserver.windowManager.xmonad.enable = true;
+services.xserver.windowManager.twm.enable = true;
+services.xserver.windowManager.icewm.enable = true;
+services.xserver.windowManager.i3.enable = true;
+services.xserver.windowManager.herbstluftwm.enable = true;
+```
+
+NixOS's default *display manager* (the program that provides a graphical
+login prompt and manages the X server) is LightDM. You can select an
+alternative one by picking one of the following lines:
+
+```nix
+services.xserver.displayManager.sddm.enable = true;
+services.xserver.displayManager.gdm.enable = true;
+```
+
+You can set the keyboard layout (and optionally the layout variant):
+
+```nix
+services.xserver.layout = "de";
+services.xserver.xkbVariant = "neo";
+```
+
+The X server is started automatically at boot time. If you don't want
+this to happen, you can set:
+
+```nix
+services.xserver.autorun = false;
+```
+
+The X server can then be started manually:
+
+```ShellSession
+# systemctl start display-manager.service
+```
+
+On 64-bit systems, if you want OpenGL for 32-bit programs such as in
+Wine, you should also set the following:
+
+```nix
+hardware.opengl.driSupport32Bit = true;
+```
+
+## Auto-login {#sec-x11-auto-login .unnumbered}
+
+The x11 login screen can be skipped entirely, automatically logging you
+into your window manager and desktop environment when you boot your
+computer.
+
+This is especially helpful if you have disk encryption enabled. Since
+you already have to provide a password to decrypt your disk, entering a
+second password to login can be redundant.
+
+To enable auto-login, you need to define your default window manager and
+desktop environment. If you wanted no desktop environment and i3 as your
+your window manager, you\'d define:
+
+```nix
+services.xserver.displayManager.defaultSession = "none+i3";
+```
+
+Every display manager in NixOS supports auto-login, here is an example
+using lightdm for a user `alice`:
+
+```nix
+services.xserver.displayManager.lightdm.enable = true;
+services.xserver.displayManager.autoLogin.enable = true;
+services.xserver.displayManager.autoLogin.user = "alice";
+```
+
+## Intel Graphics drivers {#sec-x11--graphics-cards-intel .unnumbered}
+
+There are two choices for Intel Graphics drivers in X.org: `modesetting`
+(included in the xorg-server itself) and `intel` (provided by the
+package xf86-video-intel).
+
+The default and recommended is `modesetting`. It is a generic driver
+which uses the kernel [mode
+setting](https://en.wikipedia.org/wiki/Mode_setting) (KMS) mechanism. It
+supports Glamor (2D graphics acceleration via OpenGL) and is actively
+maintained but may perform worse in some cases (like in old chipsets).
+
+The second driver, `intel`, is specific to Intel GPUs, but not
+recommended by most distributions: it lacks several modern features (for
+example, it doesn\'t support Glamor) and the package hasn\'t been
+officially updated since 2015.
+
+The results vary depending on the hardware, so you may have to try both
+drivers. Use the option
+[](#opt-services.xserver.videoDrivers)
+to set one. The recommended configuration for modern systems is:
+
+```nix
+services.xserver.videoDrivers = [ "modesetting" ];
+services.xserver.useGlamor = true;
+```
+
+If you experience screen tearing no matter what, this configuration was
+reported to resolve the issue:
+
+```nix
+services.xserver.videoDrivers = [ "intel" ];
+services.xserver.deviceSection = ''
+  Option "DRI" "2"
+  Option "TearFree" "true"
+'';
+```
+
+Note that this will likely downgrade the performance compared to
+`modesetting` or `intel` with DRI 3 (default).
+
+## Proprietary NVIDIA drivers {#sec-x11-graphics-cards-nvidia .unnumbered}
+
+NVIDIA provides a proprietary driver for its graphics cards that has
+better 3D performance than the X.org drivers. It is not enabled by
+default because it's not free software. You can enable it as follows:
+
+```nix
+services.xserver.videoDrivers = [ "nvidia" ];
+```
+
+Or if you have an older card, you may have to use one of the legacy
+drivers:
+
+```nix
+services.xserver.videoDrivers = [ "nvidiaLegacy390" ];
+services.xserver.videoDrivers = [ "nvidiaLegacy340" ];
+services.xserver.videoDrivers = [ "nvidiaLegacy304" ];
+```
+
+You may need to reboot after enabling this driver to prevent a clash
+with other kernel modules.
+
+## Proprietary AMD drivers {#sec-x11--graphics-cards-amd .unnumbered}
+
+AMD provides a proprietary driver for its graphics cards that is not
+enabled by default because it's not Free Software, is often broken in
+nixpkgs and as of this writing doesn\'t offer more features or
+performance. If you still want to use it anyway, you need to explicitly
+set:
+
+```nix
+services.xserver.videoDrivers = [ "amdgpu-pro" ];
+```
+
+You will need to reboot after enabling this driver to prevent a clash
+with other kernel modules.
+
+## Touchpads {#sec-x11-touchpads .unnumbered}
+
+Support for Synaptics touchpads (found in many laptops such as the Dell
+Latitude series) can be enabled as follows:
+
+```nix
+services.xserver.libinput.enable = true;
+```
+
+The driver has many options (see [](#ch-options)).
+For instance, the following disables tap-to-click behavior:
+
+```nix
+services.xserver.libinput.touchpad.tapping = false;
+```
+
+Note: the use of `services.xserver.synaptics` is deprecated since NixOS
+17.09.
+
+## GTK/Qt themes {#sec-x11-gtk-and-qt-themes .unnumbered}
+
+GTK themes can be installed either to user profile or system-wide (via
+`environment.systemPackages`). To make Qt 5 applications look similar to
+GTK ones, you can use the following configuration:
+
+```nix
+qt5.enable = true;
+qt5.platformTheme = "gtk2";
+qt5.style = "gtk2";
+```
+
+## Custom XKB layouts {#custom-xkb-layouts .unnumbered}
+
+It is possible to install custom [ XKB
+](https://en.wikipedia.org/wiki/X_keyboard_extension) keyboard layouts
+using the option `services.xserver.extraLayouts`.
+
+As a first example, we are going to create a layout based on the basic
+US layout, with an additional layer to type some greek symbols by
+pressing the right-alt key.
+
+Create a file called `us-greek` with the following content (under a
+directory called `symbols`; it\'s an XKB peculiarity that will help with
+testing):
+
+```nix
+xkb_symbols "us-greek"
+{
+  include "us(basic)"            // includes the base US keys
+  include "level3(ralt_switch)"  // configures right alt as a third level switch
+
+  key <LatA> { [ a, A, Greek_alpha ] };
+  key <LatB> { [ b, B, Greek_beta  ] };
+  key <LatG> { [ g, G, Greek_gamma ] };
+  key <LatD> { [ d, D, Greek_delta ] };
+  key <LatZ> { [ z, Z, Greek_zeta  ] };
+};
+```
+
+A minimal layout specification must include the following:
+
+```nix
+services.xserver.extraLayouts.us-greek = {
+  description = "US layout with alt-gr greek";
+  languages   = [ "eng" ];
+  symbolsFile = /yourpath/symbols/us-greek;
+};
+```
+
+::: {.note}
+The name (after `extraLayouts.`) should match the one given to the
+`xkb_symbols` block.
+:::
+
+Applying this customization requires rebuilding several packages, and a
+broken XKB file can lead to the X session crashing at login. Therefore,
+you\'re strongly advised to **test your layout before applying it**:
+
+```ShellSession
+$ nix-shell -p xorg.xkbcomp
+$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
+```
+
+You can inspect the predefined XKB files for examples:
+
+```ShellSession
+$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
+```
+
+Once the configuration is applied, and you did a logout/login cycle, the
+layout should be ready to use. You can try it by e.g. running
+`setxkbmap us-greek` and then type `<alt>+a` (it may not get applied in
+your terminal straight away). To change the default, the usual
+`services.xserver.layout` option can still be used.
+
+A layout can have several other components besides `xkb_symbols`, for
+example we will define new keycodes for some multimedia key and bind
+these to some symbol.
+
+Use the *xev* utility from `pkgs.xorg.xev` to find the codes of the keys
+of interest, then create a `media-key` file to hold the keycodes
+definitions
+
+```nix
+xkb_keycodes "media"
+{
+ <volUp>   = 123;
+ <volDown> = 456;
+}
+```
+
+Now use the newly define keycodes in `media-sym`:
+
+```nix
+xkb_symbols "media"
+{
+ key.type = "ONE_LEVEL";
+ key <volUp>   { [ XF86AudioLowerVolume ] };
+ key <volDown> { [ XF86AudioRaiseVolume ] };
+}
+```
+
+As before, to install the layout do
+
+```nix
+services.xserver.extraLayouts.media = {
+  description  = "Multimedia keys remapping";
+  languages    = [ "eng" ];
+  symbolsFile  = /path/to/media-key;
+  keycodesFile = /path/to/media-sym;
+};
+```
+
+::: {.note}
+The function `pkgs.writeText <filename> <content>` can be useful if you
+prefer to keep the layout definitions inside the NixOS configuration.
+:::
+
+Unfortunately, the Xorg server does not (currently) support setting a
+keymap directly but relies instead on XKB rules to select the matching
+components (keycodes, types, \...) of a layout. This means that
+components other than symbols won\'t be loaded by default. As a
+workaround, you can set the keymap using `setxkbmap` at the start of the
+session with:
+
+```nix
+services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
+```
+
+If you are manually starting the X server, you should set the argument
+`-xkbdir /etc/X11/xkb`, otherwise X won\'t find your layout files. For
+example with `xinit` run
+
+```ShellSession
+$ xinit -- -xkbdir /etc/X11/xkb
+```
+
+To learn how to write layouts take a look at the XKB [documentation
+](https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts).
+More example layouts can also be found [here
+](https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples).