<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN">

<article>

<title>README for XFree86 on LynxOS
<author>Thomas Mueller
<date>Last modified on: 15 November 1999
<toc>

<sect>What and Where is XFree86?<p>
XFree86 is a port of X11R6.3 that supports several versions of
Intel-based Unix.  It is derived from X386 1.2, which was the X server
distributed with X11R5.  This release consists of many new features
and performance improvements as well as many bug fixes.  The release
is available as source patches against the X Consortium X11R6.3 code, as
well as binary distributions for many architectures.

See the Copyright Notice in <htmlurl url="COPYRIGHT.html"
name="Copyright Notice">.

The sources for XFree86 are available by anonymous ftp from:

<htmlurl name="ftp://ftp.XFree86.org/pub/XFree86/current"
url="ftp://ftp.XFree86.org/pub/XFree86/current">

Binaries of XFree86 for LynxOS x86 are available from:

<htmlurl name="ftp://ftp.XFree86.org/pub/XFree86/current/binaries/LynxOS"
url="ftp://ftp.XFree86.org/pub/XFree86/current/binaries/LynxOS">
 
The binaries were built on `LynxOS x86 3.0.1'. Because of changes
made to the object format they don't run on LynxOS versions earlier
than 3.0.0.

Building of this XFree86 version has never been tested on LynxOS versions
earlier than 2.4.0. Binaries built on LynxOS 2.4.0 are expected to run
on 2.3.0 as well.

XFree86 supports LynxOS on the AT, on the microSPARC and
on the PowerPC platform. X servers are currently available on
the AT and microSPARC platform. Refer to section <ref id="others"
name="Building on microSPARC and PowerPC"> for details on XFree86
on the non-AT platforms.

If you need binaries for other platforms than the one on the
XFree86 FTP server contact me (<htmlurl name="tmueller@sysgo.de"
url="mailto:tmueller@sysgo.de">).

Send email to <it>tmueller@sysgo.de</it> (Thomas Mueller) or
<it>XFree86@XFree86.org</it> if you have comments or suggestions about
this file and we'll revise it.

<sect>Installing the Binaries
<p>
Please refer to section "Installing the XFree86 3.3.6 Release" of the 
<htmlurl url="RELNOTES.html" name="Release Notes"> for detailed 
installation instructions.

If you plan to install XF86Setup you'll have to install
<tt/X336prog/ as well since XF86Setup checks for the existence of
a certain file name pattern which is satisfied only if you install
the library files from <tt/X336prog/.

It may be necessary to increase the process stack limit in order to
run XFree86 on your system. Edit <tt>/etc/startab</tt> and reboot your
system to make the changes active before you begin the installation.

Also, be sure to include <tt>/usr/X11R6/bin</tt> in your PATH
environment variable.

Refer to the next section <ref id="running" name="Running XFree86"> for
further information on necessary configuration steps before running 
XFree86 on LynxOS. 

<sect>Running XFree86<p><label id="running">

This section describes the changes to the LynxOS environment 
which may be necessary to successfully run XFree86.

Read <htmlurl url="QuickStart.html" name="Quick-Start Guide 
to XFree86 Setup"> to learn more about how to configure XFree86 for
your hardware.

<sect1>System requirements<p>
  A minimum of 16MB of memory is required to run X. If you want to run
  real-world applications you should think of upgrading to 32MB (or more).

<sect1>System tuning<p>
<sect2>Tunable parameters<p>
  To reasonably run XFree86 you may have to adjust a few system parameters.

  On LynxOS 2.5.x and 3.0.x include a line
<verb>
  #define X_WINDOWS
</verb>

  in <tt>/sys/lynx.os/uparam.h</tt>.

  For earlier versions you'll have to edit <tt>/usr/include/param.h</tt>:
<verb>
  Tunable                                           Old     New
  USR_NFDS      number of open files per process     20      64
  NPROC         number of tasks                      50     150
  NFILES        number of open files in system      100     250
  NINODES       number of incore inodes             (same value as NFILES)
  QUANTUM       clock ticks until preemption         64      20
  CACHEBLKS     number of cache memory blocks       202      >= 4096
</verb>

  The new values are those suggested by the LynxOS documentation for
  their X Window package.

<sect2>Adjustment for Riva 128 and Riva TNT driver>

If you're using the nVidia driver (Riva 128, TNT, TNT2) of the SVGA
server, you will have to increase the value of the SMEMS parameter in 
<tt>/sys/lynx.os/uparam.h</tt> from 10 to 20.

<sect2>Increase number of ptys<p>

  You should also increase the number of ptys to be able run a couple
  more xterms. You may replace <tt>/sys/lynx.os/pty.cfg</tt> with
  <tt>/usr/X11R6/lib/X11/etc/pty.cfg</tt>.

<sect2>Kernel build<p>

  If you plan to use PS/2 or Bus mice refer to the following section
  before rebuilding the kernel, if not, you should rebuild the kernel
  now: 

  <tscreen><verb>
     # cd /sys/lynx.os
     # make install
     # reboot -N
  </verb></tscreen>

<sect1>Mouse support in XFree86<p>

  XFree86 includes support for PnP mice (see also
  <htmlurl url="mouse.html" name="Mouse Support in XFree86">). The
  current LynxOS TTY device driver doesn't allow the necessary
  manipulation of the RTS line and therefore the support for
  PnP mice has been disabled for LynxOS.

  Starting with LynxOS x86 2.4.0 LynxOS includes a PS/2 mouse driver.
  This driver does protocol conversion and requires to specify the 
  mouse type as <em>Microsoft</em> regardless of real mouse type.
  In some cases you won't have all mouse buttons supported.

  The PS/2 mouse driver included in LynxOS x86 3.0.1 patch #XXX
  does not perform protocol conversion and requires to set the
  mouse type to <em>PS/2</em>. This driver will also support the
  extended PS/2 mouse types.

<sect1>Bus mouse drivers<p>

  <tt>/usr/X11R6/lib/X11/etc/BM-Lynx.shar</tt> contains a LynxOS port 
  of the Linux bus mouse drivers. To install the drivers
  unpack the shar archive

  <tscreen><verb>
    # cd /
    # bash /usr/X11R6/lib/X11/etc/BM-Lynx.shar
  </verb></tscreen>

  and follow the notes in <tt>/BMOUSE.Readme</tt> for further installation and
  configuration notes.

  The XFree86 PS/2 mouse driver works also with MetroLink X 2.3.3.1 as
  shipped with LynxOS x86 2.4.0 unless you have the LynxOS patch
  000055-00 installed.

<sect1> ATC console driver and VT switching<p>

  The XFree86 servers will only run with the default LynxOS console
  driver, sorry for those of you who use the alternative vdt console
  driver. Currently there is no support for virtual terminal switching
  once the server has started.

  You will need a free console which the X server will use for
  keyboard input. You must disable login on at least one of the four
  virtual terminals in <tt>/etc/ttys</tt>, e.g. <tt>/dev/atc3</tt>:

  <tscreen>
    change
  <verb>
       /dev/atc3:1:default:vt100at:/bin/login
  </verb>
    to
  <verb>
       /dev/atc3:0:default:vt100at:/bin/login
                 ^
  </verb></tscreen>

<sect1>X Server debug diagnostics output and other VT peculiarities<p>

  The XFree86 X servers will produce a lot of diagnostics output on
  stderr during startup. This output will be lost after the server
  reached a certain point in its console initialization process. You
  should redirect stdout and stderr if you want to analyze the
  diagnostics produced by the server.

  When the X server is running output made to other consoles will be
  lost. After server shutdown the screen contents of other consoles
  may be inconsistent with what one would expect (i.e. random).

<sect>Installing XFree86 manual pages<p><label id="installman">

  LynxOS uses cat-able manual pages, and because a doc preparation
  system is definitely not a vital component of a real-time operating
  system you must first install groff-1.09 (or newer). Starting with 
  LynxOS 2.3.0 it should compile right out of the box (or better tar archive).

  XFree86 manual pages may be installed using

  <tscreen><verb>
     make install.man
  </verb></tscreen>

  The index and whatis database for the XFree86 manual pages will be
  created automatically. If you already have a whatis database or
  index file in the destination directories you should perform a
  sort/uniq operation to remove duplicate entries:

  <tscreen><verb>
     for i in 1 3 5
     do
       rm -f /tmp/tmpfile
       sort /usr/X11R6/man/cat$i/LIST$i | uniq > /tmp/tmpfile
       mv /tmp/tmpfile /usr/X11R6/man/cat$i/LIST$i
     done
     sort /usr/X11R6/man/whatis | uniq > /tmp/tmpfile
     mv /tmp/tmpfile /usr/X11R6/man/whatis
  </verb></tscreen>
  
  With LynxOS 2.3.0 you should include <tt>/usr/X11R6/man</tt> in the MANPATH
  environment variable.

  <tscreen>
      bash:   <tt>MANPATH=&dollar;MANPATH:/usr/X11R6/man</tt>
  </tscreen>

  The man command of LynxOS 2.2.1 does not support the MANPATH
  environment variable properly. The XFree86 manual pages must be
  copied (or linked) to the standard manual page locations
  (<tt>/usr/man/catx</tt>) in  order to be read the man command:

  <tscreen><verb>
      for i in 1 3 5
      do
        ln -s /usr/X11R6/man/cat$i/*.* /usr/man/cat$i
        cat /usr/X11R6/man/cat$i/LIST$i >> /usr/man/cat$i/LIST$i
        sort -o /usr/man/cat$i/LIST$i /usr/man/cat$i/LIST$i
        cat /usr/X11R6/man/cat$i/whatis$i >> /usr/man/whatis
      done
  </verb></tscreen>

<sect>Using XFree86 with Motif<p>

  The Motif libraries shipped with LynxOS x86 2.3.0 and 2.4.0 can be
  used with the XFree86 libraries. Follow the steps outlined below after
  you have installed XFree86 and LynxOS Motif on your system.

<sect1>Copy Motif files<p>

  You must create symbolic links for the Motif libraries and 
  utilities in the <tt>/usr/X11R6</tt> directory tree.
  <tscreen><verb>
      ln -s /usr/bin/X11/uil /usr/X11R6/bin
      ln -s /usr/lib/libUil.a /usr/X11R6/lib
      ln -s /usr/lib/libMrm.a /usr/X11R6/lib
      ln -s /usr/lib/libXm.a /usr/X11R6/lib
      ln -s /usr/lib/X11/uid /usr/X11R6/lib/X11
      ln -s /usr/include/Xm /usr/X11R6/include
      ln -s /usr/include/Mrm /usr/X11R6/include
      ln -s /usr/include/uil /usr/X11R6/include
  </verb></tscreen>

  The Motif imake-configuration files are part of the LynxOS X Window
  package. They must be copied to the <tt>/usr/X11R6</tt> directory tree.
  <tscreen><verb>
      cp /usr/lib/X11/config/Motif.* /usr/X11R6/lib/X11/config
  </verb></tscreen>

<sect1>Motif library patch for LynxOS x86 2.3.0<p>

  The XFree86 libraries are compiled with the -mposix compiler option
  while the Motif libraries shipped with LynxOS x86 2.3.0 are not. This
  incompatibility will cause Motif <tt>XmFileSelection</tt> widgets to be linked 
  with the wrong (i.e. POSIX) directory routines. To circumvent this 
  problem apply the following patch to the library:
  <tscreen><verb>
      cp /usr/lib/libXm.a /usr/X11R6/lib
      ar x /usr/X11R6/lib/libXm.a Xmos.o
      ar x /lib/libc.a directory.s.o
      ld -r -o x.o Xmos.o directory.s.o
      mv x.o Xmos.o
      ar r /usr/X11R6/lib/libXm.a Xmos.o
  </verb></tscreen>
  
  This patch is not necessary for LynxOS revisions after 2.3.0.

<sect1>X11R6 config file patch<p>

  Edit <tt>/usr/X11R6/lib/X11/config/lynx.cf</tt> and change the definition
  of <tt>HasMotif</tt>
  <tscreen>
    from
  <verb>
       #define HasMotif    NO
  </verb>
    to
  <verb>
       #define HasMotif    YES
  </verb></tscreen>

<sect1>Motif config file patch<p>

  The file <tt>Motif.tmpl</tt> shipped with LynxOS Motif must be modified
  to work with XFree86. In every reference to <tt>UnsharedLibReferences</tt>
  the first argument must be changed
  <tscreen>
    from
  <verb>
       UnsharedLibReferences(<Something>LIB, Arg2, Arg3)
  </verb>
    to
  <verb>
       UnsharedLibReferences(<Something>, Arg2, Arg3)
  </verb></tscreen>
  Be sure to apply the change to the file copied to
  <tt>/usr/X11R6/lib/X11/config</tt>.

<sect>Compiling the XFree86 Distribution<p>

Before trying to rebuild XFree86 from source read <htmlurl url="BUILD.html"
name="Building XFree86"> for a detailed description of the build
process. The next sections contain LynxOS specific notes with
respect to the build process.


<sect1>Disk space requirements<p>
Currently there is no support for shared libraries in the LynxOS
XFree86 port. A complete binary installation along with manual pages
will require approximately 90-100 MBytes of disk space. To compile
the system you will need at least 230 MBytes of free disk space.

<sect1>Changes to system environment (LynxOS x86)<p>
Before compiling the XFree86 distribution you will have to make a
few little adjustments to your system:

  <descrip>
  <tag>LynxOS x86 2.5</tag>
  <itemize>
  <item>Create a shell script named <tt>/lib/cpp</tt> as follows:
  <tscreen><verb>
    #!/bin/sh
    /usr/lib/gcc-lib/i386-unknown-lynxos2.5/2.7-96q1/cpp \
	      -traditional "$@"
  </verb></tscreen>
    On other platforms than the AT the paths for the compiler support
    programs are different. You may use
  <tscreen><verb>
	gcc -v
  </verb></tscreen>
    to find out the correct path. Set the file mode of <tt>/lib/cpp</tt> with
  <tscreen><verb>
	# chown root /lib/cpp
	# chmod 755 /lib/cpp
  </verb></tscreen>
  <item>Modify <tt>/lib/liblynx.a</tt>. The X servers need the 
    <tt>smem_create()</tt> system call to map the frame buffer into their 
    address space. The system call is in <tt>liblynx</tt> library along
    with other Lynx proprietary calls which (unfortunately) overlap
    with calls in <tt>libc</tt>. To reduce confusion you should modify
    <tt>liblynx</tt> as follows:
  <tscreen><verb>
    # mv /lib/liblynx.a /lib/liblynx.a.ORG
    # mkdir /tmp/xx; cd /tmp/xx
    # ar xv /lib/liblynx.a.ORG
    # ar rv /lib/liblynx.a *smem*
    # ranlib /lib/liblynx.a
  </verb></tscreen>

  </itemize>
  <tag>LynxOS x86 2.4</tag>
  <itemize>
  <item>Use the CYGNUS GNU-C Compiler to build XFree86. With LynxOS 
    2.4.0 you must execute the shell script <tt>/CYGNUS.bash</tt> to 
    apply the necessary changes to your environment.
  <item>Create a shell script named <tt>/lib/cpp</tt> as follows:
  <tscreen><verb>
    #!/bin/sh
    /cygnus/94q4-lynxos-x86/lib/gcc-lib/i386-lynx/2.6-94q4/cpp \
	      -traditional "$@"
  </verb></tscreen>
    It is possible that future releases use a different path for
    the CYGNUS compiler support programs. You may use
  <tscreen><verb>
	gcc -v
  </verb></tscreen>
    to find out the correct path. Set the file mode of <tt>/lib/cpp</tt> with
  <tscreen><verb>
	# chown root /lib/cpp
	# chmod 755 /lib/cpp
  </verb></tscreen>
  </itemize>
  <tag>LynxOS x86 2.3</tag>
  This has actually not been tested, but the steps for described
  for 2.4 should apply to 2.3 as well.
  <tag>LynxOS x86 2.2.1</tag>
  This has actually never been tested, be prepared that the build will
  fail somewhere!
  <itemize>
  <item>Create a shell script named <tt>/lib/cpp</tt> as follows:
  <tscreen><verb>
    #!/bin/sh
    /usr/local/lib/gcc-cpp -traditional "$@"
  </verb></tscreen>
  <item>The loader /bin/ld of LynxOS 2.2.1 does not support the -L option
    which is heavily used by X11R6 makefiles. To work around this
    problem you must install a small wrapper program which replaces
    the original /bin/ld program. Use the following steps to install
    it:
  <tscreen><verb>
      # cd xc/programs/Xserver/hw/xfree/etc
      # cc -o ld ld-wrapper.c
      # mv /bin/ld /bin/ld.org
      # mv ld /bin/ld
      # chmod 511 /bin/ld
      # chown root /bin/ld
  </verb></tscreen>
  <item>Modify system header files as follows:
  <descrip>
    <tag><tt>/usr/include/uio.h</tt></tag> surrounded by
     <tscreen><verb>
          #ifndef _UIO_H
          #define _UIO_H
          ...
          #endif
     </verb></tscreen>
    <tag><tt>/usr/include/utmp.h</tt></tag> surrounded by
     <tscreen><verb>
          #ifndef _UTMP_H
          #define _UTMP_H
          ...
          #endif
     </verb></tscreen>
    <tag><tt>/usr/include/unistd.h</tt></tag> add
     <tscreen><verb>
          extern int read();
     </verb></tscreen>
    </descrip>
  </itemize>
  </descrip>

<sect1> make World<p>

  Read <htmlurl url="BUILD.html" name="Building XFree86"> before
  trying to rebuild XFree86 from the source distribution.

  You may then issue a

  <tscreen><verb>
     make World
  </verb></tscreen>

  to compile XFree86. After a few hours (and hopefully a successful
  build of the XFree86 system) you can install the software using

  <tscreen><verb>
     make install
  </verb></tscreen>

  You must be logged in as super-user (root) when you invoke `make
  install'.  Be sure to set your environment to use the same compiler
  (LynxOS 2.3.0/2.4.0, CYGNUS GNU-C) as you did during the `make World'. To
  install the LinkKit use

  <tscreen><verb>
     make install.linkkit
  </verb></tscreen>

  With LynxOS 2.2.1 programs will not be stripped during
  installation. This is due to a problem with the strip program which
  shows up when installing across file system boundaries.

  Refer to section <ref id="installman" name="Installing XFree86 manual pages"> 
  for manual page installation.

  On LynxOS x86 2.5.0 you may encounter problems with <tt>make</tt> in
  deeply nested subdirectories (eg core dumps, hangups). In this case
  update to GNU make version 3.75 or higher.

<sect>Building on microSPARC and PowerPC<label id="others"><p>

  XFree86 3.3 compiles on LynxOS microSPARC and on LynxOS PPC as well. On the
  microSPARC there is X server support for the colour frame buffers CG3 and CG6
  while on the PPC there is no X server available at this time. Before you 
  start the build (on versions earlier than 2.5.0) you must create a symbolic
  link from the CYGNUS gcc to a file named <tt>cc</tt> somewhere in a 
  directory included in your PATH environment variable.

<sect1>Console driver patch for microSPARC<p>

  Before building on the microSPARC you should install the patch for the console
  driver supplied in <tt>xc/programs/Xserver/hw/sunLynx/patch.Console</tt>.
  (<tt>xc/programs/Xserver/hw/sunLynx/patch.Console-2.4.0</tt> for LynxOS 
  revisions earlier than 2.5.0).
  The patch fixes minor problems in the original LynxOS driver and adds 
  functionalities to detect the keyboard type and control the key click.
  To create a backup of the original driver and install the patch issue 
  the commands
<tscreen><verb>
 # cd /
 # tar cf /sys/drivers/console.tar /sys/drivers/console
 # patch -p -E < xc/programs/Xserver/hw/sunLynx/patch.Console
 # cd /sys/drivers/console
 # make install
 # cd /sys/lynx.os
 # make install
 # reboot -a
</verb></tscreen>

  If you opt not to install the patch you must edit <tt>xc/config/cf/lynx.cf</tt>
  and change the definition of <tt>SparcConsoleDefines</tt>
  <tscreen>
    from
  <verb>
       #define SparcConsoleDefines    -DPATCHED_CONSOLE
  </verb>
    to
  <verb>
       #define SparcConsoleDefines    /* -DPATCHED_CONSOLE */
  </verb></tscreen>

<sect1>Known Bug of the microSPARC server<p>

  On the first start of the X server on the microSPARC you will notice that
  the pointer follows mouse movements with a certain delay (especially if
  you're moving the mouse real fast). You will also notice that moving 
  windows with certain window managers (eg mwm) is not working correctly. 
  These effects should go away on the next server start.

  The server for monochrome cards builds properly if you enable it in
  <tt>lynx.cf</tt> but it has never been tested (reports are welcome).

<verb>
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/LynxOS.sgml,v 3.14.2.11 1999/12/11 19:00:43 hohndel Exp $





$XConsortium: LynxOS.sgml /main/10 1996/10/28 05:13:07 kaleb $
</verb>
</article>
