README for XFree86 3.2 on OS/2

by Holger Veit, last modified on: 21 Oct 1996

1. Introductory Note about the release 3.2

Before looking into this file, please check for any LATEST.OS2 files that may come with the binary distribution.

This version of the code is called XFree86/OS2 3.2. This means it is a public release for which also the source code is provided. In contrast, a version with a letter, such as in ``3.1.2D'', for instance, is a beta version which has certain restrictions.

Previous beta versions have been tested in a large number of configurations and have been found to be working, with some bugs left, rather flawlessly. This code is released for public use by an end user, not only for developers, although this does not necessarily mean that it is easy to use or user friendly, or using a popular term, ``plug & play''. Emphasis is on functionality, not simple installation.

This release is complete (with one exception) regarding the X11R6.1 ``core'' distribution. The ``contrib'' distribution containing some of the more interesting tools for the end user, will be issued together with a later release (no need to start porting it independently).

In the past beta testing, it has been found that the software itself is rather stable and does not damage hardware - provided the user does not try to push the builtin limits and change certain configuration parameters which could operate the video hardware out of specs.

However,

It is recommended that you backup essential data of your system before installing this software, but this should be your general precautions before ANY installation. No reports exist that a crashing X server itself actively destroys or modifies data, but it is possible in rare cases that the system is left in an unusable state (video display mode garbled or system unresponsive, not reacting to mouse or keyboard actions). If you then hard reset or switch off the system, file caches of the operating system might not be written correctly back to disk, thus causing data loss.

2. What and Where is XFree86?

XFree86 is a port of X11R6 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 code, as well as binary distributions for many architectures.

XFree86/OS2 is the name of the implementation of XFree86 on OS/2 based systems.

See the Copyright Notice <COPYRIGHT.html>.

The sources for XFree86/OS2 are available by anonymous ftp from:

Binaries for OS/2 Warp and Merlin are available from: The WWW page set.gmd.de:/~veit/os2/xf86os2.html usually show more references to FTP or WWW sites to retrieve sources or binaries.

Versions:

XFree86/OS2 will run on all dialects of Warp, including Warp "red spine box", Warp "blue spine box", Warp Connect, Warp Server, and Merlin. For Warp fixpack level 17 is mandatory, a later fixpack level (e.g. FP22) is recommended. In some future, a more recent fixpack might be necessary. Please check a LATEST.OS2 file.

OS/2 2.11 is no longer supported beginning with this release, due to lack of a working test environment. Consequently, OS/2 SMP is not supported either, because this is currently based on OS/2 2.11. OS/2 versions 1.X are definitely not supported and will never be.

It is possible to build XFree86/OS2 from the sources. Read about this in some section below.

3. Bug Reports for This Document

Send email to Holger.Veit@gmd.de (Holger Veit) or XFree86@XFree86.org if you have comments or suggestions about this file and we'll revise it.

4. Hardware and Software Requirements

4.1. Supported, Required, and Recommended Hardware

4.2. Required Software

5. Installing the System

The binary distribution is composed of a number of zip archives which are the executables, servers, fonts, libraries, include files, man pages, and config files. The full distribution requires about 40-55MB of disk space.

All archives of this alpha version are packed with the info-zip utility, which is available under the name UNZ512X2.EXE from many OS/2 archives. Please obtain a native OS/2 version of this unpacker. DOS PKUNZIP does not work, because it cannot unpack long file names and extended attributes.

At this moment, the distribution covers only the ``core'' distribution which somewhat reduces the usability. Refer to WWW sites and archives listed in the XFree86/OS2 FAQ and elsewhere to obtain prebuilt X clients which were ported to XFree86.

The contents of the packages are:

REQUIRED:

XF32base
A special device driver and the SuperProbe program
XF32doc
READMEs and XFree86 specific man pages.
XF32bin
all of the executable X client applications and shared libs
XF32fnts
the misc and 75dpi fonts
emxrt
Runtime libraries of EMX. Version 0.9C fixlevel 1 required.

Choose at least one of the following to match your hardware:

The X servers are available in two flavours: full=XF32* and small=S312*, small means that they do not contain PEX, XI, XKB and XIE support; otherwise they are functionally equivalent. You may want to have the small servers for less powerful systems, as the executable is about 1MB smaller.
XF328514
the X server for IBM 8514/A and compatible boards
XF32AGX
the X server for AGX boards
XF32I128
the X server for #9 Imagination 128 boards
XF32Ma32
the X server for ATI Mach32 graphics boards
XF32Ma64
the X server for ATI Mach64 graphics boards
XF32Ma8
the X server for ATI Mach8 graphics boards
XF32Mono
the Monochrome X Server
XF32P9K
the X server for P9000 based boards
XF32S3
the X server for S3 based boards (excluding S3 ViRGE)
XF32S3V
the X server for S3 ViRGE based boards
XF32Svga
the 8-bit pseudo-color X server for Super VGA cards
XF32vg16
the 4-bit pseudo-color X server for VGA & SVGA cards.
XF32w32
the X server for et4000w32 based boards

OPTIONAL:

XF32man
pre-formatted man pages for the X11 interface and clients
XF32f100
100dpi fonts
XF32fscl
Speedo and Type1 fonts
XF32fnon
Japanese, Chinese and other fonts
XF32fcyr
Cyrillic fonts
XF32fsrv
the font server with man pages.
XF32prog
the X11 header files and programmer's utilities for compiling other X applications
XF32pex
PEX fonts and libraries required for PEX applications
XF32nest
the Xnest X server
XF32vfb
the virtual frame buffer X server

In order to save space on your disk and reduce net bandwidth, choose the software to obtain carefully. Each X server is an archive of about 1.4MB and occupies 2.5MB on the disk. You won't normally need more than the single Xserver tailored to your video card.

If it is your first time install, get the XF32base archive before any of the other packages. This package contains a driver and a test program, which analyzes your video hardware. If this program fails or reports an incompatible hardware, it makes no sense to obtain the other packages in the hope that they would magically work.

6. Updating from a previous alpha or beta version

In general, it is not guaranteed, that newer versions will be fully compatible with older ones, particularly when upgrading from a alpha or beta version to a release version. In this special case, it works. If you are upgrading from 3.1.2D...G, you can simply overwrite the old system with new archives. Be sure that you install at least the following archives: If you have changed some command files, save them in advance manually.

7. Checking Compatibility of Video Hardware

In the following, we assume that you want to install XFree86/OS2 on a disk drive with the letter Y: (which you probably don't have). Change the letter in all commands accordingly.
  1. Obtain the package XF32base and install it from the root directory of the Y: drive, by entering the following commands:
              [C:\] Y:
              [Y:\] cd \
              [Y:\] unzip \path_of_package\XF32base.zip
    
  2. Edit your CONFIG.SYS file to contain the following line somewhere:
              DEVICE=Y:\XFree86\lib\xf86sup.sys
    
    Of course replace ``Y:'' with the correct drive letter.
  3. At this point, you may consider adding the variables required for XFree86/OS2 as well, which will save you from one additional reboot. Refer to section ``Adding Variables to CONFIG.SYS'' below.
  4. After adding the device driver entry to the CONFIG.SYS file, you must reboot to install the driver. XFree86/OS2 will not work without this driver.
  5. Start a full screen OS/2 CMD session and enter the following command:
              [C:\] Y:\XFree86\bin\SuperProbe
    
  6. This command will (normally) report important information about your video configuration, i.e. the type of chipset, the available video memory and the RAMDAC circuit available. It is basically also a test that the XF86SUP.SYS driver is working correctly. Please write this down or redirect the output of ``SuperProbe'' into a file by entering:
         [C:\] Y:\XFree86\bin\SuperProbe >filename
    
  7. SuperProbe can identify many more video cards than are supported by XFree86. In some cases, Superprobe unfortunately detects a wrong card, often it claims to have seen a MCGA card which is some sort of a fallback. Generally, if it is approximately right, there are only few reasons for doubts; if it is totally off (e.g. saying it has seen a ET4000, and you have a Cirrus card), you should report a misdetection as a bug to the given address. In all cases, please take the few minutes and check the accompanying README.* files to check for special precautions, options, or features of the card.
  8. If the README files tell you that your hardware is supported, please obtain the rest of the software.

8. Installing the packages

XFree86/OS2 assumes a directory hierarchy starting from drive:\XFree86. This can be changed, but is strictly discouraged.
  1. Choose a HPFS partition with sufficient free space.
  2. For each package to install, go to the root directory of this drive, and type:
              [Y:\] cd \
              [Y:\] unzip \path_of_packages\XF32xxxx.zip
    

9. Adding Variables to CONFIG.SYS

XFree86/OS2 requires a number of settings in the CONFIG.SYS file to work correctly. Please add the following settings:
TERM
Set the preferred terminal type for the xterm or editor to be used. Some programs need this setting. I have my type set to
          SET TERM=ansi
\XFree86\lib\X11\etc\emx.termcap.x11 contains a suitable termcap which can be used in place of termcap files that come with EMX, EMACS, or other ported software.
TERMCAP
This variable must be set to the location where the termcap file used for the above TERM variable is searched. My setting, for instance, is:
          SET TERMCAP=D:/EMX/ETC/EMX.TERMCAP.X11
Note that forward ``/'' is used as a directory separator.
ETC
Set to an ETC directory. Normally, this is already set to the ETC directory of the TCP/IP code, such as
          SET ETC=C:\TCPIP\ETC
TMP
Set to an TMP directory. Normally, this is already set to the TMP directory of the TCP/IP code, such as
          SET TMP=C:\TCPIP\TMP
HOSTNAME
Set to the internet hostname. Normally, this is already set by the TCP/IP installation program, such as
          SET HOSTNAME=myhost
With IAK, you would normally run a loopback configuration and would then set this to
          SET HOSTNAME=localhost
USER
LOGNAME
Set both to a username. Currently, they are there just to make some programs happy; in the future, this variable might be set by a login shell of a multiuser configuration. My variable, for instance, is set to
          SET USER=holger
          SET LOGNAME=holger
HOME
Set this to an existing directory that is supposed to be a home directory of a user. Some utilities place temporary and init files here. This is also future investment for a multiuser configuration, but must still be there. For instance, this variable might be set to
          SET HOME=H:\user\holger
X11ROOT
This is one of the most important settings, it determines the root of the XFree86 directory tree. Normally, you will set this to the drive letter of the partition where the \XFree86 tree resides, such as in
          SET X11ROOT=Y:
You may try to move the tree to another subdirectory, e.g. to K:\OS2\X11\XFree86... and would then have to change this to
          SET X11ROOT=K:/OS2/X11
but this is discouraged, since some utilities might not accept this. Note the forward ``/'' as a directory separator here.
DISPLAY
This variable may be set to the display to be used for displaying clients. Depending on how this variable is set, XFree86 will use either a local pipe transport or a socket transport for local clients. The pipe transport consumes less resources, and should be preferred. Normally, you can set DISPLAY to be simply ":0.0", which will select the pipe transport:
          SET DISPLAY=:0.0
Other DISPLAY strings can also be used. Shown below are a few examples of pipe transport and socket transport DISPLAY strings:
	SET DISPLAY=local/:0.0             
	SET DISPLAY=local/hostname:0.0
Selects the local pipe transport.
 
	SET DISPLAY=hostname:0.0       
	SET DISPLAY=inet/hostname:0.0
Selects the socket transport.

Read the X11 man page on the exact meaning of these postfixes and other options.

XSERVER
Set this to the executable name of the X server to be used. This must be a complete path. My setting is as follows:
          SET XSERVER=D:/XFree86/bin/XF86_Mach64.exe
PATH
Add the binary directory for the X11 utilities to your search PATH. This is normally the directory (adjust the letter)
          Y:\XFree86\bin
It is possible to move the binaries to another directory in the search path; for maintenance reasons and clarity of the structure, this is not recommended, though.
LIBPATH
Add the DLL directory for the X11 utilities to the LIBPATH. This is normally the directory (adjust the letter)
          Y:\XFree86\lib

It is possible to move the DLLs to another directory in the library path; for maintenance reasons and clarity of the structure, this is not recommended, though. Note that Y:\XFree86\lib has several other subdirectories; these may not be moved elsewhere, rather they must stay there, because most utilities form a path to these directories by using %X11ROOT%\XFree86\lib as a base.

The recent version of XFree86/OS2 has a REXX script named checkinstall.cmd which you can (and should) use to check whether you have entered most things correctly. This is not bullet-proof, but prevents the most obvious setup problems.

10. Remarks on the Network Configuration

It is beyond the scope of this document to even give an introduction about the correct installation of the TCP/IP networking system. You must do this yourself or seek assistance elsewhere. It is only possible to say here that a PC working well in a TCP/IP based LAN network will also work with XFree86/OS2 (when all other prerequisites are matched as well).

With IAK, there is a special configuration necessary, unless you want to use XFree86/OS2 only during a hot link to your Internet provider, the so called ``localhost'' or ``loopback'' configuration. This is a local network interface which ``loops'' back to the same host. The following settings are necessary for this:

  1. Create a file \tcpip\etc\hosts with the following content:
              127.0.0.1  localhost
    
    Be sure that this line ends with a newline, a very common problem. If your ETC environment variable points to another directory, put the "hosts" file in that directory.
  2. Add the following line to your \tcpip\bin\tcpstart.cmd:
              ifconfig lo 127.0.0.1 up
    
    If this file does not exist, create it, and add it to your startup folder, or start it via RUN= from CONFIG.SYS. The above will start up the loopback interface, and assign it the usual address of 127.0.0.1.
  3. Set the HOSTNAME environment variable to localhost as described in the last section.
  4. Add the following line to CONFIG.SYS:
              SET USE_HOSTS_FIRST=1
    
    This tells TCP/IP to search through your \tcpip\etc\hosts file before doing a DNS lookup when resolving names to IP addresses.
  5. After rebooting, verify that the following command works:
              [C:\] ping localhost
    
    If this works, then the loopback interface is probably functionning properly.

The checkinstall.cmd script coming with XFree86/OS2 gives some advice here as well.

If you have problems to get this or other basic networking things running, seek assistance elsewhere.

11. Configuring X for Your Hardware

After you have added the required settings and setup a working network, run the xf86config program to create a standard configuration file in Y:\XFree86\lib\X11\XConfig from a windowed or full screen OS/2 text session:
       [C:\] xf86config
This program will ask a number of questions. You will need the information obtained from the SuperProbe program here. The program should be self explanatory; if you have problems to understand something though, seek assistance in the newsgroups.

Alternatively, but not recommended for the non-expert, you can edit the XConfig file manually with a text editor. A sample file is in Y:\XFree86\lib\X11\XConfig.eg, which can be used as a starting point.

For details about the XF86Config file format, refer to the XF86Config.(4/5) manual page.

If you know the configuration process from Linux or other XFree86 platform, you will encounter a few differences:

In most cases, an existing XF86Config file for the same XFree86 version from Linux or another platform may be used without changes. There is one prominent exception: some S3 805 based VLB cards put their video memory in odd locations. The X server can search for this memory by experimentally mapping and unmapping possible memory regions. In XFree86/OS2, the OS may run out of memory tiles during this process. If this happens, you must find out the location of the memory yourself and add it as an option

  
  	MemBase 0x12345678
to the XConfig file.

Once you've set up a XF86Config file, you can fine tune the video modes with the xvidtune utility.

12. Running X

16mb of memory is a recommended minimum for running the network software, X and the presentation manager in parallel. The server, window manager and an xterm take about 4-6 Mb of memory themselves. X will start up on a system with 8MB or less, but the performance will severely suffer from heavy disk swapping. Your mileage may vary, though, so some people might consider this still tolerable.

The easiest way for new users to start X windows is to type:

       [C:\] startx
To get out of X windows, type: ``exit'' in the console xterm. You can customize your X by creating .xinitrc, .xserverrc, and .twmrc files in the directory that the HOME environment variable points to. These files are described in the xinit and startx man pages.

If you want to use XFree86/OS2 as some sort of an X terminal, start the X server with the option -query to connect to an XDMCP server, such as:

  [C:\] XF86_SVGA -query remoteservername

13. Rebuilding the XFree86 Distribution

Do you really want to rebuild XFree86/OS2 from source? Read the file OS2.Notes on details to recompile XFree86/OS2 from scratch.

14. Building New X Clients

The easiest way to build a new client (X application) is to use xmkmf if an Imakefile is included in the sources. Type ``xmkmf -a'' to create the Makefiles, check the configuration if necessary and type ``xmake''. ``xmake'' is a wrapper for the GNU make program which defeats the improper SHELL setting typically found in a Makefile generated from an Imakefile. Also see the XFree86/OS2 FAQ for more hints about porting X clients.

15. Acknowledgements

Many thanks to:
Reply to: Holger.Veit@gmd.de