diff --git a/documentation/content/en/books/handbook/x11/_index.adoc b/documentation/content/en/books/handbook/x11/_index.adoc index dfeb8aa6df..83291c3b34 100644 --- a/documentation/content/en/books/handbook/x11/_index.adoc +++ b/documentation/content/en/books/handbook/x11/_index.adoc @@ -1,822 +1,822 @@ --- title: Chapter 5. The X Window System part: Part I. Getting Started prev: books/handbook/ports next: books/handbook/wayland description: This chapter describes how to install and configure Xorg on FreeBSD, which provides the open source X Window System used to provide a graphical environment tags: ["X11", "Xorg", "TrueType", "Intel", "AMD", "NVIDIA", "Anti-Aliased", "VESA", "SCFB"] showBookMenu: true weight: 7 path: "/books/handbook/" --- [[x11]] = The X Window System :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 5 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/x11/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[x11-synopsis]] == Synopsis An installation of FreeBSD using bsdinstall does not automatically install a graphical user interface. This chapter describes how to install and configure Xorg, which provides the open source X Window System used to provide a graphical environment. It then describes how to find and install a desktop environment or window manager. Before reading this chapter, you should: * Know how to install additional third-party software as described in crossref:ports[ports,Installing Applications: Packages and Ports]. After reading this chapter, you will know: * The various components of the X Window System, and how they interoperate. * How to install and configure Xorg. * How to use TrueType(R) fonts in Xorg. * How to set up your system for graphical logins (XDM). [[x-install]] == Installing Xorg On FreeBSD, Xorg can be installed as a package or port. The binary meta package can be installed quickly but with fewer options for customization: [source,shell] .... # pkg install xorg .... Either of these installations results in the complete Xorg system being installed. The current user must be a member of the `video` group. To add a user to `video` group, execute the following command: [source,shell] .... # pw groupmod video -m username .... [TIP] ==== A smaller version of the X system suitable for experienced users is available in package:x11/xorg-minimal[]. Most of the documents, libraries, and applications will not be installed. Some applications require these additional components to function. ==== [TIP] ==== Video cards, monitors, and input devices are automatically detected and do not require any manual configuration. Do not create `xorg.conf` or run a `-configure` step unless automatic configuration fails. ==== [[x-graphic-card-drivers]] == Graphic card drivers The following table shows the different graphics cards supported by FreeBSD, which package should be installed and its corresponding module. .Graphic card packages [options="header", cols="1,1,1,1"] |=== | Brand | Type | Package | Module | Intel(R) | Open Source | drm-kmod | `i915kms` | AMD(R) | Open Source | drm-kmod | `amdgpu` and `radeonkms` | NVIDIA(R) | Proprietary | nvidia-driver | `nvidia` or `nvidia-modeset` | VESA | Open Source | xf86-video-vesa | vesa | SCFB | Open Source | xf86-video-scfb | scfb | Virtualbox | Open Source | virtualbox-ose-additions | Virtualbox OSE additions include the `vboxvideo` driver. | VMware(R) | Open Source | xf86-video-vmware | vmwgfx |=== The following command can be used to identify which graphics card is installed in the system: [source,shell] .... % pciconf -lv|grep -B4 VGA .... The output should be similar to the following: [.programlisting] .... vgapci0@pci0:0:2:0: class=0x030000 rev=0x07 hdr=0x00 vendor=0x8086 device=0x2a42 subvendor=0x17aa subdevice=0x20e4 vendor = 'Intel Corporation' device = 'Mobile 4 Series Chipset Integrated Graphics Controller' class = display subclass = VGA .... [WARNING] ==== If the graphics card is not supported by Intel(R), AMD(R) or NVIDIA(R) drivers, then VESA or SCFB modules should be used. VESA module must be used when booting in BIOS mode and SCFB module must be used when booting in UEFI mode. This command can be used to check the booting mode: [source,shell] .... % sysctl machdep.bootmethod .... The output should be similar to the following: [.programlisting] .... machdep.bootmethod: BIOS .... ==== [[x-configuration-intel]] === Intel(R) Intel(R) Graphics refers to the class of graphics chips that are integrated on the same die as an Intel(R) CPU. Wikipedia offers link:https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units[a good overview of the variations and names used for generations of Intel HD Graphics]. The package:graphics/drm-kmod[] package indirectly provides a range of kernel modules for use with Intel(R) Graphics cards. The Intel(R) driver can be installed by executing the following command: [source,shell] .... # pkg install drm-kmod .... Then add the module to `/etc/rc.conf` file, executing the following command: [source,shell] .... # sysrc kld_list+=i915kms .... [TIP] ==== If a high CPU usage is noticed or excessive tearing with HD video, the installation of package:multimedia/libva-intel-driver[] may help. To install the package execute the following command: [source,shell] .... # pkg install libva-intel-driver mesa-libs mesa-dri .... ==== [[x-configuration-amd]] === AMD(R) The package:graphics/drm-kmod[] package indirectly provides a range of kernel modules for use with AMD(R) Graphics cards. The modules `amdgpu` and `radeonkms` can be used depending the generation of the hardware. The FreeBSD project maintains an link:https://wiki.freebsd.org/Graphics/AMD-GPU-Matrix[AMD graphics support matrix to determine which driver must be used]. AMD(R) driver can be installed by executing the following command: [source,shell] .... # pkg install drm-kmod .... For post-HD7000 or Tahiti graphic cards add the module to `/etc/rc.conf` file, executing the following command: [source,shell] .... # sysrc kld_list+=amdgpu .... For older graphic cards (pre-HD7000 or pre-Tahiti) add the module to `/etc/rc.conf` file, executing the following command: [source,shell] .... # sysrc kld_list+=radeonkms .... [[x-configuration-nvidia]] === NVIDIA(R) FreeBSD supports different versions of the proprietary NVIDIA(R) driver. Users of newer graphics cards should install the package:x11/nvidia-driver[] package. Those with older cards will have to check below which version supports them. .Supported versions of NVIDIA(R) drivers [options="header", cols="1,1"] |=== | Package | Supported hardware | x11/nvidia-driver-304 | link:https://www.nvidia.com/Download/driverResults.aspx/123712/en-us/[supported hardware] | x11/nvidia-driver-340 | link:https://www.nvidia.com/Download/driverResults.aspx/156167/en-us/[supported hardware] | x11/nvidia-driver-390 | link:https://www.nvidia.com/Download/driverResults.aspx/191122/en-us/[supported hardware] | x11/nvidia-driver-470 | link:https://www.nvidia.com/Download/driverResults.aspx/191234/en-us/[supported hardware] | x11/nvidia-driver | link:https://www.nvidia.com/Download/driverResults.aspx/187164/en-us/[supported hardware] |=== [WARNING] ==== Version 304 of the NVIDIA(R) graphics driver (nvidia-driver-304) does not support xorg-server 1.20 or later. ==== The latest NVIDIA(R) driver can be installed by running the following command: [source,shell] .... # pkg install nvidia-driver .... Then add the module to `/etc/rc.conf` file, executing the following command: [source,shell] .... # sysrc kld_list+=nvidia-modeset .... [WARNING] ==== The `nvidia` driver must be used if the packages x11/nvidia-driver-304 or x11/nvidia-driver-340 have been installed. [source,shell] .... # sysrc kld_list+=nvidia .... ==== [[x-config]] == Xorg Configuration Xorg supports most common video cards, keyboards, and pointing devices. [WARNING] ==== Video cards, monitors, and input devices are automatically detected and do not require any manual configuration. Do not create [.filename]#xorg.conf# or run a `Xorg -configure` step unless automatic configuration fails. ==== [[x-config-files]] === Configuration Files Xorg looks in several directories for configuration files. [.filename]#/usr/local/etc/X11/# is the *recommended* directory for these files on FreeBSD. Using this directory helps keep application files separate from operating system files. [[x-config-files-single-or-multi]] === Single or Multiple Files It is easier to use multiple files that each configure a specific setting than the traditional single [.filename]#xorg.conf#. These files are stored in the [.filename]#/usr/local/etc/X11/xorg.conf.d/# subdirectory. [TIP] ==== The traditional single [.filename]#xorg.conf# still works, but is neither as clear nor as flexible as multiple files in the [.filename]#/usr/local/etc/X11/xorg.conf.d/# subdirectory. ==== [[x-config-video-cards]] === Video Cards The driver for the graphics card can be specified in the [.filename]#/usr/local/etc/X11/xorg.conf.d/# directory. To configure the Intel(R) driver in a configuration file: [[x-config-video-cards-file-intel]] .Select Intel(R) Video Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-intel.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "intel" EndSection .... ==== To configure the AMD(R) driver in a configuration file: -[[x-config-video-cards-file-intel]] +[[x-config-video-cards-file-amd]] .Select AMD(R) Video Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-radeon.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "radeon" EndSection .... ==== To configure the NVIDIA(R) driver in a configuration file: -[[x-config-video-cards-file-intel]] +[[x-config-video-cards-file-nvidia]] .Select NVIDIA(R) Video Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-nvidia.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "nvidia" EndSection .... ==== To configure the VESA driver in a configuration file: -[[x-config-video-cards-file-intel]] +[[x-config-video-cards-file-vesa]] .Select VESA Video Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-vesa.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "vesa" EndSection .... ==== To configure the SCFB driver in a configuration file: -[[x-config-video-cards-file-intel]] +[[x-config-video-cards-file-sfcb]] .Select SCFB Video Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-scfb.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "scfb" EndSection .... ==== To configure multiple video cards, the `BusID` can be added. A list of video card bus ``ID``s can be displayed by executing: [source,shell] .... % pciconf -lv | grep -B3 display .... The output should be similar to the following: [.programlisting] .... vgapci0@pci0:0:2:0: class=0x030000 rev=0x07 hdr=0x00 vendor=0x8086 device=0x2a42 subvendor=0x17aa subdevice=0x20e4 vendor = 'Intel Corporation' device = 'Mobile 4 Series Chipset Integrated Graphics Controller' class = display -- vgapci1@pci0:0:2:1: class=0x038000 rev=0x07 hdr=0x00 vendor=0x8086 device=0x2a43 subvendor=0x17aa subdevice=0x20e4 vendor = 'Intel Corporation' device = 'Mobile 4 Series Chipset Integrated Graphics Controller' class = display .... [[x-config-video-cards-file-multiple]] .Select Intel(R) Video Driver and NVIDIA(R) Video Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-drivers.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "intel" BusID "pci0:0:2:0" EndSection Section "Device" Identifier "Card0" Driver "nvidia" BusID "pci0:0:2:1" EndSection .... ==== [[x-config-monitors]] === Monitors Almost all monitors support the Extended Display Identification Data standard (`EDID`). Xorg uses `EDID` to communicate with the monitor and detect the supported resolutions and refresh rates. Then it selects the most appropriate combination of settings to use with that monitor. Other resolutions supported by the monitor can be chosen by setting the desired resolution in configuration files, or after the X server has been started with man:xrandr[1]. [[x-config-monitors-xrandr]] ==== Using RandR (Resize and Rotate) Run man:xrandr[1] without any parameters to see a list of video outputs and detected monitor modes: [source,shell] .... % xrandr .... The output should be similar to the following: [.programlisting] .... Screen 0: minimum 320 x 200, current 2560 x 960, maximum 8192 x 8192 LVDS-1 connected 1280x800+0+0 (normal left inverted right x axis y axis) 261mm x 163mm 1280x800 59.99*+ 59.81 59.91 50.00 1280x720 59.86 59.74 1024x768 60.00 1024x576 59.90 59.82 960x540 59.63 59.82 800x600 60.32 56.25 864x486 59.92 59.57 640x480 59.94 720x405 59.51 58.99 640x360 59.84 59.32 VGA-1 connected primary 1280x960+1280+0 (normal left inverted right x axis y axis) 410mm x 257mm 1280x1024 75.02 60.02 1440x900 74.98 60.07 1280x960 60.00* 1280x800 74.93 59.81 1152x864 75.00 1024x768 75.03 70.07 60.00 832x624 74.55 800x600 72.19 75.00 60.32 56.25 640x480 75.00 72.81 66.67 59.94 720x400 70.08 HDMI-1 disconnected (normal left inverted right x axis y axis) DP-1 disconnected (normal left inverted right x axis y axis) HDMI-2 disconnected (normal left inverted right x axis y axis) DP-2 disconnected (normal left inverted right x axis y axis) DP-3 disconnected (normal left inverted right x axis y axis) .... This shows that the `VGA-1` output is being used to display a screen resolution of 1280x960 pixels at a refresh rate of about 60 Hz. The `LVDS-1` is being used as a secondary monitor to display a screen resolution of 1280x800 pixels at a refresh rate of about 60 Hz. Monitors are not attached to the `HDMI-1`, `HDMI-2`, `DP-1`, `DP-2` and `DP-3` connectors. Any of the other display modes can be selected with man:xrandr[1]. For example, to switch to 1280x1024 at 60 Hz: [source,shell] .... % xrandr --output LVDS-1 --mode 1280x720 --rate 60 .... [[x-config-monitors-files]] ==== Using the Xorg configuration file The monitor configuration can also be set in a configuration file. To set a screen resolution of 1024x768 in a configuration file: .Set Screen Resolution in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/10-monitor.conf# [.programlisting] .... Section "Screen" Identifier "Screen0" Device "Card0" SubSection "Display" Modes "1024x768" EndSubSection EndSection .... ==== [[x-config-input]] === Input Devices Xorg supports the vast majority of input devices via package:x11/libinput[]. [TIP] ==== Some desktop environments (such as KDE Plasma) provide a graphical UI for setting these parameters. Check if this is the case before resorting to manual configuration editing. ==== [[x-config-input-keyboard-layout]] For example, to configure the keyboard layout: .Setting a Keyboard Layout [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/00-keyboard.conf# [.programlisting] .... Section "InputClass" Identifier "Keyboard1" MatchIsKeyboard "on" Option "XkbLayout" "es, fr" Option "XkbModel" "pc104" Option "XkbVariant" ",qwerty" Option "XkbOptions" "grp:win_space_toggle" EndSection .... ==== [[x-fonts]] == Using Fonts in Xorg The default fonts that ship with Xorg are less than ideal for typical desktop publishing applications. Large presentation fonts show up jagged and unprofessional looking, and small fonts are almost completely unintelligible. However, there are several free, high quality Type1 (PostScript(R)) fonts available which can be readily used with Xorg. [[type1]] === Type1 Fonts The URW font collection (package:x11-fonts/urwfonts[]) includes high quality versions of standard type1 fonts (Times Roman(TM), Helvetica(TM), Palatino(TM) and others). The Freefonts collection (package:x11-fonts/freefonts[]) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts. In addition, Xorg can be configured to use TrueType(R) fonts with a minimum of effort. For more details on this, see the man:X[7] manual page or <>. To install the above Type1 font collections from binary packages, run the following commands: [source,shell] .... # pkg install urwfonts .... And likewise with the freefont or other collections. To have the X server detect these fonts, add an appropriate line to the X server configuration file ([.filename]#/usr/local/etc/X11/xorg.conf.d/90-fonts.conf#), which reads: [.programlisting] .... Section "Files" FontPath "/usr/local/share/fonts/urwfonts/" EndSection .... Alternatively, at the command line in the X session run: [source,shell] .... % xset fp+ /usr/local/share/fonts/urwfonts % xset fp rehash .... This will work but will be lost when the X session is closed, unless it is added to the startup file ([.filename]#~/.xinitrc# for a normal `startx` session, or [.filename]#~/.xsession# when logging in through a graphical login manager like XDM). A third way is to use the new [.filename]#/usr/local/etc/fonts/local.conf# as demonstrated in <>. [[truetype]] === TrueType(R) Fonts Xorg has built in support for rendering TrueType(R) fonts. There are two different modules that can enable this functionality. The freetype module is used in this example because it is more consistent with the other font rendering back-ends. To enable the freetype module just add the following line to the `"Module"` section of [.filename]#/usr/local/etc/X11/xorg.conf.d/90-fonts.conf#. [.programlisting] .... Load "freetype" .... Now make a directory for the TrueType(R) fonts (for example, [.filename]#/usr/local/share/fonts/TrueType#) and copy all of the TrueType(R) fonts into this directory. Keep in mind that TrueType(R) fonts cannot be directly taken from an Apple(R) Mac(R); they must be in UNIX(R)/MS-DOS(R)/Windows(R) format for use by Xorg. Once the files have been copied into this directory, use mkfontscale to create a [.filename]#fonts.dir#, so that the X font renderer knows that these new files have been installed. `mkfontscale` can be installed as a package: [source,shell] .... # pkg install mkfontscale .... Then create an index of X font files in a directory: [source,shell] .... # cd /usr/local/share/fonts/TrueType # mkfontscale .... Now add the TrueType(R) directory to the font path. This is just the same as described in <>: [source,shell] .... % xset fp+ /usr/local/share/fonts/TrueType % xset fp rehash .... or add a `FontPath` line to [.filename]#xorg.conf#. Now Gimp, LibreOffice, and all of the other X applications should now recognize the installed TrueType(R) fonts. Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within LibreOffice) will look much better now. [[antialias]] === Anti-Aliased Fonts All fonts in Xorg that are found in [.filename]#/usr/local/share/fonts/# and [.filename]#~/.fonts/# are automatically made available for anti-aliasing to Xft-aware applications. Most recent applications are Xft-aware, including KDE, GNOME, and Firefox. To control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file [.filename]#/usr/local/etc/fonts/local.conf#. Several advanced features of the Xft font system can be tuned using this file; this section describes only some simple possibilities. For more details, please see man:fonts-conf[5]. This file must be in XML format. Pay careful attention to case, and make sure all tags are properly closed. The file begins with the usual XML header followed by a DOCTYPE definition, and then the `` tag: [.programlisting] .... .... As previously stated, all fonts in [.filename]#/usr/local/share/fonts/# as well as [.filename]#~/.fonts/# are already made available to Xft-aware applications. To add another directory outside of these two directory trees, add a line like this to [.filename]#/usr/local/etc/fonts/local.conf#: [.programlisting] .... /path/to/my/fonts .... After adding new fonts, and especially new font directories, rebuild the font caches: [source,shell] .... # fc-cache -f .... Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes "staircases" from large text, but can cause eyestrain if applied to normal text. To exclude font sizes smaller than 14 point from anti-aliasing, include these lines: [.programlisting] .... 14 false 14 false .... Spacing for some monospaced fonts might also be inappropriate with anti-aliasing. This seems to be an issue with KDE, in particular. One possible fix is to force the spacing for such fonts to be 100. Add these lines: [.programlisting] .... fixed mono console mono .... (this aliases the other common names for fixed fonts as `"mono"`), and then add: [.programlisting] .... mono 100 .... Certain fonts, such as Helvetica, may have a problem when anti-aliased. Usually this manifests itself as a font that seems cut in half vertically. At worst, it may cause applications to crash. To avoid this, consider adding the following to [.filename]#local.conf#: [.programlisting] .... Helvetica sans-serif .... After editing [.filename]#local.conf#, make certain to end the file with the `` tag. Not doing this will cause changes to be ignored. Users can add personalized settings by creating their own [.filename]#~/.config/fontconfig/fonts.conf#. This file uses the same `XML` format described above. One last point: with an LCD screen, sub-pixel sampling may be desired. This basically treats the (horizontally separated) red, green and blue components separately to improve the horizontal resolution; the results can be dramatic. To enable this, add the line somewhere in [.filename]#local.conf#: [.programlisting] .... unknown rgb .... [NOTE] ==== Depending on the sort of display, `rgb` may need to be changed to `bgr`, `vrgb` or `vbgr`: experiment and see which works best. ==== For more information about how to install and configure fonts on FreeBSD, please read the article link:{fonts}[Fonts and FreeBSD].