source: x/installing/xorg.xml@ 6473e74

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

  <!ENTITY xorg-download-http "http://xorg.freedesktop.org/releases/X11R&xorg-version;/src-single/X11R&xorg-version;-src.tar.bz2 ">
  <!ENTITY xorg-download-ftp  "ftp://expo.x.org/pub/X11R&xorg-version;/src-single/X11R&xorg-version;-src.tar.bz2">
  <!ENTITY xorg-md5sum        "52ad69832db5c36c7041f90625ed4598">
  <!ENTITY xorg-size          "45 MB">
  <!ENTITY xorg-buildsize     "864 MB">
  <!ENTITY xorg-time          "11.68 SBU">
]>

<sect1 id="xorg" xreflabel="X.org-&xorg-version;">
  <?dbhtml filename="xorg.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
    <keywordset>
      <keyword role="package">X11R&xorg-version;-src.tar</keyword>
      <keyword role="ftpdir">Xorg</keyword>
    </keywordset>
  </sect1info>

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

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

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

    <note>
      <para>There are three packages in BLFS that implement the <application>X
      Window System</application>: <application>Xorg</application> 
      (X11R6 and X11R7) and  <application>XFree86</application>. These 
      packages are all quite similar.  In fact, the base system of 
      <application>Xorg</application> is 
      <application>XFree86</application>-4.4.0RC2. Licensing was the original
      reason for the split.  <application>Xorg-&xorg7-version;</application>
      introduces a completely autotooled build system, but is otherwise the
      same codebase as <application>Xorg-&xorg-version;</application>. 
      Most large commercial distributions have decided to use the
      <application>Xorg</application> package, but several still provide
      <application>XFree86</application>.</para>

      <para>A second reason for the forking of <application>X</application>
      packages is the stated goals of the developers. Some developers were
      unhappy with the administration and progress of
      <application>XFree86</application>. X.org's future plans include
      significant improvements to the internals of the system and more 
      frequent releases.</para>

      <para><application>XFree86</application> continues to be a solid,
      conservative application with excellent driver support.</para>

    </note>

    <para><application>Xorg</application> is a freely redistributable open-source
    implementation of the <application>X</application> Window System. This
    system 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="&xorg-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&xorg-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &xorg-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &xorg-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &xorg-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &xorg-time;</para>
      </listitem>
    </itemizedlist>

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

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

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

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="linux-pam"/></para>

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

    <para>As an alternative to downloading the entire source tree in a single
    file, there are several, smaller files that can be fetched from the 
    download location (directory /pub/X11R&xorg-version;/src/):</para>

    <itemizedlist spacing='compact'>
      <listitem>
        <para><filename>X11R&xorg-version;-src1.tar.gz</filename></para>
      </listitem>
      <listitem>
        <para><filename>X11R&xorg-version;-src2.tar.gz</filename></para>
      </listitem>
      <listitem>
        <para><filename>X11R&xorg-version;-src3.tar.gz</filename></para>
      </listitem>
      <listitem>
        <para><filename>X11R&xorg-version;-src4.tar.gz</filename></para>
      </listitem>
      <listitem>
        <para><filename>X11R&xorg-version;-src5.tar.gz</filename></para>
      </listitem>
      <listitem>
        <para><filename>X11R&xorg-version;-src6.tar.gz</filename></para>
      </listitem>
      <listitem>
        <para><filename>X11R&xorg-version;-src7.tar.gz</filename></para>
      </listitem>
    </itemizedlist>

    <para>The first package contains the <application>Xorg</application>
    libraries and support programs, the second contains standard
    <application>X</application> programs, the third contains the
    <application>X</application> server, the fourth and fifth are fonts,
    the sixth is normal documentation, and the seventh is hardcopy
    documentation.</para>

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

<screen><userinput>md5sum -c md5sums</userinput></screen>

    <para>The package (or all seven packages) should give an OK status.</para>

  </sect2>

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

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

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

    <para>In the "Character Devices" section of the "Device Drivers" menu,
    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 Xorg</title>

    <sect3>
      <title>Various build fixes</title>

      <para>The <application>Xorg</application> sources must be patched in
      order to avoid a race condition with the <application>luit</application>
      program.  Additionally, recent <application>glibc</application> requires
      <filename>linux/types.h</filename> to be included prior to 
      <filename>asm/types.h</filename>.  Fix both issues with the following 
      commands:</para>

<screen><userinput>patch -Np1 -i ../X11R&xorg-version;-luit_race-1.patch &amp;&amp;
sed -i "s@*/@*/\n#include &lt;linux/types.h&gt;\n@" \
    programs/Xserver/hw/xfree86/os-support/linux/lnx_agp.c</userinput></screen>

      <para>Additionally, if you choose to install 
      <application>Xorg</application> to any prefix other than 
      <filename class="directory">/usr/X11R6</filename>, the luit package
      needs another correction to fix a hard coded path.  Execute the 
      following command:</para>

<screen><userinput>sed -i 's@/usr/X11R6@<replaceable>[/usr]</replaceable>@' programs/luit/parser.h</userinput></screen>

    </sect3>

    <sect3>
      <title>Suppressing Xprint-related Modification to '/etc'</title>

      <para><application>Xorg</application> insists on putting
      its boot and profile scripts into the <filename
      class="directory">/etc</filename> directory even if specifically told
      not to compile anything Xprint server or client related (see
      <filename>host.def</filename> below). The following command will
      suppress any such modifications:</para>

<screen><userinput>sed -i '/^SUBDIRS =/s/ etc$//' programs/Xserver/Xprint/Imakefile</userinput></screen>

    </sect3>

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

      <para>When building <application>Xorg</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>pushd config/util &amp;&amp;
make -f Makefile.ini lndir
popd</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>The next step is to create the
      <filename>config/cf/host.def</filename> file. The documentation for
      <application>Xorg</application> indicates that the application will
      build without a <filename>host.def</filename> file, but the included
      libraries for <application>Fontconfig</application> and
      <application>FreeType2</application> do not build properly on a base
      LFS system. Therefore, you must specify that these libraries, as well
      as others, should be imported from the system.</para>

      <note>
        <para><filename>config/cf/host.def</filename> is a C file, not a
        shell script. Ensure the comments delimited by /* ... */ are balanced
        when modifying the file.</para>
      </note>

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

/* System Related Information.  If you read and configure only one
 * section then it should be this one.  The Intel architecture defaults
 * are set for a i686 and higher.  Axp is for the Alpha architecture
 * and Ppc is for the Power PC.  AMD64 is for the Opteron processor.
 * Note that there have been reports that the Ppc optimization line
 * causes segmentation faults during build.  If that happens, try
 * building without the DefaultGcc2PpcOpt line.  ***********/

/* #define DefaultGcc2i386Opt  -O2 -fno-strength-reduce \
                               -fno-strict-aliasing -march=i686 */
/* #define DefaultGcc2AMD64Opt -O2 -fno-strength-reduce \
                               -fno-strict-aliasing */
/* #define DefaultGcc2AxpOpt   -O2 -mcpu=ev6 */
/* #define DefaultGcc2PpcOpt   -O2 -mcpu=750 */

#define HasFreetype2            YES
#define HasFontconfig           YES
#define HasExpat                YES
#define HasLibpng               YES
#define HasZlib                 YES

/*
 * Which drivers to build.  When building a static server, each of
 * these will be included in it.  When building the loadable server
 * each of these modules will be built.
 *
#define XF86CardDrivers         mga glint nv tga s3virge sis rendition \
                                neomagic i740 tdfx savage \
                                cirrus vmware tseng trident chips apm \
                                GlideDriver fbdev i128 \
                                ati DevelDrivers ark \
                                cyrix siliconmotion vesa vga \
                                XF86OSCardDrivers XF86ExtraCardDrivers
*/

/*
 * Select the XInput devices you want by uncommenting this.
 *
#define XInputDrivers           mouse keyboard acecad calcomp citron \
                                digitaledge dmc dynapro elographics \
                                microtouch mutouch penmount spaceorb \
                                summa wacom void magictouch aiptek
 */

/* Most installs will only need this */

#define XInputDrivers           mouse keyboard

/* Xterm is no longer built by default */
#define BuildXterm              YES

/* Disable building Xprint server and clients until we get them figured
 * out but build Xprint libraries to allow precompiled binaries such as
 * Acrobat Reader to run.
 */

#define XprtServer              NO
#define BuildXprintClients      NO

/* Uncomment the following define if you would prefer to install X into
 * /usr or change it to any other location that you prefer.
 * The GL related defines disable compatibility symlinks (the links
 * are not needed when X is installed in /usr).
#define ProjectRoot             /usr
#define LinkGLToUsrInclude      NO
#define LinkGLToUsrLib          NO
 */

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

      <para>There are several other options that you may want to consider.
      A well documented example file is
      <filename>config/cf/xorgsite.def</filename>.</para>

    </sect3>

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

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

<screen><userinput>sed -i -e "s@^#include &lt;linux/config.h&gt;@/* &amp; */@" \
    `grep -lr linux/config.h *` &amp;&amp;
( make World 2&gt;&amp;1 | tee xorg-compile.log &amp;&amp; exit $PIPESTATUS )</userinput></screen>

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

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

      <para>If you've installed <application>Xorg</application> in the default
      prefix listed above, run the following commands as the 
      <systemitem class="username">root</systemitem> user:</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>

    </sect3>

  </sect2>

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

    <para><command>sed -i -e "s@^#include &lt;linux/config.h&gt;@...</command>:
    The <application>Linux-Libc-Headers</application> package installed in
    LFS installs a <filename>/usr/include/linux/config.h</filename> file
    which is not compatible with userspace applications. The recommended fix
    for applications including this file is to remove it (see <ulink
    url="http://ep09.pld-linux.org/~mmazur/linux-libc-headers/doc/FAQ">
    linux-libc-headers FAQ</ulink>). The <command>sed</command> uses
    <command>grep -lr</command> to replace all occurrences. If you desire, just
    remove (comment) the line in the appropriate video driver file if you
    customized <filename>host.def</filename>.</para>

    <para><command>( make World 2&gt;&amp;1 | tee xorg-compile.log
    &amp;&amp; exit $PIPESTATUS )</command>: This command runs multiple
    <filename>Makefile</filename>s to completely rebuild the system.
    <parameter>2&gt;&amp;1</parameter> 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>Xorg</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>Xorg</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 role="configuration" id='xorg-config'>
    <title>Configuring Xorg</title>

    <para>Edit <filename>/etc/ld.so.conf</filename> and add
    <filename class="directory">/usr/X11R6/lib</filename>. Run:</para>

    <indexterm zone="xorg xorg-config">
      <primary sortas="e-etc-ld.so.conf">/etc/ld.so.conf</primary>
    </indexterm>

<screen role="root"><userinput>ldconfig</userinput></screen>

    <para>Ensure <filename class="directory">/usr/X11R6/bin</filename>
    and <filename class="directory">/usr/X11R6/lib/pkgconfig</filename>
    are added to your <envar>PATH</envar> and <envar>PKG_CONFIG_PATH</envar>
    environment variables, respectively. Instructions for doing this are
    described in the section <xref linkend='postlfs-config-profile'/>.</para>

    <para>Create the <filename>xorg.conf</filename> file with:</para>

<screen><userinput>cd ~ &amp;&amp;
Xorg -configure</userinput></screen>

    <para>The screen will go black and you may hear some clicking of the monitor.
    This command will create a file, <filename>xorg.conf.new</filename> in your
    home directory.</para>

    <indexterm zone="xorg xorg-config">
      <primary sortas="e-etc-X11-xorg-conf">/etc/X11/xorg.conf</primary>
    </indexterm>

    <para>Edit <filename>xorg.conf.new</filename> to suit your system. The
    details of the file are located in the xorg.conf man page. Some things
    you may want to do are:</para>

    <itemizedlist>
      <listitem>
        <para>Section "Files". Change the order of the font paths searched.
        You may want to put 100dpi fonts ahead of 75dpi fonts if your system
        normally comes up closer to 100 dots per inch. You may want to remove
        some font directories completely.</para>
      </listitem>
      <listitem>
        <para>Section "Module". If you are going to install NVidia
        drivers, remove the "dri" line.</para>
      </listitem>
      <listitem>
        <para>Sections "InputDevice". You may want to change the
        keyboard autorepeat rate by adding
        <option>Option "Autorepeat" "250 30"</option>.</para>
      </listitem>
      <listitem>
        <para>Section "Monitor". Specify the <option>VertRefresh</option>
        and <option>HorizSync</option> values if the system does not
        automatically detect the monitor and its values.</para>
      </listitem>
      <listitem>
        <para>Section "Device". You may want to set some of the options
        available for your selected video driver. A description of the driver
        parameters is in the man page for your driver.</para>
      </listitem>
      <listitem><para>Section "Screen". Add a DefaultDepth statement such as:
        <option>DefaultDepth 24</option>. In the SubSection for your
        default depth, add a modes line such as:
        <option>Modes "1600x1200" "1280x1024" "1024x768"</option>. The first
        mode listed will normally be the starting resolution.</para>
      </listitem>
    </itemizedlist>

    <para>Test the system with:</para>

<screen><userinput>X -config ~/xorg.conf.new</userinput></screen>

    <para>You will only get a gray background with an X-shaped mouse cursor,
    but it confirms the system is working. Exit with
    <keycap>Control+Alt+Backspace</keycap>. If the system does not work, take
    a look at <filename>/var/log/Xorg.0.log</filename> to see what went
    wrong.</para>

    <para>Move the configuration file to its final location:</para>

<screen role="root"><userinput>mv ~/xorg.conf.new /etc/X11/xorg.conf</userinput></screen>

    <para>Create <filename>.xinitrc</filename>:</para>

<screen><userinput>cat &gt; ~/.xinitrc &lt;&lt; "EOF"
<literal># Begin .xinitrc file
xterm  -g 80x40+0+0   &amp;
xclock -g 100x100-0+0 &amp;
twm</literal>
EOF</userinput></screen>

    <para>This provides an initial screen with an xterm and a clock that is
    managed by a simple window manager, Tab Window Manager. For details of
    <command>twm</command>, see the man page.</para>

    <indexterm zone="xorg xorg-config">
      <primary sortas="e-AA.xinitrc">~/.xinitrc</primary>
    </indexterm>

    <note>
      <para>When needed, <application>Xorg</application> creates the directory
      <filename>/tmp/.ICE-unix</filename> if it does not exist. If this
      directory is not owned by <systemitem class="username">root</systemitem>,
      <application>Xorg</application> delays startup by a few seconds and also
      appends a warning to the logfile. This also affects startup of other
      applications. To improve performance, it is advisable to manually create
      the directory before <application>Xorg</application> uses it. Add the
      file creation to <filename>/etc/sysconfig/createfiles</filename> that is
      sourced by the <filename>/etc/rc.d/init.d/cleanfs</filename> startup
      script.</para>

<screen role="root"><userinput>cat &gt;&gt; /etc/sysconfig/createfiles &lt;&lt; "EOF"
<literal>/tmp/.ICE-unix dir 1777 root root</literal>
EOF</userinput></screen>

    </note>

    <indexterm zone="xorg xorg-config">
      <primary
      sortas="e-etc-sysconfig-createfiles">/etc/sysconfig/createfiles</primary>
    </indexterm>

    <para>Start <application>X</application> with:</para>

<screen><userinput>startx</userinput></screen>

    <para>to get a basic functional <application>X Window
    System</application>.</para>

    <para>At this point, you should check out <xref linkend='x-setup'/> for
    the necessary configuration to make <application>X</application> fully
    functional. Additionally, you can have a look at <xref linkend='x-config'/>
    for information on fine tuning your <application>X</application>
    configuration.</para>

    <para>For a list of the package contents and a description of the commands,
    see the sections in the <xref linkend='xfree86-contents'/>.</para>

  </sect2>

</sect1>