summary refs log tree commit diff
path: root/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/from_md/configuration/x-windows.chapter.xml')
-rw-r--r--nixos/doc/manual/from_md/configuration/x-windows.chapter.xml381
1 files changed, 381 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml
new file mode 100644
index 00000000000..274d0d817bc
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml
@@ -0,0 +1,381 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-x11">
+  <title>X Window System</title>
+  <para>
+    The X Window System (X11) provides the basis of NixOS’ graphical
+    user interface. It can be enabled as follows:
+  </para>
+  <programlisting language="bash">
+services.xserver.enable = true;
+</programlisting>
+  <para>
+    The X server will automatically detect and use the appropriate video
+    driver from a set of X.org drivers (such as <literal>vesa</literal>
+    and <literal>intel</literal>). You can also specify a driver
+    manually, e.g.
+  </para>
+  <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;r128&quot; ];
+</programlisting>
+  <para>
+    to enable X.org’s <literal>xf86-video-r128</literal> driver.
+  </para>
+  <para>
+    You also need to enable at least one desktop or window manager.
+    Otherwise, you can only log into a plain undecorated
+    <literal>xterm</literal> window. Thus you should pick one or more of
+    the following lines:
+  </para>
+  <programlisting language="bash">
+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;
+</programlisting>
+  <para>
+    NixOS’s default <emphasis>display manager</emphasis> (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:
+  </para>
+  <programlisting language="bash">
+services.xserver.displayManager.sddm.enable = true;
+services.xserver.displayManager.gdm.enable = true;
+</programlisting>
+  <para>
+    You can set the keyboard layout (and optionally the layout variant):
+  </para>
+  <programlisting language="bash">
+services.xserver.layout = &quot;de&quot;;
+services.xserver.xkbVariant = &quot;neo&quot;;
+</programlisting>
+  <para>
+    The X server is started automatically at boot time. If you don’t
+    want this to happen, you can set:
+  </para>
+  <programlisting language="bash">
+services.xserver.autorun = false;
+</programlisting>
+  <para>
+    The X server can then be started manually:
+  </para>
+  <programlisting>
+# systemctl start display-manager.service
+</programlisting>
+  <para>
+    On 64-bit systems, if you want OpenGL for 32-bit programs such as in
+    Wine, you should also set the following:
+  </para>
+  <programlisting language="bash">
+hardware.opengl.driSupport32Bit = true;
+</programlisting>
+  <section xml:id="sec-x11-auto-login">
+    <title>Auto-login</title>
+    <para>
+      The x11 login screen can be skipped entirely, automatically
+      logging you into your window manager and desktop environment when
+      you boot your computer.
+    </para>
+    <para>
+      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.
+    </para>
+    <para>
+      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:
+    </para>
+    <programlisting language="bash">
+services.xserver.displayManager.defaultSession = &quot;none+i3&quot;;
+</programlisting>
+    <para>
+      Every display manager in NixOS supports auto-login, here is an
+      example using lightdm for a user <literal>alice</literal>:
+    </para>
+    <programlisting language="bash">
+services.xserver.displayManager.lightdm.enable = true;
+services.xserver.displayManager.autoLogin.enable = true;
+services.xserver.displayManager.autoLogin.user = &quot;alice&quot;;
+</programlisting>
+  </section>
+  <section xml:id="sec-x11--graphics-cards-intel">
+    <title>Intel Graphics drivers</title>
+    <para>
+      There are two choices for Intel Graphics drivers in X.org:
+      <literal>modesetting</literal> (included in the xorg-server
+      itself) and <literal>intel</literal> (provided by the package
+      xf86-video-intel).
+    </para>
+    <para>
+      The default and recommended is <literal>modesetting</literal>. It
+      is a generic driver which uses the kernel
+      <link xlink:href="https://en.wikipedia.org/wiki/Mode_setting">mode
+      setting</link> (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).
+    </para>
+    <para>
+      The second driver, <literal>intel</literal>, 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.
+    </para>
+    <para>
+      The results vary depending on the hardware, so you may have to try
+      both drivers. Use the option
+      <xref linkend="opt-services.xserver.videoDrivers" /> to set one.
+      The recommended configuration for modern systems is:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;modesetting&quot; ];
+services.xserver.useGlamor = true;
+</programlisting>
+    <para>
+      If you experience screen tearing no matter what, this
+      configuration was reported to resolve the issue:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;intel&quot; ];
+services.xserver.deviceSection = ''
+  Option &quot;DRI&quot; &quot;2&quot;
+  Option &quot;TearFree&quot; &quot;true&quot;
+'';
+</programlisting>
+    <para>
+      Note that this will likely downgrade the performance compared to
+      <literal>modesetting</literal> or <literal>intel</literal> with
+      DRI 3 (default).
+    </para>
+  </section>
+  <section xml:id="sec-x11-graphics-cards-nvidia">
+    <title>Proprietary NVIDIA drivers</title>
+    <para>
+      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:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;nvidia&quot; ];
+</programlisting>
+    <para>
+      Or if you have an older card, you may have to use one of the
+      legacy drivers:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;nvidiaLegacy390&quot; ];
+services.xserver.videoDrivers = [ &quot;nvidiaLegacy340&quot; ];
+services.xserver.videoDrivers = [ &quot;nvidiaLegacy304&quot; ];
+</programlisting>
+    <para>
+      You may need to reboot after enabling this driver to prevent a
+      clash with other kernel modules.
+    </para>
+  </section>
+  <section xml:id="sec-x11--graphics-cards-amd">
+    <title>Proprietary AMD drivers</title>
+    <para>
+      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:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;amdgpu-pro&quot; ];
+</programlisting>
+    <para>
+      You will need to reboot after enabling this driver to prevent a
+      clash with other kernel modules.
+    </para>
+  </section>
+  <section xml:id="sec-x11-touchpads">
+    <title>Touchpads</title>
+    <para>
+      Support for Synaptics touchpads (found in many laptops such as the
+      Dell Latitude series) can be enabled as follows:
+    </para>
+    <programlisting language="bash">
+services.xserver.libinput.enable = true;
+</programlisting>
+    <para>
+      The driver has many options (see <xref linkend="ch-options" />).
+      For instance, the following disables tap-to-click behavior:
+    </para>
+    <programlisting language="bash">
+services.xserver.libinput.touchpad.tapping = false;
+</programlisting>
+    <para>
+      Note: the use of <literal>services.xserver.synaptics</literal> is
+      deprecated since NixOS 17.09.
+    </para>
+  </section>
+  <section xml:id="sec-x11-gtk-and-qt-themes">
+    <title>GTK/Qt themes</title>
+    <para>
+      GTK themes can be installed either to user profile or system-wide
+      (via <literal>environment.systemPackages</literal>). To make Qt 5
+      applications look similar to GTK ones, you can use the following
+      configuration:
+    </para>
+    <programlisting language="bash">
+qt5.enable = true;
+qt5.platformTheme = &quot;gtk2&quot;;
+qt5.style = &quot;gtk2&quot;;
+</programlisting>
+  </section>
+  <section xml:id="custom-xkb-layouts">
+    <title>Custom XKB layouts</title>
+    <para>
+      It is possible to install custom
+      <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">
+      XKB </link> keyboard layouts using the option
+      <literal>services.xserver.extraLayouts</literal>.
+    </para>
+    <para>
+      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.
+    </para>
+    <para>
+      Create a file called <literal>us-greek</literal> with the
+      following content (under a directory called
+      <literal>symbols</literal>; it's an XKB peculiarity that will help
+      with testing):
+    </para>
+    <programlisting language="bash">
+xkb_symbols &quot;us-greek&quot;
+{
+  include &quot;us(basic)&quot;            // includes the base US keys
+  include &quot;level3(ralt_switch)&quot;  // configures right alt as a third level switch
+
+  key &lt;LatA&gt; { [ a, A, Greek_alpha ] };
+  key &lt;LatB&gt; { [ b, B, Greek_beta  ] };
+  key &lt;LatG&gt; { [ g, G, Greek_gamma ] };
+  key &lt;LatD&gt; { [ d, D, Greek_delta ] };
+  key &lt;LatZ&gt; { [ z, Z, Greek_zeta  ] };
+};
+</programlisting>
+    <para>
+      A minimal layout specification must include the following:
+    </para>
+    <programlisting language="bash">
+services.xserver.extraLayouts.us-greek = {
+  description = &quot;US layout with alt-gr greek&quot;;
+  languages   = [ &quot;eng&quot; ];
+  symbolsFile = /yourpath/symbols/us-greek;
+};
+</programlisting>
+    <note>
+      <para>
+        The name (after <literal>extraLayouts.</literal>) should match
+        the one given to the <literal>xkb_symbols</literal> block.
+      </para>
+    </note>
+    <para>
+      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 <emphasis role="strong">test
+      your layout before applying it</emphasis>:
+    </para>
+    <programlisting>
+$ nix-shell -p xorg.xkbcomp
+$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
+</programlisting>
+    <para>
+      You can inspect the predefined XKB files for examples:
+    </para>
+    <programlisting>
+$ echo &quot;$(nix-build --no-out-link '&lt;nixpkgs&gt;' -A xorg.xkeyboardconfig)/etc/X11/xkb/&quot;
+</programlisting>
+    <para>
+      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 <literal>setxkbmap us-greek</literal> and then type
+      <literal>&lt;alt&gt;+a</literal> (it may not get applied in your
+      terminal straight away). To change the default, the usual
+      <literal>services.xserver.layout</literal> option can still be
+      used.
+    </para>
+    <para>
+      A layout can have several other components besides
+      <literal>xkb_symbols</literal>, for example we will define new
+      keycodes for some multimedia key and bind these to some symbol.
+    </para>
+    <para>
+      Use the <emphasis>xev</emphasis> utility from
+      <literal>pkgs.xorg.xev</literal> to find the codes of the keys of
+      interest, then create a <literal>media-key</literal> file to hold
+      the keycodes definitions
+    </para>
+    <programlisting language="bash">
+xkb_keycodes &quot;media&quot;
+{
+ &lt;volUp&gt;   = 123;
+ &lt;volDown&gt; = 456;
+}
+</programlisting>
+    <para>
+      Now use the newly define keycodes in <literal>media-sym</literal>:
+    </para>
+    <programlisting language="bash">
+xkb_symbols &quot;media&quot;
+{
+ key.type = &quot;ONE_LEVEL&quot;;
+ key &lt;volUp&gt;   { [ XF86AudioLowerVolume ] };
+ key &lt;volDown&gt; { [ XF86AudioRaiseVolume ] };
+}
+</programlisting>
+    <para>
+      As before, to install the layout do
+    </para>
+    <programlisting language="bash">
+services.xserver.extraLayouts.media = {
+  description  = &quot;Multimedia keys remapping&quot;;
+  languages    = [ &quot;eng&quot; ];
+  symbolsFile  = /path/to/media-key;
+  keycodesFile = /path/to/media-sym;
+};
+</programlisting>
+    <note>
+      <para>
+        The function
+        <literal>pkgs.writeText &lt;filename&gt; &lt;content&gt;</literal>
+        can be useful if you prefer to keep the layout definitions
+        inside the NixOS configuration.
+      </para>
+    </note>
+    <para>
+      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
+      <literal>setxkbmap</literal> at the start of the session with:
+    </para>
+    <programlisting language="bash">
+services.xserver.displayManager.sessionCommands = &quot;setxkbmap -keycodes media&quot;;
+</programlisting>
+    <para>
+      If you are manually starting the X server, you should set the
+      argument <literal>-xkbdir /etc/X11/xkb</literal>, otherwise X
+      won't find your layout files. For example with
+      <literal>xinit</literal> run
+    </para>
+    <programlisting>
+$ xinit -- -xkbdir /etc/X11/xkb
+</programlisting>
+    <para>
+      To learn how to write layouts take a look at the XKB
+      <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">documentation
+      </link>. More example layouts can also be found
+      <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">here
+      </link>.
+    </para>
+  </section>
+</chapter>