source: x/installing/xorg.xml@ feeb99a

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

  <!ENTITY xorg-download-http "http://freedesktop.org/~xorg/X11R6.7.0/src/">
  <!ENTITY xorg-download-ftp  " ">
  <!ENTITY xorg-size          "70.3 MB">
  <!ENTITY xorg-buildsize     "645 MB">
  <!ENTITY xorg-time          "17.1 SBU">
]>

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


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

<note><para>There are two packages in BLFS 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>-RC2.  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 X packages is the stated goals of the 
developers.  Some developers were unhappy with the administration and progress of 
<application>XFree86</application>.  Xorg'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 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"/>, <xref linkend="expat"/>, <xref linkend="freetype2"/> and
<xref linkend="fontconfig"/>.</para>
</sect4>

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

</sect3>
 
 
<sect3><title>Download Instructions</title>
 
<para>There are several files that need to be fetched from the download location:</para>
<itemizedlist spacing='compact'>
<listitem><para><filename>X11R6.7.0-src1.tar.gz</filename></para></listitem>
<listitem><para><filename>X11R6.7.0-src2.tar.gz</filename></para></listitem>
<listitem><para><filename>X11R6.7.0-src3.tar.gz</filename></para></listitem>
<listitem><para><filename>X11R6.7.0-src4.tar.gz</filename></para></listitem>
<listitem><para><filename>X11R6.7.0-src5.tar.gz</filename></para></listitem>
<listitem><para><filename>X11R6.7.0-src6.tar.gz</filename></para></listitem>
<listitem><para><filename>X11R6.7.0-src7.tar.gz</filename></para></listitem>
</itemizedlist>

<para>The first package contains the <application>Xorg</application> libraries and 
support programs,  the second contains standard X programs, the third contains the 
X server, 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>md5sums</filename>
file.  Then:</para>
 
<screen><userinput><command>md5sum -c md5sums</command></userinput></screen>
 
<para>All seven packages should give an OK status.</para>
</sect3>
</sect2>

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


<sect3>
<title>Kernel Compilation Settings</title>
<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 doing:</para>
<screen><userinput><command>cat /proc/pci</command></userinput></screen>
 
<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).
If you do enable <acronym>DRI</acronym> here, make sure you select the video card(s) you want
to support as a <emphasis>module</emphasis>.</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 the kernel.</para>
 
<para>Copy the <filename>arch/i386/boot/bzImage</filename> and <filename>System.map</filename> 
from the kernel build directory to <filename class='directory'>/boot</filename>.
Edit <filename>/boot/grub/grub.conf</filename> and add the new kernel to the
boot menu.
(If you use lilo, edit <filename>/etc/lilo.conf</filename> and run <filename>lilo</filename>.)
</para>
 
<note><para>If you build <application>Xorg</application> in a chroot environment, 
make sure the kernel version of the base system and the target system are the same.  
This is especially important if you enabled <acronym>DRI</acronym> support as a module as
instructed above.</para></note>
</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, we first
make the <application>lndir</application>.  Starting from the 
<filename class='directory'>xc</filename> directory:</para>

<screen><userinput><command>pushd config/util &amp;&amp;
make -f Makefile.ini lndir &amp;&amp;
cp lndir /usr/bin/ &amp;&amp;
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 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><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


/* 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.cf</filename>.</para>
</sect3>

<sect3>
<title>Build Commands</title>
<para>Install <application>Xorg</application> by running the following commands:</para>
 
 
<screen><userinput><command>( make World 2&gt;&amp;1 | tee xorg-compile.log &amp;&amp; exit $PIPESTATUS ) &amp;&amp;
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>

<sect3>
<title>Updating Direct Rendering Infrastructure (<acronym>DRI</acronym>)</title>
<para>If you have one of the supported <acronym>DRI</acronym> cards and
have enabled <acronym>DRI</acronym> kernel modules as explained
above, you now need to update the kernel modules to ensure they are compatible with the
current version of <application>Xorg</application>.  To do this, perform the following:</para>
 
<screen><userinput><command>cd programs/Xserver/hw/xfree86/os-support/linux/drm/kernel &amp;&amp;
make  CC=/opt/gcc-2.95.3/bin/gcc -f Makefile.linux  &amp;&amp;
mkdir -p /lib/modules/`uname -r`/kernel/drivers/char/drm/  &amp;&amp;
cp gamma.o radeon.o sis.o r128.o i810.o i830.o mga.o tdfx.o \
    /lib/modules/`uname -r`/kernel/drivers/char/drm/  &amp;&amp;
depmod -a</command></userinput></screen>
 
<warning><para>If you recompile or upgrade your kernel, you will need to re-copy the
appropriate driver module(s)
to the kernel module library and rerun the <command>depmod -a</command> command.</para></warning>
 
<note><para>If you created <acronym>AGP</acronym> support as a module when compiling 
the kernel, you may have to add a line to <filename>/etc/modules.conf</filename> to ensure
the agpgart module is loaded.  For instance, the <acronym>AGP</acronym> version of the 
Radeon video card will use the <filename>radeon.o</filename> driver.  It will
need to have the line <screen>below radeon agpgart</screen> in
<filename>/etc/modules.conf</filename> to enable <acronym>DRI</acronym> support.</para></note>
</sect3>
</sect2>

<sect2>
<title>Command explanations</title>
 
<para><command>( make World 2&gt;&amp;1 | tee xorg-compile.log
   &amp;&amp; exit $PIPESTATUS )</command>:
This command runs multiple makefiles 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>.  We do this 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>
 
<para><command>make  CC=/opt/gcc-2.95.3/bin/gcc -f Makefile.linux</command>: This builds the
<application>Xorg</application> compatible kernel modules using the same compiler used to compile
the kernel.</para>
 
<para><command>cp gamma.o radeon.o sis.o r128.o i810.o i830.o mga.o tdfx.o
/lib/modules/`uname -r`/kernel/drivers/char/drm/</command>: Put the kernel
module(s) where the kernel can find them. You only need to copy the driver you
need to support your video card.</para>
 
<para><command>depmod -a</command>: Update the modules.dep file for module
management.</para>

</sect2>

<sect2>
<title>Configuring Xorg</title>

<para>Edit <filename>/etc/ld.so.conf</filename> and add
<filename class="directory">/usr/X11R6/lib</filename>.
Run:</para> <screen><userinput><command>ldconfig</command></userinput></screen>
 
<para>Ensure <filename class='directory'>/usr/X11R6/bin</filename> is added to your
<envar>PATH</envar> environment variable. Instructions for doing this are described
in the section "<xref linkend='postlfs-config-profile'/>."</para>
 
<para>Expand the <envar>PKG_CONFIG_PATH</envar> so that other packages
can find <application>X</application> libraries. Procedures for this are also
described in the section "<xref linkend='postlfs-config-profile'/>."</para>

<para>Set up your mouse:
<screen><userinput><command>ln -s psaux /dev/mouse</command></userinput></screen>
 
Adjust the symbolic link as necessary for other types of mice.  For instance,
a serial mouse on the first serial port would be linked to ttyS1.</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>
 
<para>Edit <filename>xorg.conf.new</filename> to suit your system.  The
details of the file are located in the man
page <command>man xorg.conf</command>.  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 "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 "InputDevice".  You may want to change the keyboard
autorepeat rate by
adding <parameter>Option "Autorepeat" "250 30"</parameter>.</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 16</parameter>. In the SubSection for your
default depth, add a modes line such
as: <parameter> Modes "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 -xf86config ~/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 twm, see the
man page.</para>
 
<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 Xorg 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><command>cat &gt;&gt; /etc/sysconfig/createfiles &lt;&lt; "EOF"</command>
/tmp/.ICE-unix dir 1777 root root
<command>EOF</command></userinput></screen>
 
</note>
 
<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 the X Window Components at 
<xref linkend='x-setup'/>.</para>

</sect2>
</sect1>