source: x/installing/xfree86.xml@ d7ac3b8

<?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;

  <!ENTITY xfree86-download-http "http://gnu.kookel.org/ftp/XFree86/&xfree86-version;/source/">
  <!ENTITY xfree86-download-ftp  "ftp://ftp.xfree86.org/pub/XFree86/&xfree86-version;/source/">
  <!ENTITY xfree86-md5sum        "ftp://ftp.xfree86.org/pub/XFree86/&xfree86-version;/source/SUMS.md5sum">
  <!ENTITY xfree86-size          "51 MB">
  <!ENTITY xfree86-buildsize     "740 MB">
  <!ENTITY xfree86-time          "12 SBU">
]>

<sect1 id="xfree86" xreflabel="XFree86">
  <?dbhtml filename="xfree86.html" ?>

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

  <title>XFree86-&xfree86-version;</title>

  <indexterm zone="xfree86">
    <primary sortas="a-xfree86">XFree86</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to XFree86</title>

    <para><application>XFree86</application> is a freely redistributable
    open-source implementation of the <application>X Window
    System</application>. <application>XFree86</application> provides a
    client/server interface between display hardware (the mouse, keyboard,
    and video displays) and the desktop environment, while also providing
    both the windowing infrastructure and a standardized application
    interface (API).</para>

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

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Required patch: <ulink
        url="&patch-root;/XFree86-&xfree86-version;-freetype_internals-1.patch"/></para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">XFree86 Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="libpng"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="linux-pam"/>; the
    following packages are included in the <application>XFree86</application>
    package, however they are updated more often than the
    <application>XFree86</application> package and are highly recommended:
    <xref linkend="expat"/>, <xref linkend="freetype2"/>,
    <xref linkend="fontconfig"/>.</para>

    <note>
      <para>If you choose not to install <application>expat</application>,
      <application>FreeType2</application>, and
      <application>Fontconfig</application>, the
      <filename>host.def</filename> file below will have to be modified to
      instruct <application>XFree86</application> to build them.</para>
    </note>

    <para condition="html" role="usernotes">User Notes:
    <ulink url='&blfs-wiki;/XFree86'/></para>

    <bridgehead renderas="sect3">Download Instructions</bridgehead>

    <para>There are several files that need to be fetched from the download
    location:</para>

    <itemizedlist spacing='compact'>
      <listitem>
        <para><filename>XFree86-&xfree86-version;-src-1.tgz</filename></para>
      </listitem>
      <listitem>
        <para><filename>XFree86-&xfree86-version;-src-2.tgz</filename></para>
      </listitem>
      <listitem>
        <para><filename>XFree86-&xfree86-version;-src-3.tgz</filename></para>
      </listitem>
      <listitem>
        <para><filename>XFree86-&xfree86-version;-src-4.tgz</filename></para>
      </listitem>
      <listitem>
        <para><filename>XFree86-&xfree86-version;-src-5.tgz</filename></para>
      </listitem>
      <listitem>
        <para><filename>XFree86-&xfree86-version;-src-6.tgz</filename></para>
      </listitem>
      <listitem>
        <para><filename>XFree86-&xfree86-version;-src-7.tgz</filename></para>
      </listitem>
    </itemizedlist>

    <para>The first three packages are the <application>XFree86</application>
    programs, the fourth and fifth are fonts, the sixth is normal documentation,
    and the seventh is hardcopy documentation.</para>

    <para>To check your downloads for integrity, download the
    <filename>SUMS.md5sum</filename> file. Then:</para>

<screen><userinput>md5sum -c SUMS.md5sum</userinput></screen>

    <para>The only errors you should see are for <filename>README</filename>,
    <filename>doctools-1.3.x.tgz</filename>, <filename>utils-1.1.x.tgz</filename>
    and <filename>XFree86-xtest-4.0.x.tar.bz2</filename> files if you did not
    download them.</para>

  </sect2>

  <sect2 role="kernel" id='xfree86-kernel'>
    <title>Kernel Configuration</title>

    <para>If you have an Intel P6 (Pentium Pro, Pentium II and later), it is
    recommended that you compile MTRR (Memory Type Range Registers) support
    into the kernel.  The kernel can map Cyrix and AMD CPUs to the MTRR
    interface, so selecting this option is useful for those processors also.
    This option is found in the "Processor type and features" menu. It can
    increase performance of image write operations 2.5 times or more on PCI
    or AGP video cards.</para>

    <indexterm zone="xfree86 xfree86-kernel">
      <primary sortas="d-xfree86">XFree86</primary>
    </indexterm>

    <para>In the "Character Devices" section, enable AGP Support and select
    the chipset support on your motherboard. If you do not know the chipset,
    you may select all the chip types at the expense of extra kernel size.
    You can usually determine your motherboard's chipset by running the
    command <command>lspci</command>, a program from the
    <xref linkend="pciutils"/> package.</para>

    <para>In the "Character Devices" section, <emphasis>disable</emphasis>
    Direct Rendering Manager unless you have a Direct Rendering Infrastructure
    (DRI) supported video card.  A complete list of DRI supported video cards
    can be found at <ulink url="http://dri.sourceforge.net" /> in the Status
    section. Currently, supported cards include those from 3dfx (Voodoo,
    Banshee), 3Dlabs, ATI (Rage Pro, Rage 128, Radeon 7X00, Radeon 2), Intel
    (i810, i815), and Matrox (G200, G400, G450).</para>

    <para>Additionally NVidia provides their own closed source binary drivers,
    which do not make use of DRI. If you intend to use these drivers, do not
    enable DRI.</para>

    <para>If you made any changes to the kernel configuration, recompile and
    install the new kernel.</para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of XFree86</title>

    <sect3>

      <title>Preparing the Sources</title>

      <para>Three fixes are needed for <application>XFree86</application>.
      First, a patch is needed to build against newer <application>FreeType</application>
      releases. Second, the macro "PAGE_MASK" is manually defined because
      including <filename>asm/page.h</filename> from the Linux kernel headers
      does not work when compiling with <parameter>-ansi</parameter>. Third,
      the Linux kernel headers no longer install the unneeded header
      <filename>linux/config.h</filename>. A <command>sed</command> is used
      to remove all usage of this header. Finally, one of the input drivers
      will not build with the <parameter>-ansi</parameter> setting, so the
      <application>GCC</application> default is restored. Perform these
      actions with the following commands:</para>

<screen><userinput>patch -Np1 -i ../XFree86-&xfree86-version;-freetype_internals-1.patch &amp;&amp;
sed -i '/page.h/c #define PAGE_MASK (~(getpagesize() - 1))' \
    programs/Xserver/hw/xfree86/fbdevhw/fbdevhw.c &amp;&amp;
grep -rl '^#include &lt;linux/config.h&gt;' . | \
    xargs sed -i '\@^#include &lt;linux/config.h&gt;@d' &amp;&amp;
echo 'CCOPTIONS += -std=gnu89' &gt;&gt; \
    programs/Xserver/hw/xfree86/input/ur98/Imakefile</userinput></screen>

    </sect3>

    <sect3>

      <title>Setting Up a Shadow Directory</title>

      <para>When building <application>XFree86</application>, you should create
      a shadow directory of symbolic links for the compiled code. To do that,
      first make <command>lndir</command>. Starting from the
      <filename class='directory'>xc</filename> directory:</para>

<screen><userinput>make -C config/util -f Makefile.ini lndir</userinput></screen>

      <para>Now create the shadow tree:</para>

<screen><userinput>mkdir ../xcbuild &amp;&amp;
cd ../xcbuild &amp;&amp;
../xc/config/util/lndir ../xc</userinput></screen>

    </sect3>

    <sect3>
      <title>Creating 'host.def'</title>

      <para>Although <application>XFree86</application> will compile without
      a <filename>host.def</filename> file, the following file is recommended
      for customizing the installation. Start from the
      <filename class="directory">xcbuild</filename> directory.</para>

      <note>
        <para>The <filename>host.def</filename> file is a
        <application>C</application> file, not the usual configuration file.
        If you make any changes, be sure the comment characters (/* and */)
        are balanced.  Most of the entries in the file below are commented
        out with the default settings shown.</para>
      </note>

<screen><userinput>cat &gt; config/cf/host.def &lt;&lt; "EOF"
<literal>/* Begin XFree86 host.def file */

/* COMPILER SETTINGS
 * The default compiler settings for x86 are shown below. These settings
 * and those for other architectures can be found in config/cf/xfree86.cf.
#define DefaultGcc2i386Opt  -O2 -fno-strength-reduce -fno-strict-aliasing
 */

/* INPUT DRIVERS
 * The build will pick the correct drivers for your platform, but a shorter
 * list can be defined to reduce compile time if they will not all be needed.
 * The list below shows the default input drivers from config/cf/xfree86.cf.
 *
#define XInputDrivers    mouse keyboard acecad calcomp citron \
                         digitaledge dmc dynapro elographics tek4957 \
                         microtouch mutouch penmount spaceorb summa \
                         wacom void magellan magictouch hyperpen \
                         jamstudio fpit palmax \
                         OSXInputDrivers ExtraXInputDrivers
 */

/* VIDEO DRIVERS
 * The build will pick the correct drivers for your platform, but a shorter
 * list can be defined to reduce compile time if they will not all be needed.
 * The list below shows the default input drivers from config/cf/xfree86.cf.
 *
#define XF86CardDrivers  mga glint nv tga s3 s3virge sis xgi rendition \
                         neomagic i740 tdfx savage cirrus vmware tseng \
                         trident chips aspeed apm GlideDriver i128 NscDriver \
                         ati i810 AgpGartDrivers DevelDrivers ark cyrix \
                         siliconmotion via fbdev vesa vga dummy \
                         XF86OSCardDrivers XF86ExtraCardDrivers
 */

/* SYSTEM LIBRARIES
 * These settings ensure we use our libraries. Comment them if you prefer to
 * use the versions shipped with XFree86.
 */
#define HasFreetype2        YES
#define HasFontconfig       YES
#define HasExpat            YES
#define HasLibpng           YES
#define HasZlib             YES

/* Use Linux-PAM with xdm
#define HasPam              YES
 */

/* GENERAL SETTINGS
 */
#define ManPath             /usr/share/man
#define DocDir              /usr/share/doc/xfree86-4.6.0

/* INSTALLATION PREFIX
 * The default is to install into /usr/X11R6. If you would like to install
 * into /usr, uncomment these options.
#define ProjectRoot         /usr
#define LinkGLToUsrLib      NO
#define LinkGLToUsrInclude  NO
 */

/* End XFree86 host.def file */</literal>
EOF</userinput></screen>

      <para>Edit the file for your hardware and desires. You can find more
      options by reading the other files in
      <filename class="directory">xc/config/cf</filename> and on the
      <ulink url='&blfs-wiki;/XFree86'>wiki</ulink>.</para>

    </sect3>

    <sect3>
      <title>Build Commands</title>

      <para>Install <application>XFree86</application> by running the
      following commands:</para>

<screen><userinput>( make World 2&gt;&amp;1 | tee xfree-compile.log &amp;&amp; exit $PIPESTATUS )</userinput></screen>

      <para>This package does not come with a test suite.</para>

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

<screen role="root"><userinput>make install install.man</userinput></screen>

      <para>If you installed <application>XFree86</application> into the default
      prefix, <filename class="directory">/usr/X11R6</filename>, make these
      symlinks to work around some applications which look for things in the
      wrong place. As <systemitem class="username">root</systemitem>:</para>

<screen role="root"><userinput>ln -v -s ../X11R6/bin /usr/bin/X11 &amp;&amp;
ln -v -s ../X11R6/lib/X11 /usr/lib/X11 &amp;&amp;
ln -v -s ../X11R6/include/X11 /usr/include/X11</userinput></screen>

      <para>The <application>XFree86</application> fonts have been installed
      outside of <application>Fontconfig</application>'s default search path
      of <filename class="directory">/usr/share/fonts</filename>. In order
      for <application>Fontconfig</application> to find the installed TrueType
      fonts, you should make symlinks to their directories. If you installed
      <application>XFree86</application> with the prefix
      <filename class="directory">/usr</filename>, omit /X11R6 from the
      following commands. As <systemitem class="username">root</systemitem>:
      </para>

<screen role="root"><userinput>install -d -m755 /usr/share/fonts &amp;&amp;
ln -svn /usr/X11R6/lib/X11/fonts/OTF /usr/share/fonts/X11-OTF &amp;&amp;
ln -svn /usr/X11R6/lib/X11/fonts/TTF /usr/share/fonts/X11-TTF</userinput></screen>

      <para><application>XFree86</application> installs the
      <application>XRender</application> and
      <application>XExtensions</application> extension libraries but does not
      install the corresponding <application>pkg-config</application> files.
      Create the files with these commands. If you installed
      <application>XFree86</application> with the prefix
      <filename class="directory">/usr</filename>, omit /X11R6 from the
      paths. As <systemitem class="username">root</systemitem>:</para>

<screen role="root"><userinput>cat &gt; /usr/X11R6/lib/pkgconfig/xrender.pc &lt;&lt; "EOF"
<literal>prefix=/usr/X11R6
exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include

Name: Xrender
Description: X Render Library
Version: 0.8.3
Cflags: -I${includedir} -I/usr/X11R6/include
Libs: -L${libdir} -lXrender  -L/usr/X11R6/lib -lX11</literal>

EOF

cat &gt; /usr/X11R6/lib/pkgconfig/xextensions.pc &lt;&lt; "EOF"
<literal>prefix=/usr/X11R6
exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include

Name: XExtensions
Description: Sundry X extension headers
Version: 1.0.1
Cflags: -I${includedir}</literal>

EOF</userinput></screen>

      <para>You should now continue on to the <xref linkend="x-setup"/> section
      to complete the configuration of
      <application>XFree86</application>.</para>

    </sect3>

  </sect2>

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

    <para><command>( make World 2&gt;&amp;1 | tee xfree-compile.log
      &amp;&amp; exit $PIPESTATUS )</command>:
    This command runs multiple <filename>Makefile</filename>s to completely
    rebuild the system. <option>2&gt;&amp;1</option>
    redirects error messages to the same location as standard output. The
    <command>tee</command> command allows viewing of the output while logging
    the results to a file. The parentheses around the command runs the entire
    command in a subshell and finally the <command>exit $PIPESTATUS</command>
    ensures the result of the <command>make</command> is returned as the result
    and not the result of the <command>tee</command> command.</para>

    <note>
      <para>When rebuilding <application>XFree86</application>, a separate
      command that may be used if only minor changes are made to the sources
      is <command>make Everything</command>. This does not automatically
      remove generated files and only rebuilds those files or programs that
      are out of date.</para>
    </note>

    <para><command>ln -v -s ...</command>: These commands are present to
    enable other (broken) packages to build against
    <application>XFree86</application>, even though the Filesystem Hierarchy
    Standard says: <quote>In general, software must not be installed or managed
    via the above symbolic links. They are intended for utilization by
    users only.</quote></para>

  </sect2>

  <sect2 id="xfree86-contents" role="content"
  xreflabel="XFree86 Contents and Descriptions">
    <title>Contents</title>

    <para>The <application>XFree86</application> package contains the
    <application>X Window System</application> for Linux (and other operating
    systems). It includes the <application>X</application> server, fonts,
    <command>xterm</command>, a simple window manager (<command>twm</command>),
    various utilities, video output drivers, and various input drivers
    including the mouse and keyboard.</para>

    <para><application>XFree86</application> also contains libraries and header
    files for development of the <application>X Window System</application>
    programs.</para>

    <note>
      <para>The following lists are not comprehensive. The full list of
      programs is (if you install into
      <filename class="directory">/usr/X11R6</filename>) in
      <filename class="directory">/usr/X11R6/bin</filename>.
      For additional information about these programs, see the respective
      man page.</para>
    </note>

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

      <seglistitem>
        <seg>XFree86, xf86config, xf86cfg, startx, xinit, twm, xterm,
        xwininfo, x11perf, xlsfonts, xvidtune, xload, xcalc, xclock,
        oclock, and xmodmap</seg>
        <seg>libGL.so, libGLU.so, libSM.so, libXi.so, libXrender.so,
        libXt.so, and libXfont.so</seg>
        <seg>/usr/X11R6/ and /etc/X11/</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="XFree86">
        <term><command>XFree86</command></term>
        <listitem>
          <para>is the X11R6 implementation of the <application>X Window
          System</application> server.</para>
          <indexterm zone="xfree86 XFree86">
            <primary sortas="b-XFree86">XFree86</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xf86config">
        <term><command>xf86config</command></term>
        <listitem>
          <para>is an interactive program for generating an
          <filename>XF86Config</filename> file for use with
          <application>XFree86</application> <application>X</application>
          servers.</para>
          <indexterm zone="xfree86 xf86config">
            <primary sortas="b-xf86config">xf86config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xf86cfg">
        <term><command>xf86cfg</command></term>
        <listitem>
          <para>is a tool to configure <application>XFree86</application>
          that can be used to either write the initial configuration file
          or make customizations to the current configuration.</para>
          <indexterm zone="xfree86 xf86cfg">
            <primary sortas="b-xf86cfg">xf86cfg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="startx">
        <term><command>startx</command></term>
        <listitem>
          <para>is a script to initialize the <application>X</application>
          session. It runs <command>xinit</command>.</para>
          <indexterm zone="xfree86 startx">
            <primary sortas="b-startx">startx</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xinit">
        <term><command>xinit</command></term>
        <listitem>
          <para>is used to start the <application>X Window
          System</application> server.</para>
          <indexterm zone="xfree86 xinit">
            <primary sortas="b-xinit">xinit</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="twm">
        <term><command>twm</command></term>
        <listitem>
          <para>(Tab Window Manager) is a window manager included with the
          <application>X Window System</application>.</para>
          <indexterm zone="xfree86 twm">
            <primary sortas="b-twm">twm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xterm">
        <term><command>xterm</command></term>
        <listitem>
          <para>is a terminal emulator for <application>X</application>.</para>
          <indexterm zone="xfree86 xterm">
            <primary sortas="b-xterm">xterm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xwininfo">
        <term><command>xwininfo</command></term>
        <listitem>
          <para>is a window information utility for
          <application>X</application>.</para>
          <indexterm zone="xfree86 xwininfo">
            <primary sortas="b-xwininfo">xwininfo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="x11perf">
        <term><command>x11perf</command></term>
        <listitem>
          <para>is an <application>X</application>11 server performance
          test program.</para>
          <indexterm zone="xfree86 x11perf">
            <primary sortas="b-x11perf">x11perf</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xlsfonts">
        <term><command>xlsfonts</command></term>
        <listitem>
          <para>is a program to list fonts available to the
          <application>X</application> server.</para>
          <indexterm zone="xfree86 xlsfonts">
            <primary sortas="b-xlsfonts">xlsfonts</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xvidtune">
        <term><command>xvidtune</command></term>
        <listitem>
          <para>is a video mode tuner for
          <application>XFree86</application>.</para>
          <indexterm zone="xfree86 xvidtune">
            <primary sortas="b-xvidtune">xvidtune</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xload">
        <term><command>xload</command></term>
        <listitem>
          <para> is a system load average display for
          <application>X</application>.</para>
          <indexterm zone="xfree86 xload">
            <primary sortas="b-xload">xload</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xcalc">
        <term><command>xcalc</command></term>
        <listitem>
          <para>is a scientific calculator for
          <application>X</application>.</para>
          <indexterm zone="xfree86 xcalc">
            <primary sortas="b-xcalc">xcalc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xclock">
        <term><command>xclock</command></term>
        <listitem>
          <para>is a clock programs for <application>X</application>.</para>
          <indexterm zone="xfree86 xclock">
            <primary sortas="b-xclock">xclock</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="oclock">
        <term><command>oclock</command></term>
        <listitem>
          <para>is a clock programs for <application>X</application>.</para>
          <indexterm zone="xfree86 oclock">
            <primary sortas="b-oclock">oclock</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xmodmap">
        <term><command>xmodmap</command></term>
        <listitem>
          <para>is a utility for modifying keymaps and pointer button
          mappings in <application>X</application>.</para>
          <indexterm zone="xfree86 xmodmap">
            <primary sortas="b-xmodmap">xmodmap</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>