                        README for XFree86 on LynxOS

                               Thomas Mueller

                     Last modified on: 15 November 1999

1.  What and Where is XFree86?

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 improve-
ments 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 Copyright Notice.

The sources for XFree86 are available by anonymous ftp from:

ftp://ftp.XFree86.org/pub/XFree86/current

Binaries of XFree86 for LynxOS x86 are available from:

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 plat-
form. X servers are currently available on the AT and microSPARC platform.
Refer to section Building on microSPARC and PowerPC (section 7., page 1) 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 (tmueller@sysgo.de).

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

2.  Installing the Binaries

Please refer to section "Installing the XFree86 3.3.6 Release" of the Release
Notes for detailed installation instructions.

If you plan to install XF86Setup you'll have to install 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 X336prog.

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

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

Refer to the next section Running XFree86 (section 3., page 1) for further
information on necessary configuration steps before running XFree86 on
LynxOS.

3.  Running XFree86

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

Read Quick-Start Guide  to XFree86 Setup to learn more about how to configure
XFree86 for your hardware.

3.1  System requirements

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).

3.2  System tuning

3.2.1  Tunable parameters

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

       #define X_WINDOWS

in /sys/lynx.os/uparam.h.

For earlier versions you'll have to edit /usr/include/param.h:

       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

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

3.2.2  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
/sys/lynx.os/uparam.h from 10 to 20."

3.2.3  Increase number of ptys

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

3.2.4  Kernel build

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:

          # cd /sys/lynx.os
          # make install
          # reboot -N

3.3  Mouse support in XFree86

XFree86 includes support for PnP mice (see also 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
Microsoft 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 per-
form protocol conversion and requires to set the mouse type to PS/2. This
driver will also support the extended PS/2 mouse types.

3.4  Bus mouse drivers

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

         # cd /
         # bash /usr/X11R6/lib/X11/etc/BM-Lynx.shar

and follow the notes in /BMOUSE.Readme for further installation and configu-
ration 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.

3.5  ATC console driver and VT switching

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
/etc/ttys, e.g. /dev/atc3:

change

            /dev/atc3:1:default:vt100at:/bin/login

to

            /dev/atc3:0:default:vt100at:/bin/login
                      ^

3.6  X Server debug diagnostics output and other VT peculiarities

The XFree86 X servers will produce a lot of diagnostics output on stderr dur-
ing 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 inconsis-
tent with what one would expect (i.e. random).

4.  Installing XFree86 manual pages

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

          make install.man

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:

          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

With LynxOS 2.3.0 you should include /usr/X11R6/man in the MANPATH environ-
ment variable.

     bash:   MANPATH=$MANPATH:/usr/X11R6/man

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 (/usr/man/catx) in  order to be read the man
command:

           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

5.  Using XFree86 with Motif

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.

5.1  Copy Motif files

You must create symbolic links for the Motif libraries and utilities in the
/usr/X11R6 directory tree.

           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

The Motif imake-configuration files are part of the LynxOS X Window package.
They must be copied to the /usr/X11R6 directory tree.

           cp /usr/lib/X11/config/Motif.* /usr/X11R6/lib/X11/config

5.2  Motif library patch for LynxOS x86 2.3.0

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 XmFileSelection widgets to be linked with the wrong (i.e.
POSIX) directory routines. To circumvent this problem apply the following
patch to the library:

           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

This patch is not necessary for LynxOS revisions after 2.3.0.

5.3  X11R6 config file patch

Edit /usr/X11R6/lib/X11/config/lynx.cf and change the definition of HasMotif
from

            #define HasMotif    NO

to

            #define HasMotif    YES

5.4  Motif config file patch

The file Motif.tmpl shipped with LynxOS Motif must be modified to work with
XFree86. In every reference to UnsharedLibReferences the first argument must
be changed from

            UnsharedLibReferences(<Something>LIB, Arg2, Arg3)

to

            UnsharedLibReferences(<Something>, Arg2, Arg3)

Be sure to apply the change to the file copied to /usr/X11R6/lib/X11/config.

6.  Compiling the XFree86 Distribution

Before trying to rebuild XFree86 from source read Building XFree86 for a
detailed description of the build process. The next sections contain LynxOS
specific notes with respect to the build process.

6.1  Disk space requirements

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.

6.2  Changes to system environment (LynxOS x86)

Before compiling the XFree86 distribution you will have to make a few little
adjustments to your system:

      LynxOS x86 2.5

               o Create a shell script named /lib/cpp as follows:

                          #!/bin/sh
                          /usr/lib/gcc-lib/i386-unknown-lynxos2.5/2.7-96q1/cpp \
                                 -traditional "$@"

                 On other platforms than the AT the paths for the compiler
                 support programs are different. You may use

                           gcc -v

                 to find out the correct path. Set the file mode of /lib/cpp
                 with

                           # chown root /lib/cpp
                           # chmod 755 /lib/cpp

               o Modify /lib/liblynx.a. The X servers need the smem_create()
                 system call to map the frame buffer into their address
                 space. The system call is in liblynx library along with
                 other Lynx proprietary calls which (unfortunately) overlap
                 with calls in libc. To reduce confusion you should modify
                 liblynx as follows:

                          # 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

      LynxOS x86 2.4

               o Use the CYGNUS GNU-C Compiler to build XFree86. With LynxOS
                 2.4.0 you must execute the shell script /CYGNUS.bash to
                 apply the necessary changes to your environment.

               o Create a shell script named /lib/cpp as follows:

                          #!/bin/sh
                          /cygnus/94q4-lynxos-x86/lib/gcc-lib/i386-lynx/2.6-94q4/cpp \
                                 -traditional "$@"

                 It is possible that future releases use a different path for
                 the CYGNUS compiler support programs. You may use

                           gcc -v

                 to find out the correct path. Set the file mode of /lib/cpp
                 with

                           # chown root /lib/cpp
                           # chmod 755 /lib/cpp

      LynxOS x86 2.3
            This has actually not been tested, but the steps for described
            for 2.4 should apply to 2.3 as well.

      LynxOS x86 2.2.1
            This has actually never been tested, be prepared that the build
            will fail somewhere!

               o Create a shell script named /lib/cpp as follows:

                          #!/bin/sh
                          /usr/local/lib/gcc-cpp -traditional "$@"

               o 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 follow-
                 ing steps to install it:

                            # 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

               o Modify system header files as follows:

                       /usr/include/uio.h
                             surrounded by

                                            #ifndef _UIO_H
                                            #define _UIO_H
                                            ...
                                            #endif

                       /usr/include/utmp.h
                             surrounded by

                                            #ifndef _UTMP_H
                                            #define _UTMP_H
                                            ...
                                            #endif

                       /usr/include/unistd.h
                             add

                                            extern int read();

6.3  make World

Read Building XFree86 before trying to rebuild XFree86 from the source dis-
tribution.

You may then issue a

          make World

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

          make install

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

          make install.linkkit

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 Installing XFree86 manual pages (section 4., page 1) for
manual page installation.

On LynxOS x86 2.5.0 you may encounter problems with make in deeply nested
subdirectories (eg core dumps, hangups). In this case update to GNU make ver-
sion 3.75 or higher.

7.  Building on microSPARC and PowerPC

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 cc somewhere in a directory included
in your PATH environment variable.

7.1  Console driver patch for microSPARC

Before building on the microSPARC you should install the patch for the con-
sole driver supplied in xc/programs/Xserver/hw/sunLynx/patch.Console.
(xc/programs/Xserver/hw/sunLynx/patch.Console-2.4.0 for LynxOS revisions ear-
lier 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

      # 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

If you opt not to install the patch you must edit xc/config/cf/lynx.cf and
change the definition of SparcConsoleDefines from

            #define SparcConsoleDefines    -DPATCHED_CONSOLE

to

            #define SparcConsoleDefines    /* -DPATCHED_CONSOLE */

7.2  Known Bug of the microSPARC server

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 lynx.cf
but it has never been tested (reports are welcome).

     Generated from 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 $

