Rewrote installation and configuration sections

1 files changed, 155 insertions, 78 deletions

diff --git a/xc/programs/Xserver/hw/xfree86/doc/sgml/DRIcomp.sgml b/xc/programs/Xserver/hw/xfree86/doc/sgml/DRIcomp.sgml
index b54386a91..fde6b7bc5 100644
--- a/xc/programs/Xserver/hw/xfree86/doc/sgml/DRIcomp.sgml
+++ b/xc/programs/Xserver/hw/xfree86/doc/sgml/DRIcomp.sgml
@@ -1,15 +1,17 @@
 <!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN" [
 <!ENTITY % defs SYSTEM "defs.ent"> %defs;
 ]>
-<!-- Created: Sun Mar 12 13:00:00 2000 by brian@precisioninsight.com -->
+
+<!-- Created: Sun Mar 12 13:00:00 2000 by brianp@valinux.com -->
 <!-- Revised: Fri May 19 09:36:02 2000 by martin@valinux.com -->
+<!-- Revised: Sat Aug 19 14:00:00 2000 by brianp@valinux.com -->
 
   <article>
 
       <title>DRI Compilation Guide
       <author>
-          <htmlurl url="http://www.precisioninsight.com/"
-            name="Precision Insight, Inc.">
+          <htmlurl url="http://www.valinux.com/"
+            name="VA Linux Systems, Inc."> Professional Services - Graphics.
       <date>8 August 2000
         
     <ident>
@@ -22,8 +24,7 @@
 
       <sect1>Copyright <p>
 
-          <bf>Copyright &copy; 2000 by Precision Insight, Inc.,
-          Cedar Park, Texas.
+          <bf>Copyright &copy; 2000 by VA Linux Systems, Inc.
           All Rights Reserved.</bf>
         <p>
           <bf>Permission is granted to make and distribute verbatim copies 
@@ -57,7 +58,7 @@
         Beginners are probably better off installing precompiled packages.
       <p>
         Edits, corrections and updates to this document may be mailed
-        to brian@precisioninsight.com.
+        to brianp@valinux.com.
 
 
     <sect>Prerequisites <p>
@@ -339,7 +340,7 @@
           would overwrite your default X files.
           The following is recommended:
           <verb>
-            #define ProjectRoot /usr/XF86-main
+            #define ProjectRoot /usr/X11R6-DRI
           </verb>
         <p>
           Especially note the <em>XF86CardDrivers</em> line to be sure your
@@ -353,7 +354,7 @@
           line in <tt>host.def</tt>.
         <p>
 
-      <sect1>Compile <p>
+      <sect1>Compilation <p>
 
           To compile the complete DRI tree:
           <verb>
@@ -408,47 +409,50 @@
           </verb>
           or alternatively, edit Makefile to include this change.
         <p>
-          After fixing the errors, do <tt>make World</tt> again.
+          After fixing the errors, run <tt>make World</tt> again.
           Later, you might just compile parts of the source tree but it's
           important that the whole tree will build first.
 
 
-    <sect>Installing <p>
+    <sect>Normal Installation and Configuration <p>
 
-        After the DRI tree has been compiled you can install the XFree86
-        headers, libraries, programs, etc for testing.
+        Most users will want to install the new X server and use it instead
+        of the original X server.
+        This section explains how to do that.
+        We assume that the user is upgrading from XFree86 3.3.x.
+        <p>
+        Developers, on the other hand, may just want to test the X server
+        without actually installing it as their default server.
+        If you want to do that, skip to the next section.
+        <p>
 
       <sect1>X Installation <p>
 
-	  As mentioned above, the install directory is specified by the
+          You'll need to run as root to do the following commands:
+          <verb>
+	      su
+          </verb>
+	  As mentioned above, the installation directory is specified by the
 	  <tt>ProjectRoot</tt> variable in the <tt>host.def</tt> file.
-	  Create that directory now if it doesn't already exist:
-	  <verb>
-	      mkdir /usr/XF86-main
-	  </verb>
-	<p>
-	  You'll have to change to root since the install process puts
-	  several files in <tt>/etc/X11/</tt> and sets the setuid flag on
-	  the X server executable.
+	  Create that directory now if it doesn't already exist, then
+          run the install commands:
 	  <verb>
+	      mkdir /usr/X11R6-DRI
 	      cd ~/DRI-CVS/build/xc
-	      su
 	      make install
 	  </verb>
+
+      <sect1>Linker configuration <p>
+
 	  Edit your <tt>/etc/ld.so.conf</tt> file and put
-	  <tt>/usr/XF86-main/lib</tt> as the first line.
-	  Continue with:
+	  <tt>/usr/X11R6-DRI/lib</tt> as the first line.
+	  Then run:
 	  <verb>
 	      ldconfig
-	      exit
 	  </verb>
-	<p>
-	  Look in <tt>/usr/XF86-main</tt> to be sure the files installed
-          there.
-	<P>
-	  Strictly speaking, installing the DRI tree isn't required.
-	  It's possible to run and test the X server directly from the
-	  build directory but it's a bit error prone.
+          This will ensure that you use the new X libraries when you run
+          X programs.
+        <p>
 
       <sect1>Update Locale Information <p>
 
@@ -462,64 +466,137 @@
           This will prevent a locale error message from being printed
           when you run Xlib programs.
 
-    <sect>X Server Configuration <p>
+      <sect1>Setup Miscellaneous Files <p>
 
-        If your X server is currently running you'll have to stop it
-        and return to a virtual terminal.
-      <p>
-        First, setup your XF86Config file.
-        It should load the GLX and DRI modules and specify the driver to
-        use for your hardware.
-        See the <htmlurl url="http://dri.sourceforge.net/DRIuserguide.html"
-        name="DRI User Guide"> for detailed information.
-      <p>
-        You may want to make a backup copy of your existing
-        <tt>/etc/X11/XF86Config</tt> file first.
+          Issue the following commands:
+          <verb>
+             cd /usr/X11R6-DRI/lib/X11
+             ln -s /usr/X11R6/lib/X11/rgb.txt .
+             ln -s /usr/X11R6/lib/X11/fonts .
+             ln -s /usr/X11R6/lib/X11/app-defaults .
+          </verb>
+
+          This will allow applications to use the fonts and resources
+          that they used in the past.
+
+      <sect1>Disable the Old X Server and Enable the New One <p>
+
+          Assuming that an installation of XFree86 3.3.x is present, we need
+          to disable the old 3.3.x X server and enable the new 4.0.x X server.
+        <p>
+          Issue the following commands:
+          <verb>
+             cd /usr/X11R6/bin
+             mv Xwrapper Xwrapper.old
+             rm X
+             ln -s /usr/X11R6-4.0.1/lib/X11/XFree86  X
+          </verb>
+          This will cause the new X server to be used instead of the
+          original one.
+        <p>
+
+      <sect1>Create the XF86Config File <p>
+
+          Configuration files for XFree86 3.3.x will not work with
+          XFree86 4.0.x.
+        <p>
+          The new 4.0.x server can generate a basic configuration file
+          itself.
+          Simply do this:
+          <verb>
+             cd /usr/X11R6-DRI/bin
+             ./XFree86 -configure
+          </verb>
+          A file named <tt>/root/XF86Config.new</tt> will be created.
+          It should allow you to try your X server but you'll almost
+          certainly have to edit it.
+          For example, you should add <tt>HorizSync</tt> and
+          <tt>VertRefresh</tt> options to the <tt>Monitor</tt> section
+          and <tt>Modes</tt> options to the <tt>Screen</tt> section.
+          Also, the <tt>ModulePath</tt> option in the <tt>Files</tt>
+          section should be set to <tt>/usr/X11R6-DRI/lib/modules</tt>.
+        <p>
+          On the DRI website, in the resources section, you'll find example
+          XF86Config files for a number of graphics cards.
+          These configuration files also setup DRI options so it's highly
+          recommended that you look at these examples.
+        <p>
+          In any case, your new XF86Config file should be placed in
+          <tt>/etc/X11/XF86Config-4</tt>.
+          This configuration file will be recognized by the 4.0.x server
+          but not by 3.3.x servers.
+          You can instead name it <tt>/etc/X11/XF86Config</tt> but
+          that'll overwrite your old config file, which you may want to
+          preserve.
+        <p>
+
+      <sect1>Start the New X Server <p>
+
+          The new X server should be ready to use now.
+          Start your X server in your usual manner.
+          Typically, the <tt>startx</tt> command is used:
+          <verb>
+             startx
+          </verb>
+
+
+    <sect>Testing the Server Without Installing It <p>
+
+        As mentioned at the start of section 8, developers may want to
+        simply run the X server without installing it.
+        This can save some time and allow you to keep a number of X servers
+        available for testing.
       <p>
-        It's very important that you set the <tt>ModulePath</tt> option to
-        point to your installation directory:
-        <verb>
-            ModulePath "/usr/XF86-main/lib/modules"
-        </verb>
+
+      <sect1>Configuration <p>
+        As described in the preceeding section, you'll need to create a
+        configuration file for the new server.
+        Put the <tt>XF86Config</tt> file in your
+        <tt>~/DRI-CVS/build/xc/programs/Xserver</tt> directory.
       <p>
-        Double check with this:
-        <verb>
-            grep ModulePath /etc/X11/XF86Config
-        </verb>
+        Be sure the <tt>ModulePath</tt> option is set correctly.
       <p>
-        Next, your <tt>~/.xinitrc</tt> file controls which clients will be
-        launched when your X server starts.
-        You might put the following in yours:
+
+      <sect1>A Startup Script <p>
+        A simple shell script can be used to start the X server.
+        Here's an example.
         <verb>
-            xset b off
-            xsetroot -solid "#004070"
-            xmodmap -e "clear mod4"
-            xrdb -merge ~/.Xdefaults
-            xterm -geometry +0+0 &
-            xterm -geometry +512+0 &
-            fvwm
+	   #!/bin/sh
+	   export DISPLAY=:0
+	   ./XFree86 -xf86config XF86Config & \
+	   sleep 2
+	   fvwm2 &
+	   xset b off
+	   xmodmap -e "clear mod4"
+	   xsetroot -solid "#00306f"
+	   xterm -geometry 80x40+0+0
         </verb>
-      <p>
+	  You might name this script <tt>start-dri</tt>.
+	  Put it in your <tt>~/DRI-CVS/build/xc/programs/Xserver</tt>
+          directory.
+        <p>
+          To test the server run the script:
+          <verb>
+             cd ~/DRI-CVS/build/xc/programs/Xserver
+             ./start-dri
+          </verb>
+          For debugging, you may also want to capture the log messages
+          printed by the server in a file.
+          If you're using the C-shell:
+          <verb>
+             ./start-dri >& log
+          </verb>
 
-    <sect>X Server Start-up <p>
 
-        The X server can be started with:
-      <p>
-        <verb>
-            xinit -- /usr/XF86-main/bin/XFree86
-        </verb>
-      <p>
-        Automatic loading of DRM kernel modules was added to the X server
-        in XFree86 4.0.1.
-        This feature, and manual loading of kernel modules, is documented
-        in the DRI user guide.
-      <p>
+    <sect>Where To Go From Here <p>
+
         At this point your X server should be up and running with
         hardware-accelerated direct rendering.
         Please read the
         <htmlurl url="http://dri.sourceforge.net/DRIuserguide.html"
-        name="DRI User Guide"> for trouble shooting information.
-
+        name="DRI User Guide"> for information about trouble shooting
+        and how to use the DRI-enabled X server for 3D applications.
+      <p>
 
   </article>