source: x/installing/xorg.xml@ a0d94196

<?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 " ">
  <!ENTITY xorg-download-ftp  "ftp://ftp.opengroup.org/pub/x.org/pub/X11R&xorg-version;/src-single/X11R&xorg-version;-src.tar.bz2">
  <!ENTITY xorg-md5sum        "8131cd7ea1e4566e6e05c438a93fcfe1">
  <!ENTITY xorg-size          "43 MB">
  <!ENTITY xorg-buildsize     "839 MB">
  <!ENTITY xorg-time          "10.34 SBU">
]>

<sect1 id="xorg" xreflabel="X.org-&xorg-version;">
<sect1info>
  <othername>$LastChangedBy$</othername>
  <date>$Date$</date>
</sect1info>

<?dbhtml filename="xorg.html"?>
<title>Xorg-&xorg-version;</title>

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

<sect2>
<title>Introduction to <application>Xorg</application></title>

<note><para>There are two packages in <acronym>BLFS</acronym> that implement 
the <application>X</application> Window System: <application>Xorg</application> 
and <application>XFree86</application>. These packages are quite similar. In 
fact, the base system of <application>Xorg</application> is 
<application>XFree86</application>-4.4.0RC2. The primary difference as of this 
writing is the license provisions of the packages.  For someone building a 
package for their own use, these issues are not significant.  Most large 
commercial distributions have decided to use the  
<application>Xorg</application> package, but several still use 
<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>

<para>Both <application>Xorg</application> and 
<application>XFree86</application> can be installed in the same way, but this 
section will provide a slightly different and more current variation for 
installation.</para>
</note>

<para><application>Xorg</application> is a freely redistributable open-source
implementation of the <application>X</application> Window System. This 
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 (<acronym>API</acronym>).</para>
 
<sect3><title>Package information</title>
  <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>
</sect3>
 
<sect3>
  <title><application>Xorg</application> Dependencies</title>
 
<sect4>
  <title>Required</title>
  <para><xref linkend="libpng"/> and 
        <xref linkend="fontconfig"/></para>
</sect4>

<sect4>
  <title>Optional</title> 
  <para><xref linkend="Linux_PAM"/></para>
</sect4>

</sect3>
 
<sect3><title>Download Instructions</title>
 
<para>As an alternative to downloading the entire source tree in a single
file, there are several files that need to be fetched from the download 
location (directory /pub/x.org/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><command>md5sum -c md5sums</command></userinput></screen>
 
<para>The package (or all seven packages) should give an OK status.</para>
</sect3>
</sect2>

<sect2>
  <title>Installation of <application>Xorg</application></title>

<sect3 id='xorg-kernel'>
  <title>Kernel Compilation Settings</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 <acronym>MTRR</acronym> (Memory Type Range 
    Registers) support into the kernel. The kernel can map Cyrix and AMD 
    <acronym>CPU</acronym>s to the <acronym>MTRR</acronym> 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 <acronym>PCI</acronym> or
    <acronym>AGP</acronym> video cards.
  </para>
 
  <para>In the "Character Devices" section, enable <acronym>AGP</acronym> 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
    (<acronym>DRI</acronym>) supported video card.  A complete list of 
    <acronym>DRI</acronym> 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 <acronym>DRI</acronym>. If you intend to use these 
    drivers, do not enable <acronym>DRI</acronym>.
  </para>
 
  <para>If you made any changes to the kernel configuration, recompile and
    install the new kernel.
  </para>
 
  <note><para>If you build <application>Xorg</application> in a 
    <command>chroot</command> environment, make sure the kernel version of the base 
    system and the target system are the same.</para>
  </note>
</sect3>

<sect3>
  <title>Suppressing Xprint-related modification to <filename class="directory">/etc</filename></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><command>sed -i '/^SUBDIRS =/s/ etc$//' programs/Xserver/Xprint/Imakefile</command></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><command>pushd config/util &amp;&amp;
make -f Makefile.ini lndir</command></userinput></screen> 

<para>Now, as the root user:</para>
 
<screen><userinput role='root'><command>cp lndir /usr/bin/</command></userinput></screen> 

<para>And back as a regular user:</para>
<screen><userinput><command>popd</command></userinput></screen>

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

<screen><userinput><command>mkdir ../xcbuild &amp;&amp;
cd ../xcbuild &amp;&amp;
lndir ../xc</command></userinput></screen>
</sect3>

<sect3>
  <title>Creating <filename>host.def</filename></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 
    <acronym>LFS</acronym> 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 <userinput>/*</userinput> ... 
    <userinput>*/</userinput> are balanced when modifying the file.</para>
  </note>

<screen><userinput><command>cat &gt; config/cf/host.def &lt;&lt; "EOF"</command>
/* 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 DefaultGccAMD64Opt -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 AgpGartDrivers 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

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

/* End Xorg host.def file */
<command>EOF</command></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><command>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 )</command></userinput></screen> 

<para>Again as the root user:</para>
 
<screen><userinput role='root'><command>make install &amp;&amp; 
make install.man &amp;&amp;
ln -sf ../X11R6/bin /usr/bin/X11 &amp;&amp;
ln -sf ../X11R6/lib/X11 /usr/lib/X11 &amp;&amp;
ln -sf ../X11R6/include/X11 /usr/include/X11</command></userinput></screen>
 
</sect3>
</sect2>

<sect2>
<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
    <acronym>LFS</acronym> 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 occurences. 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 comand 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><screen><command>ln -sf ../X11R6/bin /usr/bin/X11
ln -sf ../X11R6/lib/X11 /usr/lib/X11
ln -sf ../X11R6/include/X11 /usr/include/X11</command></screen>
These commands are present to enable other (broken) packages to build against 
<application>Xorg</application>, even though the Filesystem Hierarchy Standard 
says: "In general, software must not be installed or managed via the above
symbolic links. They are intended for utilization by users only."</para>
 
</sect2>

<sect2 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><userinput><command>ldconfig</command></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:
<screen><userinput><command>cd ~
Xorg -configure</command></userinput></screen>
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
<parameter>Option "Autorepeat" "250 30"</parameter>.</para></listitem>
 
<listitem><para>Section "Monitor".  Specify the 
<parameter>VertRefresh</parameter> and <parameter>HorizSync</parameter> 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: 
<parameter>DefaultDepth 24</parameter>. In the SubSection for your default 
depth, add a modes line such as: 
<parameter>Modes "1600x1200" "1280x1024" "1024x768"</parameter>. The first mode listed 
will normally be the starting resolution.</para></listitem>
 
</itemizedlist>

<para>Test the system with:
<screen><userinput><command>X -config ~/xorg.conf.new</command></userinput></screen>
You will only get a gray background with an X-shaped mouse cursor, but it
confirms the system is working.  Exit with Control-Alt-Backspace.  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><userinput><command>mv ~/xorg.conf.new /etc/X11/xorg.conf</command></userinput></screen>
 
<para>Create <filename>.xinitrc</filename>:
<screen><userinput><command>cat &gt; ~/.xinitrc &lt;&lt; "EOF"</command>
# Begin .xinitrc file
xterm  -g 80x40+0+0   &amp;
xclock -g 100x100-0+0 &amp;
twm
<command>EOF</command></userinput></screen>
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 root, <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><userinput role='root'><command>cat &gt;&gt; /etc/sysconfig/createfiles &lt;&lt; "EOF"</command>
/tmp/.ICE-unix dir 1777 root root
<command>EOF</command></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:
<screen><userinput><command>startx</command></userinput></screen>
to get a basic functional <application>X</application> Window System.</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>