  GGI Installation Guide
  The GGI Project Team
  $Date: 1998/06/29 17:07:26 $

  This document describes how to install GGI. It covers patching the
  Linux kernel, installing (Linux) kernel drivers and installing the
  libggi.
  ______________________________________________________________________

  Table of Contents


  1. Temporary preface

  2. Disclaimer

  3. Overview

  4. Patching your Kernel

  5. Installing the Drivers

  6. Installing libggi



  ______________________________________________________________________

  1.  Temporary preface

  This document describes still the installation procedure for ggi
  version 0.0.9 (dali), and has not been updatded for the new degas
  stage. Be prepared that it might be inaccurate.  (H. Niemann, 10Jun98)


  2.  Disclaimer


  This software is still in its development stage. Make sure you read
  ALL related documentation before attempting to install or use any
  portion of GGI. For more information, see the GGI homepage
  <http://www.ggi-project.org/>.


  THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
  USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  DAMAGE.



  3.  Overview


  First of all, thank you for trying GGI. The sources you obtained are
  the GGI-0.0.9 public release. Not all of the drivers are in working
  stage. However, they are included to have a broader testing base.


  Please make sure you read all the README files related to the drivers,
  there will be useful hints and notes about what works, what is known
  not to work, how to fix problems etc.

  To install GGI, the steps described in this document have to be done.
  But you will not have to do these steps manually. There are scripts
  (most of the time called 'configure') spread in the source tree that
  will help you to configure and install GGI. This document will show
  you what has to happen in order to install GGI to let you understand
  what the scripts can do for you. Read 'README.configure' for more
  information on the configuration scripts.

  Basically you will:

  o  create, configure, build, install and boot a GGI-prepared kernel.
     This is described in section ``Patching your kernel''

  o  configure, build and install drivers for your graphics cards.  This
     is described in section ``Installing the drivers''

  o  build and install ggilib-dynamic This is described in section
     ``Installing libggi''

  o  have fun running the demos without any root privileges This is not
     described anywhere, as you know how to have fun, don't you ? But
     before the fun, we have to do a little work.


  4.  Patching your Kernel



  1. Extract this package.

     Well you did already, so let's assume this file resides in the ggi-
     v.e.r/ directory. If you obtained a development version of GGI,
     from CVS or a snapshot page, the file will reside in the ggi/
     directory.

  2. Get a linux-2.x.x.tar.gz kernel archive of any 2.0 kernel or a
     recent 2.1 kernel. Please look at the file ggi-
     v.e.r/patches/Linux/Makefile for details and get a supported
     kernel.


     NOTE: Support for old 2.1 kernels may be dropped without notice if
     maintaining four(!) kernel trees becomes too much work.  Thank you
     for your understanding.


  3. Expand the linux source archive in /usr/src.


     NOTE: The archive expands to linux/* so rename any directory or
     link named "linux" before you extract the sources - otherwise your
     current kernel source will be broken!

     NOTE: You should also use a "fresh" kernel the first time, as these
     are known to work well. If you have other patches applied, the GGI
     patch may fail. Please check this before mailing a bug report.


  4. We recommend you have a second kernel image to boot from either on
     floppy or on harddisk. Don't rely on one image. See the man pages
     or lilo docs for details. For example, save your current boot image
     (e.g. /vmlinuz to /vmlinuz.sav), and add the following lines to
     your /etc/lilo.conf file:



               # rescue boot kernel
               image = /vmlinuz.sav
               root = <your root partition>
               label = rescue_me





  5. Go to the ggi-v.e.r/ directory and modify the kernel in
     /usr/src/linux. Simply type

     make patch_kernel KERNEL_VERSION=v.e.r

     with v.e.r being the version of the kernel code in /usr/src/linux.
     The Makefile will try to apply patches known to work, so don't
     panic if it insists on using patches for a different kernel
     version.  It knows well about it's job, and you should trust it.


     NOTE: The KERNEL_VERSION argument is optional, as the ggi-
     v.e.r/patches/Linux/Makefile is able to extract it from the
     kernel's Makefile.

     NOTE: If the kernel source resides in a different directory than
     the default one -- which is /usr/src/linux-- then specify its root
     directory using the KERNELSRC option:

     make patch_kernel KERNELSRC=/home/develop/linux-ggi


  6. Now configure, compile, and install the new kernel. For instance,
     you might want to do

     cd /usr/src/linux; make config

     and follow the instructions given there. Of course you will have to
     substitute the directory path if your kernel resides in a different
     directory than the default one.

     Make sure you DO NOT enable the Magic SysRq patch as this will
     break GGI/KGI!

     If your keyboard is not supported, there is a patch to the kbd
     utilities included (ggi-v.e.r/patches/utils/kbd-0.91.diff), so you
     may create your own linux/drivers/char/i386/default/keymap.c file
     using the patched loadkeys utility and your favorite keymap.  If
     you do so, make sure you map Graphic_nn keysyms to ALTGR-Fnn.  See
     the ibm-usa.kmap file for an example.

  7. Now reboot and find as many bugs or features as possible.


     NOTE: The current code expects all displays found to be in a
     text16.80x25.80x25 mode. You might have to give the proper
     arguments to the kernel if you normally like to boot e.g.
     text16.132x43.  This is because the kernel doesn't report the mode
     of a second display when installed.


  8. Create the device special files in /dev. To do this, run

     make devices

     from the ggi-v.e.r/ directory.

     This will create the /dev/graph?? special files that are needed by
     ggilib-dynamic.

  9. Create the needed link in /usr/include. To do this, run

     make install

     This will create a link from /usr/include/ggi/ to ggi-
     v.e.r/include/

  The ggi-kernel should boot on any display your computer boots onto,
  but only one VGA and/or only one MDA will be detected and served by
  the boot driver. You can plug in both, and both should be detected.

  If you see our boot logo flashing and get the system running, you have
  done the first third of the installation procedure.



  5.  Installing the Drivers


  You are still with us, so you have a GGI kernel running and you are
  prepared for the next step. The new kernel has hooks to register input
  and display drivers that are loaded as modules. You will have to
  create the drivers first.  To do this, please do the following steps:


  1. Look at your graphics card and find out the hardware that's on it.
     Especially you need to know:


  o  chipset manufacturer, chipset name/trademark/ID

  o  ramdac manufacturer, chip name/trademark/ID

  o  clock chip type and name/manufacturer/ID

  o  monitor type and parameters


     If you don't know much about your card, but know it is a VGA
     compatible device, try VGA settings. Use these too if your card is
     not supported in "native" mode.

  2. Change over to the ggi-v.e.r/driver directory.

  3. If you did not patch the kernel from this source tree,

     echo /where/the/linuxsrc/is > .kernelsrc

     e.g.

     echo /usr/src/linux-ggi > .kernelsrc

     (This is normally done while patching the kernel.)

  4. Run "make".

     This will run the configure script first and let you do the
     configuration by hand or automatically. You can also create a
     config file with a normal editor, we suggest you create a normal
     VGA config first and modify this one. See the README.CONFIG file
     for more details.

     After it, make will build dependencies and compile all the drivers
     needed to create a driver as stated in ggi-v.e.r/driver/.config.

     From now on, running "make" will rebuild this driver. If you want
     to change the configuration, run "make config; make clean; make"

  5. You can create a plain VGA driver for Linux/x86 by a simple

     make vga

     This will neither change nor need an existing .config.

  6. Run "make input"

     This will compile all the configured input drivers.

  7. Run (cd ../util ; make setmouse)

     This will compile a setup utility foe the mouse which is used by
     the insert script.

  8. Insmod the new drivers. Normally

     insert

     does the job. If you made a VGA driver with make vga, then use

     insertvga

     instead.

     The new drivers will be located in the "modules" directory.  The
     toplevel "util" directory includes several programs to help you
     tweak your mouse, mode settings, etc...

     Please refer also to the corresponding files in the driver/.../.../
     directories for possible options, known problems and other hints.


     NOTE: With the 2.1 kernels, you need to upgrade your modutils to at
     least version 2.1.34, otherwise module loading will not work.


  Once the driver(s) are inserted, your system is - from the kernel side
  - prepared so you can run the library and demos. Note that you will
  have to insert the modules again after each boot. So a script to do
  this is not a bad idea.



  6.  Installing libggi



  1. Before attempting to install libggi, make sure you have met the
     following requirements.


  o  linuxthreads-0.5 or higher (or glibc-2.0.2) is installed

  o  ld.so 1.7.14 or higher is installed


     You may compile the ggilib-dynamic without multithread support, but
     some features may be missing then.

  2. Change over to the "lib/libggi" directory.

  3. Run "make config"

     This will bring up a configuration menu. You can choose whether you
     want to use multithreading or not and you can select several
     display targets, i.e. LibGGI can display in an X window or using
     the kernel KGI driver for instance. Leave the menu with EXIT.

  4. Run "make"

     This will compile the library.

  5. Run "make install" as root.

  6. Now drop the root rights. You don't need them anymore.

  7. "cd demos" and "make" there.

     This will compile some demos.

  Now you can try the demos available in the "demos" subdir. These will
  show you some capabilities of libggi. Except for execution permission
  and access permission to the /dev/graph?? files no other rights,
  especially no SUID root is required.

  If you can run the demos, you have successfully installed GGI, and now
  you may play with it. You probably want to install XGGI, which can be
  obtained from the ftp site <ftp://ftp.ggi-project.org/pub/ggi>

  Have a lot of fun,

  The GGI Project Team






























