diff options
Diffstat (limited to 'nixpkgs/nixos/doc/manual/configuration/x-windows.xml')
| -rw-r--r-- | nixpkgs/nixos/doc/manual/configuration/x-windows.xml | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/configuration/x-windows.xml b/nixpkgs/nixos/doc/manual/configuration/x-windows.xml new file mode 100644 index 000000000000..7cdc5196e0d2 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/x-windows.xml @@ -0,0 +1,292 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + 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: +<programlisting> +<xref linkend="opt-services.xserver.enable"/> = true; +</programlisting> + 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. +<programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "r128" ]; +</programlisting> + 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 <command>xterm</command> window. + Thus you should pick one or more of the following lines: +<programlisting> +<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true; +<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true; +<xref linkend="opt-services.xserver.desktopManager.gnome3.enable"/> = true; +<xref linkend="opt-services.xserver.desktopManager.mate.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.xmonad.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.twm.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.icewm.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.i3.enable"/> = true; +</programlisting> + </para> + <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: +<programlisting> +<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.slim.enable"/> = true; +</programlisting> + </para> + <para> + You can set the keyboard layout (and optionally the layout variant): +<programlisting> +<xref linkend="opt-services.xserver.layout"/> = "de"; +<xref linkend="opt-services.xserver.xkbVariant"/> = "neo"; +</programlisting> + </para> + <para> + The X server is started automatically at boot time. If you don’t want this + to happen, you can set: +<programlisting> +<xref linkend="opt-services.xserver.autorun"/> = false; +</programlisting> + The X server can then be started manually: +<screen> +# systemctl start display-manager.service +</screen> + </para> + <para> + On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine, + you should also set the following: +<programlisting> +<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true; +</programlisting> + </para> + <simplesect 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: +<programlisting> +<xref linkend="opt-services.xserver.desktopManager.default"/> = "none"; +<xref linkend="opt-services.xserver.windowManager.default"/> = "i3"; +</programlisting> + And, finally, to enable auto-login for a user <literal>johndoe</literal>: +<programlisting> +<xref linkend="opt-services.xserver.displayManager.auto.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.auto.user"/> = "johndoe"; +</programlisting> + </para> + </simplesect> + <simplesect 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: +<programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidia" ]; +</programlisting> + Or if you have an older card, you may have to use one of the legacy drivers: +<programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy390" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy173" ]; +</programlisting> + You may need to reboot after enabling this driver to prevent a clash with + other kernel modules. + </para> + </simplesect> + <simplesect xml:id="sec-x11--graphics-cards-amd"> + <title>Proprietary AMD drivers</title> + <para> + AMD 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: +<programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "ati_unfree" ]; +</programlisting> + You will need to reboot after enabling this driver to prevent a clash with + other kernel modules. + </para> + <note> + <para> + For recent AMD GPUs you most likely want to keep either the defaults + or <literal>"amdgpu"</literal> (both free). + </para> + </note> + </simplesect> + <simplesect 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: +<programlisting> +<xref linkend="opt-services.xserver.libinput.enable"/> = true; +</programlisting> + The driver has many options (see <xref linkend="ch-options"/>). For + instance, the following disables tap-to-click behavior: +<programlisting> +<xref linkend="opt-services.xserver.libinput.tapping"/> = false; +</programlisting> + Note: the use of <literal>services.xserver.synaptics</literal> is deprecated + since NixOS 17.09. + </para> + </simplesect> + <simplesect 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 GTK2 ones, you can install <literal>qt5.qtbase.gtk</literal> + package into your system environment. It should work for all Qt 5 library + versions. + </para> + </simplesect> + <simplesect 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 + <option> + <link linkend="opt-services.xserver.extraLayouts"> + services.xserver.extraLayouts + </link> + </option>. + 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> + To do this we are going to create a <literal>us-greek</literal> file + with a <literal>xkb_symbols</literal> section. + </para> +<programlisting> +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> + To install the layout, the filepath, a description and the list of + languages must be given: + </para> +<programlisting> +<xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = { + description = "US layout with alt-gr greek"; + languages = [ "eng" ]; + symbolsFile = /path/to/us-greek; +} +</programlisting> + <note> + <para> + The name should match the one given to the + <literal>xkb_symbols</literal> block. + </para> + </note> + <para> + The layout should now be installed and ready to use: try it by + running <literal>setxkbmap us-greek</literal> and type + <literal><alt>+a</literal>. To change the default the usual + <option> + <link linkend="opt-services.xserver.layout"> + services.xserver.layout + </link> + </option> + 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> +xkb_keycodes "media" +{ + <volUp> = 123; + <volDown> = 456; +} +</programlisting> + <para> + Now use the newly define keycodes in <literal>media-sym</literal>: + </para> +<programlisting> +xkb_symbols "media" +{ + key.type = "ONE_LEVEL"; + key <volUp> { [ XF86AudioLowerVolume ] }; + key <volDown> { [ XF86AudioRaiseVolume ] }; +} +</programlisting> + <para> + As before, to install the layout do + </para> +<programlisting> +<xref linkend="opt-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> +<xref linkend="opt-services.xserver.displayManager.sessionCommands"/> = "setxkbmap -keycodes media"; +</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> +</simplesect> +</chapter> |