source: x/installing/xorg-server.xml@ 7c83169b

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY xorg-server-download-http "&xorg-download-http;/xserver/xorg-server-&xorg-server-version;.tar.xz">
  <!ENTITY xorg-server-download-ftp  " ">
  <!ENTITY xorg-server-md5sum        "69dbed93746d0af6b46de76d711614e4">
  <!ENTITY xorg-server-size          "4.7 MB">
  <!ENTITY xorg-server-buildsize     "147 MB (with tests)">
  <!ENTITY xorg-server-time          "0.3 SBU (using parallelism=4; with tests)">
  <!ENTITY modesetting_drv
           "<filename class='libraryfile'>modesetting_drv</filename>">
  <!ENTITY BLFS113 "https://www.linuxfromscratch.org/blfs/view/11.3/x/x7driver.html">
  <!ENTITY BLFS76 "https://www.linuxfromscratch.org/blfs/view/7.6/x/x7driver.html">
]>

<sect1 id="xorg-server" xreflabel="Xorg-Server-&xorg-server-version;">
  <?dbhtml filename="xorg-server.html"?>


  <title>Xorg-Server-&xorg-server-version;</title>

  <indexterm zone="xorg-server">
    <primary sortas="a-xorg-server">xorg-server</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Xorg Server</title>

    <para>
      The <application>Xorg</application> Server is the core
      of the X Window system.
    </para>

    &lfs121_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&xorg-server-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&xorg-server-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &xorg-server-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &xorg-server-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &xorg-server-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &xorg-server-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          With the removal of the xf86-video-* drivers, the TearFree option
          is no longer functional. To work around this, upstream has added the
          TearFree option to the default modesetting driver. This patch
          backports this feature. Apply this patch if you are going to use Xorg
          in an environment without a compositor (such as TWM, IceWM, Openbox,
          or Fluxbox).
        </para>
        <para>
          Optional patch:
          <ulink url="&patch-root;/xorg-server-&xorg-server-version;-tearfree_backport-2.patch"/>
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Xorg Server Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="libxcvt"/>,
      <xref linkend="pixman"/>,
      <xref linkend="xorg7-font"/> (only font-util), and at runtime:
      <xref role="runtime" linkend="xkeyboard-config"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <phrase revision="sysv"><xref linkend='dbus'/>,
      <xref role="runtime" linkend="elogind"/> (runtime;
      <systemitem class='library'>libelogind</systemitem> also referred
      at build time but it's not really useful),</phrase>
      <xref linkend="libepoxy"/> (needed for glamor),
      <xref linkend="libtirpc"/>,
      <phrase revision="systemd"><xref role="runtime"
                                       linkend="systemd"/> (runtime),</phrase>
      and <xref role='runtime' linkend='xorg-libinput-driver'/> (runtime)
    </para>

    <!-- TODO: Add -Dsystemd_logind=yes explicitly (like -Dglamor=true) to
         make this more clear for BLFS 12.2.  Now (Feb 16 2024) this package
         is already under 12.1 freeze. -->
    <note>
      <para>
        Although it's possible to<phrase revision='sysv'> build this package
        without <xref linkend='dbus'/> installed or</phrase> run the Xorg
        server without
        <phrase revision='sysv'><xref linkend='elogind'/></phrase><phrase
        revision='systemd'><xref linkend='systemd'/>
        (rebuilt with PAM)</phrase> functioning, it would require running
        the Xorg server as the &root; user or Xorg server will malfunction
        or even fail to start.  The BLFS editors strongly discourage
        skipping <phrase revision='sysv'>these two
        dependencies</phrase><phrase revision='systemd'>this
        dependency</phrase>.  Do not attempt to do so unless you really know
        what you are doing.
      </para>
    </note>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref role="runtime" linkend="acpid"/> (runtime),
      <xref linkend="doxygen"/> (to build API documentation),
      <xref linkend="fop"/> (to build documentation),
      <xref linkend="libunwind"/>,
      <xref linkend="nettle"/>,
      <xref linkend="libgcrypt"/>,
      <xref linkend="xcb-util-keysyms"/>,
      <xref linkend="xcb-util-image"/>,
      <xref linkend="xcb-util-renderutil"/>,
      <xref linkend="xcb-util-wm"/> (all four to build Xephyr),
      <xref linkend="xmlto"/> (to build documentation),
      <xref linkend="xkeyboard-config"/> (for tests),
      <ulink url="https://gitlab.freedesktop.org/xorg/test/rendercheck">rendercheck</ulink> (for tests), and
      <ulink url="https://www.x.org/archive/individual/doc/">xorg-sgml-doctools</ulink> (to build documentation)
    </para>
  </sect2>

  <sect2 role="kernel" id="xorg-server-kernel">
    <title>Kernel Configuration</title>

    <para>
      The traditional Device Dependent X (DDX) drivers have been removed
      from BLFS in favor of the &modesetting_drv; driver which will be
      built as a part of this package.  To use the &modesetting_drv; driver,
      the kernel must provide a Direct Rendering Manager (DRM) driver for
      your GPU.
    </para>

    <para>
      If your GPU supports 3D acceleration and <xref linkend='mesa'/>
      provides a Gallium3D driver for utilizing its 3D capability, you
      should have already enabled the necessary kernel configuration options
      in <xref linkend='mesa-kernel'/>.  Otherwise, you need to find the
      kernel configuration option of the DRM driver for the GPU and enable
      it.  Notably, the virtual GPUs provided by some virtual machine
      managers:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="xorg-server-kernel.xml"/>

    <para>
      If the kernel does not provide a DRM driver for your GPU, on most x86
      systems the <quote>simple frame buffer</quote> DRM driver running on
      VESA or UEFI frame buffer can be used as a fallback.  Enable the
      following options in the kernel configurations if you don't have a
      dedicated DRM driver for the GPU, or you want to keep the simple
      frame buffer driver as a fallback in case the dedicated driver fails:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="xorg-server-simpledrm-kernel.xml"/>

    <para>
      To allow the kernel to print debug messages at an early boot stage,
      <option>CONFIG_DRM</option> and <option>CONFIG_DRM_SIMPLEDRM</option>
      should not be built as kernel modules unless an initramfs will be
      used.
    </para>

    <para>
      If you want to use the simple frame buffer driver on a system booted
      via BIOS (instead of UEFI), add the following line before the first
      <literal>menuentry</literal> block in the
      <filename>/boot/grub/grub.cfg</filename> file to initialize the VESA
      frame buffer:
    </para>

<screen><literal>set gfxpayload=<replaceable>1024x768x32</replaceable></literal></screen>

    <para>
      You may replace <literal>1024</literal>, <literal>768</literal>, and
      <literal>32</literal> with a resolution and color depth setting
      suitable for your monitor.
    </para>

    <para>
      If all of these DRM drivers do not work for you and you need to use
      a DDX driver with a non-DRM kernel GPU driver (usually named
      <option>CONFIG_FB_*</option> in the kernel configuration, or existing
      as out-tree kernel modules), or you need an device specific
      functionality requiring a DDX driver, consult
      <ulink url="&BLFS113;">a prior version of BLFS</ulink>, or
      <ulink url="&BLFS76;">an even earlier prior version</ulink> for more DDX
      drivers.
    </para>

    <indexterm zone="xorg-server xorg-server-kernel">
      <primary sortas="d-xorg-server">xorg-server</primary>
    </indexterm>
  </sect2>

  <sect2 role="installation">
    <title>Installation of Xorg Server</title>

    <para>
      First, if you need the TearFree option to work around screen tearing,
      apply the backported patch:
    </para>

<screen><userinput remap="pre">patch -Np1 -i ../xorg-server-&xorg-server-version;-tearfree_backport-2.patch</userinput></screen>

    <para>
      Install the server by running the following commands:
    </para>

    <!-- To editors: Ironically -D systemd_logind=true shows up only for
         **sysv** revision.  No it's not a bug.  It's used to make the
         building system error out when dbus is not installed and emphasis
         that we don't support a configuration lacking a recommended
         dependency.  On systemd dbus is installed in LFS.  Despite the
         naming, it controls elogind support as well.

         It's harmless to have this option for systemd revision as well
         but I cannot figure out how to write it up in the Explanations
         section for systemd revision, so just omit it for systemd
         revision.  -->

<screen revision='sysv'><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup ..               \
      --prefix=$XORG_PREFIX  \
      --localstatedir=/var   \
      -D glamor=true         \
      -D systemd_logind=true \
      -D xkb_output_dir=/var/lib/xkb &amp;&amp;
ninja</userinput></screen>

<screen revision='systemd'><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup ..              \
      --prefix=$XORG_PREFIX \
      --localstatedir=/var  \
      -D glamor=true        \
      -D xkb_output_dir=/var/lib/xkb &amp;&amp;
ninja</userinput></screen>

    <para>
      To test the results, issue: <command>ninja test</command>. You
      will need to run <command>ldconfig</command> as the <systemitem
      class="username">root</systemitem> user first or some tests may fail.
    </para>

    <para>
      Now as the <systemitem class="username">root</systemitem>
      user:
    </para>

<screen role="root" revision="sysv"><userinput>ninja install &amp;&amp;
mkdir -pv /etc/X11/xorg.conf.d &amp;&amp;
install -v -d -m1777 /tmp/.{ICE,X11}-unix &amp;&amp;
cat &gt;&gt; /etc/sysconfig/createfiles &lt;&lt; "EOF"
<literal>/tmp/.ICE-unix dir 1777 root root
/tmp/.X11-unix dir 1777 root root</literal>
EOF</userinput></screen>

<screen role="root" revision="systemd"><userinput>ninja install &amp;&amp;
mkdir -pv /etc/X11/xorg.conf.d</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <parameter>-D glamor=true</parameter>: Ensure building the Glamor
      module.  It's needed to build the &modesetting_drv; driver
      which replaces the traditional Device Dependent X (DDX) drivers.
    </para>

    <para revision='sysv'>
      <option>-D systemd_logind=true</option>:
      This switch makes the building system error out if
      <xref linkend='dbus'/> is not installed.  The BLFS editors discourage
      building this package without <xref linkend='dbus'/> installed.
    </para>

    <para>
      <option>-D suid_wrapper=true</option>: Builds the suid-root
      wrapper for legacy DDX driver support on rootless xserver systems.
    </para>

    <para revision="sysv">
      <command>cat &gt;&gt; /etc/sysconfig/createfiles...</command>: This
      command creates the <filename class="directory">/tmp/.ICE-unix</filename>
      and <filename class="directory">/tmp/.X11-unix</filename> directories at
      startup, and ensures that the permissions and ownership are correct as
      required by the server.
    </para>

    <para>
      <option>-D xephyr=true</option>: This option allows building Xephyr if its
      dependencies are met.
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          gtf, X, Xnest, Xorg, Xvfb, and optionally Xephyr
        </seg>
        <seg>
          several under $XORG_PREFIX/lib/xorg/modules/ including the
          &modesetting_drv; driver
        </seg>
        <seg>
          /etc/X11/xorg.conf.d,
          $XORG_PREFIX/include/xorg,
          $XORG_PREFIX/lib/xorg, and
          $XORG_PREFIX/share/X11/xorg.conf.d
        </seg>

      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="gtf-x7">
        <term><command>gtf</command></term>
        <listitem>
          <para>
            calculates VESA GTF mode lines
          </para>
          <indexterm zone="xorg-server gtf-x7">
            <primary sortas="b-gtf">gtf</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="X-x7">
        <term><command>X</command></term>
        <listitem>
          <para>
            is a symbolic link to Xorg
          </para>
          <indexterm zone="xorg-server X-x7">
            <primary sortas="b-X">X</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="Xephyr-x7">
        <term><command>Xephyr</command></term>
        <listitem>
          <para>
            is a nested X server which supports modern X extensions
          </para>
          <indexterm zone="xorg-server Xephyr-x7">
            <primary sortas="b-Xephyr">Xephyr</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="Xnest-x7">
        <term><command>Xnest</command></term>
        <listitem>
          <para>
            is a nested X server
          </para>
          <indexterm zone="xorg-server Xnest-x7">
            <primary sortas="b-Xnest">Xnest</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="Xorg-x7">
        <term><command>Xorg</command></term>
        <listitem>
          <para>
            is the X11R7 X Server
          </para>
          <indexterm zone="xorg-server Xorg-x7">
            <primary sortas="b-Xorg">Xorg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="Xvfb-x7">
        <term><command>Xvfb</command></term>
        <listitem>
          <para>
            is the virtual framebuffer X server for X Version 11
          </para>
          <indexterm zone="xorg-server Xvfb-x7">
            <primary sortas="b-Xvfb">Xvfb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="modesetting_drv-x7">
        <term><filename class="libraryfile">modesetting_drv.so</filename></term>
        <listitem>
          <para>
            provides a video driver for machines using Kernel Mode Setting (KMS).
            This will use glamor if that has been enabled and the hardware offers
            acceleration
          </para>
          <indexterm zone="xorg-server modesetting_drv-x7">
            <primary sortas="c-modesetting_drv">modesetting_drv.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>