source: x/installing/xorg-config.xml@ f38727d

<?xml version="1.0" encoding="ISO-8859-1"?>
<!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;
]>

<sect1 id="xorg-config">
  <?dbhtml filename="xorg-config.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Xorg-&xorg-version; Testing and Configuration</title>

  <indexterm zone="xorg-config">
    <primary sortas="g-configuring-xorg">Configuring Xorg</primary>
  </indexterm>

    <sect2 id='X11-testing' xreflabel="Testing Xorg">
    <title>Testing Xorg</title>
     
    <para>To test the <application>Xorg</application> installation, issue
    <userinput>startx</userinput>.  This command brings up a rudimentary window
    manager called <emphasis>twm</emphasis> with three xterm windows and one
    xclock window.  The xterm window in the upper left is a login terminal and
    running <emphasis>exit</emphasis> from this terminal will exit the
    <application>X Window</application> session.  The third xterm window may be
    obscured on your system by the other two xterms.</para>
    
    <para>Generally, there is no specific configuration required for
    <application>Xorg</application>, but customization is possible.  For details 
    see <xref linkend='xconfig'/> below.</para>

    </sect2>

    <sect2 role="configuration" id="checking-dri" xreflabel="Checking the DRI installation">
    <title>Checking the Direct Rendering Infrastructure (DRI) Installation</title>

    <para>
      DRI is a framework for allowing software to access graphics hardware in a safe and
      efficient manner. It is installed in <application>X</application> by default
      (using <application>MesaLib</application>) if you have a supported video card.
    </para>

    <para>
      To check if DRI drivers are installed properly, check the log file
      <filename>/var/log/Xorg.0.log</filename> for statements like:
    </para>

<screen><literal>(II) intel(0): direct rendering: DRI2 Enabled</literal></screen>

    <note>
      <para>
        DRI configuration may differ if you are using alternate drivers, such
        as those from
        <ulink url="http://www.nvidia.com/page/home.html">NVIDIA</ulink> or
        <ulink url="http://www.ati.com/">ATI</ulink>.
      </para>
    </note>

    <para>
      Although all users can use software acceleration, any hardware acceleration (DRI2)
      is only available to <systemitem class="username">root</systemitem> and members
      of the <systemitem class="groupname">video</systemitem> group.
    </para>

    <para>
      To see if hardware acceleration is available for your driver, look in
      <filename>/var/log/Xorg.0.log</filename> for statements like:
    </para>

<screen><literal>(II) intel(0): direct rendering: DRI2 Enabled</literal></screen>

    <para>
      If your driver is supported, add any users that might use X to that group:
    </para>

<screen role="root"><userinput>usermod -a -G video <replaceable>&lt;username&gt;</replaceable></userinput></screen>

    <para>
      If you have installed two OpenGL demo programs when you installed
      <xref linkend="mesalib"/>, from an X terminal, run <command>glxinfo</command>
      and look for the phrase:
    </para>

<screen><computeroutput>name of display: :0
display: :0  screen: 0
direct rendering: Yes</computeroutput></screen>

    <para>
      If direct rendering is enabled, you can add verbosity by running
      <command>LIBGL_DEBUG=verbose glxinfo</command>. This will show the drivers,
      device nodes and files used by the DRI system.
    </para>

    <para>
      If DRI2 is enabled, to confirm that DRI2 hardware acceleration is working you can
      (still in the X terminal) run the command
      <command>glxinfo | egrep "(OpenGL vendor|OpenGL renderer|OpenGL version)"</command>
      - if that reports something <emphasis>other than</emphasis>
      <literal>Software Rasterizer</literal> then you have working acceleration for the
      user who ran the command.
    </para>

    <para>
      If your hardware does not have any DRI2 driver available, it will use Software Rasterizer
      for Direct Rendering. In such cases, it is recommended that you use new, LLVM-accelerated,
      Software Rasterizer called LLVMPipe. In order to build LLVMPipe just make sure that
      <xref linkend="llvm"/> is present at MesaLib build time. Please note that all decoding is
      done on CPU instead of GPU, so expect that things run slower. To check if you are using
      LLVMpipe, run
      <command>glxinfo | egrep "(OpenGL vendor|OpenGL renderer|OpenGL version)"</command>.
      An example output is shown below:
    </para>

<screen><computeroutput>OpenGL vendor string: VMware, Inc.
OpenGL renderer string: Gallium 0.4 on llvmpipe (LLVM 3.2, 256 bits)
OpenGL version string: 2.1 Mesa 9.1-devel (git-cb3b172)</computeroutput></screen>

    <para>
      You can always force LLVMPipe by exporting <envar>LIBGL_ALWAYS_SOFTWARE=1</envar>
      environment variable.
    </para>

    <para>
      Again, if you have built Mesa OpenGL demos, you can also run the test program
      <command>glxgears</command>. This program brings up a window with three gears
      turning. The X terminal will display how many frames were drawn every five
      seconds, so this is a reasonable benchmark. The window is scalable, and the
      frames drawn per second is highly dependent on the size of the window. On some
      hardware, <command>glxgears</command> will run synchronized to vertical refresh
      and framerate will be approximately the same as the monitor refresh rate.
    </para>

    </sect2>

    <sect2 role="configuration" id="hybrid-graphics" xreflabel="Hybrid Graphics">
    <title>Hybrid Graphics</title>

    <para>
      Hybrid Graphics is still in experimental state for Linux. Xorg Developers have
      developed a technology called PRIME that can be used for switching between
      integrated and muxless discrete GPU at will. Automatic switching is not
      possible at the moment.
    </para>

    <para>
      In order to use PRIME for GPU switching, make sure that you are using Linux
      Kernel 3.4 or later (recommended). You will need latest DRI and DDX drivers
      for your hardware and <application>Xorg Server</application> 1.13 with an
      optional patch applied.
    </para>

    <para>
      <application>Xorg Server</application> should load both GPU drivers automaticaly.
      In order to run a GLX application on a discrete GPU, you will need to export
      <envar>DRI_PRIME=1</envar> environment variable. For example,
      
<screen><userinput>DRI_PRIME=1 glxinfo | egrep "(OpenGL vendor|OpenGL renderer|OpenGL version)"</userinput></screen>

      will show OpenGL vendor, renderer and version for the discrete GPU.
    </para>

    <para>
      If the last command reports same OpenGL renderer with and without <envar>DRI_PRIME=1</envar>,
      you will need to check your installation.
    </para>

    </sect2>

<!--
    <sect2 role="configuration" id='X11R6-compat-symlink'
         xreflabel="Creating an X11R6 Compatibility Symlink">

    <title>Creating an X11R6 Compatibility Symlink</title>

    <para>Until recently (relatively speaking) almost every
    <application>X Window</application> installation you performed or came
    across was installed in the
    <filename class='directory'>/usr/X11R6</filename> directory. That was the
    standard for years. Developers picked up on this and wrote their package
    installation scripts looking for <application>X</application> in the
    standard location. Things have changed and the trend is to now install
    <application>X</application> in
    <filename class='directory'>/usr</filename>. Some people want to install
    it in a custom location.</para>

    <para>Many package developers have not caught up to the change and their
    packages are still trying to find <application>X</application> in
    <filename class='directory'>/usr/X11R6</filename> and subsequently fail
    when you try to build the package. Though for most packages it is not
    difficult to 'hack' the installation script to fix the problem, that is not
    the long term solution to the problem. Upstream developers need to modernize
    their installation scripts and eliminate the problem altogether.</para>

    <para>Until then, you can create a symbolic link to satisfy the
    <filename class='directory'>/usr/X11R6</filename> requirement so that you
    won't be inconvenienced with a package build failure due to this known
    issue. If you wish to create the symlink, issue the following command as
    the <systemitem class="username">root</systemitem>:</para>

<screen role="root"><userinput>ln -vsf $XORG_PREFIX /usr/X11R6</userinput></screen>

    </sect2>
-->

    <sect2 role="configuration" id="xft-font-protocol"  xreflabel="Xft Font Protocol">
      <title>Xft Font Protocol</title>

      <indexterm zone="xft-font-protocol" id="fonts">
        <primary sortas="g-truetype">TrueType Fonts</primary>
      </indexterm>

      <para>Xft provides antialiased font rendering through
      <application>Freetype</application>, and fonts are controlled from the
      client side using <application>Fontconfig</application>.  The default
      search path is <filename class="directory">/usr/share/fonts</filename>
      and <filename class="directory">~/.fonts</filename>.
      <application>Fontconfig</application> searches directories in its
      path recursively and maintains a cache of the font characteristics in
      <filename>fonts.cache-1</filename> files in each directory.  If the cache
      appears to be out of date, it is ignored, and information is (slowly)
      fetched from the fonts themselves.  This cache
      can be regenerated using the <command>fc-cache</command> command at any
      time. You can see the list of fonts known by
      <application>Fontconfig</application> by running the command
      <command>fc-list</command>.</para>

      <para>If you've installed <application>Xorg</application> in any prefix
      other than <filename class="directory">/usr</filename>, the
      <application>X</application> fonts were not installed in a
      location known to <application>Fontconfig</application>. This prevents
      <application>Fontconfig</application> from using the poorly rendered
      Type 1 fonts or the non-scalable bitmapped fonts. Symlinks were created
      from the <filename class="directory">OTF</filename> and <filename
      class="directory">TTF</filename> <application>X</application> font
      directories to <filename
      class="directory">/usr/share/fonts/X11-{OTF,TTF}</filename>. This allows
      <application>Fontconfig</application> to use the OpenType and TrueType
      fonts provided by <application>X</application> (which are scalable and
      of higher quality).</para>

      <para><application>Fontconfig</application> uses names such as
      "Monospace 12" to define fonts.  Applications generally use generic font
      names such as "Monospace", "Sans" and "Serif".
      <application>Fontconfig</application> resolves these names to a font that
      has all characters that cover the orthography of the language indicated
      by the locale settings.  Knowledge of these font names is included in
      <filename>/etc/fonts/fonts.conf</filename>. Fonts that are not listed
      in this file are still usable by <application>Fontconfig</application>,
      but they will not be accessible by the generic family names.</para>

      <para>Standard scalable fonts that come with <application>X</application>
      provide very poor Unicode coverage.  You may notice in applications that
      use <application>Xft</application> that some characters appear as a box
      with four binary digits inside.  In this case, a font set with the
      available glyphs has not been found.  Other times, applications that
      don't use other font families by default and don't accept substitutions
      from <application>Fontconfig</application> will display blank lines when
      the default font doesn't cover the orthography of the user's language.
      This happens, e.g., with <application>Fluxbox</application> in the
      ru_RU.KOI8-R locale.</para>

      <para>In order to provide greater Unicode coverage, it is recommended
      that you install these fonts:</para>

      <itemizedlist>
        <listitem>
          <para><ulink url="http://dejavu.sourceforge.net/">DejaVu fonts</ulink>
          - These fonts are replacements for the Bitstream Vera fonts and
          provide Latin-based scripts with accents and Cyrillic glyphs.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://download.savannah.nongnu.org/releases/freefont/">FreeFont</ulink>
          - This set of fonts covers nearly every non-CJK character, but is not
          visually pleasing.  <application>Fontconfig</application> will use it
          as a last resort to substitute generic font family names.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://corefonts.sourceforge.net/">Microsoft Core fonts</ulink>
          - These fonts provide slightly worse Unicode coverage than FreeFont,
          but are better hinted.  Be sure to read the license before using
          them. These fonts are listed in the aliases in the 
          <filename class="directory">/etc/fonts/fonts.d</filename> directory
          by default.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://cle.linux.org.tw/fonts/FireFly">Firefly New Sung font</ulink>
          - This font provides Chinese coverage. This font is listed in the
          aliases in the
          the <filename class="directory">/etc/fonts/fonts.d</filename>
          directory by default.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://cle.linux.org.tw/fonts/Arphic">Arphic fonts</ulink> -
          A similar set of Chinese fonts to the Firefly New Sung font.
          These fonts are listed in the aliases in the
          <filename class="directory">/etc/fonts/fonts.d</filename> directory
          by default.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://sourceforge.jp/projects/efont/">Kochi fonts</ulink> -
          These provide Japanese characters, and are listed in the aliases
          in the <filename class="directory">/etc/fonts/fonts.d</filename>
          directory by default.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://kldp.net/projects/baekmuk/">Baekmuk fonts</ulink>
          - These fonts provide Korean coverage, and are listed in the
          aliases in the
          <filename class="directory">/etc/fonts/fonts.d</filename> directory
          by default.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="&gnome-download-http;/cantarell-fonts/0.0/">Cantarell fonts</ulink>
          - The Cantarell typeface family provides a contemporary Humanist sans
          serif. It is particularly optimised for legibility at small sizes and is
          the preferred font family for the <application>GNOME-3</application> user
          interface.</para>
        </listitem>
      </itemizedlist>

      <para>The list above will not provide complete Unicode coverage.  For
      more information, please visit the <ulink
      url="http://unifont.org/fontguide/">Unicode Font Guide</ulink>.</para>

      <para>As an example, consider the installation of the DejaVu fonts.  From
      the unpacked source directory, run the following commands as the
      <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -d -m755 /usr/share/fonts/dejavu &amp;&amp;
install -v -m644 *.ttf /usr/share/fonts/dejavu &amp;&amp;
fc-cache -v /usr/share/fonts/dejavu</userinput></screen>

    </sect2>

  <sect2 role="configuration" id='xconfig'>
    <title>Setting up Xorg Devices</title>
    <para>For most hardware configurations, modern Xorg will automatically
    get the server configuration correct without any user intervention. There
    are, however, some cases where auto-configuration will be incorrect.
    Following are some example manual configuration items that may be of use in
    these instances.</para>

    <sect3 id="xinput">
    <title>Setting up X Input Devices</title>
    <para>For most input devices, no additional configuration will be
    necessary.  This section is provided for informational purposes only.</para>
    
    <para>A sample default XKB setup could look like the following (executed as
    the <systemitem class="username">root</systemitem> user):</para>
<screen><userinput role="username">cat &gt; /etc/X11/xorg.conf.d/xkb-defaults.conf &lt;&lt; "EOF"
Section "InputClass"
    Identifier "XKB Defaults"
    MatchIsKeyboard "yes"
    Option "XkbOptions" "terminate:ctrl_alt_bksp"
EOF</userinput></screen>

  </sect3>

  <sect3 id="xdisplay">
  <title>Fine Tuning Display Settings</title>
  <para>Again, with modern Xorg, little or no additional configuration is
  necessary. If you should need extra options passed to your video driver,
  for instance, you could use something like the following (again, executed as
  the <systemitem class="username">root</systemitem> user):</para>

<screen><userinput role="root">cat &gt; /etc/X11/xorg.conf.d/videocard-0.conf &lt;&lt; "EOF"
Section "Device"
    Identifier  "Videocard0"
    Driver      "radeon"
    VendorName  "Videocard vendor"
    BoardName   "ATI Radeon 7500"
    Option      "NoAccel" "true"
EndSection
EOF</userinput></screen>

  <para>Another common setup is having multiple server layouts for use in
  different environments. Though the server will automatically detect the
  presence of another monitor, it may get the order incorrect:</para>

<screen><userinput role="root">cat &gt; /etc/X11/xorg.conf.d/server-layout.conf &lt;&lt; "EOF"
Section "ServerLayout"
    Identifier     "DefaultLayout"
    Screen      0  "Screen0" 0 0
    Screen      1  "Screen1" LeftOf "Screen0"
    Option         "Xinerama"
EndSection
EOF</userinput></screen>

  </sect3>
  </sect2>
</sect1>