diff options
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.xml | 381 |
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 = [ "r128" ]; +</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 = "de"; +services.xserver.xkbVariant = "neo"; +</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 = "none+i3"; +</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 = "alice"; +</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 = [ "modesetting" ]; +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 = [ "intel" ]; +services.xserver.deviceSection = '' + Option "DRI" "2" + Option "TearFree" "true" +''; +</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 = [ "nvidia" ]; +</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 = [ "nvidiaLegacy390" ]; +services.xserver.videoDrivers = [ "nvidiaLegacy340" ]; +services.xserver.videoDrivers = [ "nvidiaLegacy304" ]; +</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 = [ "amdgpu-pro" ]; +</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 = "gtk2"; +qt5.style = "gtk2"; +</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 "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 ] }; +}; +</programlisting> + <para> + A minimal layout specification must include the following: + </para> + <programlisting language="bash"> +services.xserver.extraLayouts.us-greek = { + description = "US layout with alt-gr greek"; + languages = [ "eng" ]; + 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 "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/" +</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><alt>+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 "media" +{ + <volUp> = 123; + <volDown> = 456; +} +</programlisting> + <para> + Now use the newly define keycodes in <literal>media-sym</literal>: + </para> + <programlisting language="bash"> +xkb_symbols "media" +{ + key.type = "ONE_LEVEL"; + key <volUp> { [ XF86AudioLowerVolume ] }; + key <volDown> { [ XF86AudioRaiseVolume ] }; +} +</programlisting> + <para> + As before, to install the layout do + </para> + <programlisting language="bash"> +services.xserver.extraLayouts.media = { + description = "Multimedia keys remapping"; + languages = [ "eng" ]; + symbolsFile = /path/to/media-key; + keycodesFile = /path/to/media-sym; +}; +</programlisting> + <note> + <para> + The function + <literal>pkgs.writeText <filename> <content></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 = "setxkbmap -keycodes media"; +</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> |