The X11 Files

By Christian Hennecke

General info
The X11 windowing system is the standard on Unix-like systems for displaying windows. It can roughly be compared to OS/2's Presentation Manager. The XFree86 Consortium provides a freeware port for Intel x86 based platforms. Holger Veit and Frank Giessler ported XFree86 to OS/2 and eComStation (eCS).

X11 systems have a client/server structure. The so-called X server (the displaying system) offers its capabilities to the X clients (the applications) to display their output. Due to the X systems networking capabilities server and client can be sited on different machines which are connected via a network (e.g. a TCP/IP LAN or a TCP/IP based dial-up connection).

Now you might ask what to do with a Unix system when you're running OS/2. Well, using XFree86/OS2 and its client/server architecture offers you the following possibilities:


 * Use your OS/2 machine to login to a Unix machine, start programs on that remote machine and let them display their output and user interface on your local OS/2 machine. Think of sitting at home and doing some work using the machines at work or a 1000 miles away.
 * Run ported Unix programs on your local OS/2 machine.

What makes the whole thing especially interesting is the fact that Unix programs can relatively easy be ported to OS/2 with the help of the emx package. This package consists of some libraries that provide Unix-features which OS/2 and eCS lack and the GNU gcc compiler that can be used to compile e.g. C, C++, Objective C, Ada95 and Fortran77 programs. Using emx it sometimes is enough to compile the Unix programs' source code to get a working program. Meanwhile lots of programs have been ported and the list is growing...

Please take a look at the following highlights of ported applications:


 * The GIMP (The Graphics Image Manipulation Package). This freeware package isn't that far from Photoshop's functionality and can be extended using a plug-in architecture. Using the xscanimage plug-in you can also directly scan into The GIMP.
 * LyX is a GUI for LaTeX that allows to compose documents very similar to WYSIWYG word processors. The installation including the setup of emTeX, Ghostscript and XDVI can be a bit tricky, but the LyX package comes with a helpful README.

XFree86OS/2 is not able to display windows seamlessly on the OS/2 desktop, but can be run at the same time. Since it directly accesses the video hardware, it is also very fast. There's a Netlabs project called Everblue which aims at making seamless X windows on the OS/2 desktop possible, similar to packages like the withdrawn PMX from IBM, Hummingbird's Exceed or HOBLink X11.

Installing XFree86/OS2 seems a bit complicated first, but if you follow the instructions given in the distributions README and the pretty extensive step-by-step guides on these pages there should be no big problems. You can make your life easier by purchasing a Team Trier Collection CD which contains XFree86 3.3.6 which can directly be installed from the CD.

Well, there are some "disadvantages" using XFree86/OS2:


 * To start working under XFree86/OS2 you should have some knowledge about Unix basics, like directory structure and shell commands, since most of the programs take some things for granted and won't work otherwise. These "things" often are not (sufficiently) documented and so you can e.g. come across the question where to put certain files. Therefor this site offers a guide on setting up a unixish environment for OS/2.
 * XFree86 itself doesn't need very much harddrive space considering that it is a complete video subsystem. But then to successfully operate the ported programs you'll need several tools and utilities that are not always mentioned in the READMEs. Once you have installed all these the used harddisk space has somewhat grown. For help on installation see the guide at this site.
 * Unix systems don't know about driveletters, there is nothing like C:. You may come across some quick ports that haven't been extended for driveletter support and therefor can only access files residing on the same drive as themselves. To access data on other drives you can use the Toronto Virtual File System (TVFS) and mount all relevant files and directories on one drive.
 * Many programs have to be used with tons of cryptic command line options and are not very user friendly. And their documentation is often a bit, hm, rough. Man pages are good as a reference, but not for teaching yourself how to operate the software.
 * There is no standardized user interface. Instead there are lots of window managers with different features available. Most window managers have to be configured by hand-editing files. There's no drag & drop or configuration menus.

To be fair one has to say that most of these disadvantages are not the ones of XFree86/OS2, but result from Unix systems' structure. In the following you can find some directions to ease your life with XFree86/OS2.


 * First of all see if your graphics card is supported by XFree86/OS2. The README lists several cards and chipsets.
 * Make yourself a pot of coffee or tea before starting the installation!
 * Read the READMEs and the X11OS2FAQ!
 * Get the emx+gcc package and the GNU utilities FIND, FUTIL, GREP, SED, SUTIL, and TUTIL from os2site.com. Hopefully, the UnixOS2 project will solve all problems in the future. It aims at creating a kind of Unix distribution for OS/2 that is easy to install.
 * Read the guide on setting up a unixish environment for OS/2 on this site!
 * Most configuration files have to be edited with a X-editor (e.g. xed or gxedit) or EPM in Unix mode (use parameter /U). OS/2 and Unix systems use different codes to terminate a line. Editing a file with an editor using different codes will result in programs not being able to read their configuration.
 * Don't panic! If you can't it to work have a look at the FAQ or send a problem report to the XFree86/OS2 mailing list or an OS/2 newsgroup. The mailing list even has a searchable archive.

Hardware
At least a computer with a 486DX33 and 16MB RAM is required. Machines with 386 CPUs or with 8MB or less memory are insufficient. A Pentium or Pentium Pro class processor and - especially - more main memory is recommended.

There are no specific requirements concerning network cards, disk types, or CD-ROM equipment; of course the more powerful, the better.

Depending on the packages installed, a disk space of 20-55MB on a HPFS formatted partition (or a JFS, NFS or ext2fs partition natively allowing long filenames) is required. (Note however that many applications require certain other packages. See Setting up a Unix-like environment for OS/2 on this site.) XFree86/OS2 will not run on FAT partitions.

You will also need a video card, or better a video chipset which is supported by XFree86. Note that the sets of video cards supported by XFree86 on one hand and OS/2 on the other hand overlap, but do not match exactly, i.e. the fact that your card is supported by OS/2 does not mean it works with XFree86 as well, and vice versa. XFree86 does not use the video services of the OS/2 operating system.

Software
Supported OS/2 versions are Warp 3 or Warp 3 Connect with at least fixpak 17 applied, Warp Server (including SMP) with the corresponding fixpak, Warp 4, Warp Server for e-Business, the IBM Convenience Packs (aka Warp 4.5x), and eComStation.

XFree86/OS2 may use a local named-pipe connection or a TCP/IP based network connection.


 * Warp comes with the Internet Access Kit (IAK), which is sufficient. Warp Connect and Warp Server are delivered with a full version of TCP/IP 3.0. Use of this software is preferred over IAK then.
 * Warp 4 comes with TCP/IP 4.0 which also works. Be sure to apply the available fixes, though.
 * The 32-bit versions TCP/IP 4.1 and later are available via IBM Software Choice. They also come with Warp Server for e-Business, the IBM Convenience Packs, and eComStation. To use these products you will need EMX 0.9c fix 4 or later. The latest EMX 0.9d is recommended.
 * The old IBM TCP/IP 2.0, that comes with the IBM PMX product may be used with Warp as well, although it is no longer supported by IBM. Please ensure that you have the latest Corrective Service Disks (CSDs) installed.

Other versions of TCP/IP, such as FTP's, DEC's, or Hummingbird's TCP/IP versions, as well as IBM TCP/IP 1.X are not supported. Nor does any networking support from DOS (packet drivers, winsock), Netware, or NetBIOS work.

This is a slightly changed version of parts of the README.OS2 from the XFree86/OS2 distribution, © Holger Veit.

Installation version 3.3.x
The binary distribution consists of a number of ZIP files containing programs, servers, fonts, libraries, include files, man documentation pages und configuration files. The complete distribution requires 40-55MB space on your harddisk.

1. Choosing the software
The XFree86/OS2 distribution only includes the "core" and no applications and consists of the following packages:

Required packages

 * Xbase - a special driver and the Superprobe program CAUTION: Due to changes in OS/2 versions based on Warp Server for e-Business code (WSeB, Warp 4 with fixpak 13 and later, eComStation) you must use the latest version of the XF86SUP.SYS driver from this archive!


 * Xdoc - READMEs and man documentation pages specific for XFree86


 * Xbin - all executable X client applications and shared libraries


 * Xfnts - assorted fonts incuding 75dpi fonts


 * emxrt - EMX runtime library (only if you don't have emx installed on your system)

You will need at least one of the following, video hardware specific packages:


 * X8514 - X server for IBM 8514/A and compatible


 * XAGX - X server for AGX


 * XGlnt - X server for Permedia / GLINT


 * XI128 - X server for #9 Imagination 128


 * XMa32 - X server for ATI Mach32


 * XMa64 - X server for ATI Mach64
 * XMa8 - X server for ATI Mach8
 * XMono - the monochrome X server
 * XP9K - X server for P9000
 * XS3 - X server for S3 (ohne S3 ViRGE)
 * XS3V - X server for S3 ViRGE
 * XSVGA - the 8bit pseudocolor X server for Super VGA adapters, also includes the X server for Matrox chipsets with full hardware acceleration
 * XVG16 - the 4bit pseudocolor X server for VGA & SVGA adapters
 * XW32 - X server for Tseng ET4000W32

Optional packages:

 * Xman - formatted man documentation pages for the X11 interface and the included X clients
 * Xf100 - 100dpi fonts
 * Xfscl - Speedo and Type1 fonts
 * Xfnon - Japanese, Chinese and other fonts
 * Xfcyr - Cyrillic fonts
 * Xfsvr - font server and man pages
 * Xprog - X11 header files and tools for developers, needed for compiling X applications
 * Xpex - PEX fonts and libraries for PEX applications

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.2MB and occupies 3.0MB 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 Xbase 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.

2. Checking the compatibility of the video hardware
In the following we assume that you install XFree86/OS2 on drive Y: in the directory Y:\XFree8. Please adapt the commands and file entries according to your real choice. Placing the directory XFree86 in the root of the drive is not necessary per se. However, several software packages have this location hardcoded (i.e. it can't be changed) and won't run otherwise. Let's also assume that the XFree86/OS2 distribution's archives reside in a directory X:\xtemp.

CAUTION: The drive you install XFree86/OS2 to must support long filenames!

Open an OS/2 Commandline, change to the root of drive Y: and unzip (i.e. decompress) the archive Xbase into the root of drive Y:. Enter the following commands to accomplish this task:

[C:\] Y:   [Y:\] cd \ [Y:\] unzip X:\xtemp\Xbase.zip

The unpacking process automatically created some directories.

Add the following line to your CONFIG.SYS file:

DEVICE=Y:\XFree86\lib\xf86sup.sys

If you are sure that XFree86/OS2 supports your video adapter, adding (or changing) the required environment variables to your CONFIG.SYS file will save you from one additional reboot. (refer to section Changing CONFIG.SYS)

Shutdown OS/2 and reboot to load the XF86SUP.SYS driver. XFree86/OS2 will not work without it.

Open an OS/2 fullscreen session and enter the following command:

[C:\] Y:\XFree86\bin\SuperProbe

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. Please write this down or redirect the output of Superprobe to a file by entering:

[C:\] Y:\XFree86\bin\SuperProbe >filename

You can then open this textfile later to recall the information.

Superprobe can identify many more video cards than XFree86/OS2 supports. Though in some cases, Superprobe detects a wrong card and often claims that it's a MCGA card which is some kind 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 maintainers.

In all cases, please take some time to carefully check the accompanying README.* file in the Y:\XFree86\lib\X11\doc directory for special precautions, options, or features of the card.

If your card is supported, please obtain the rest of the software.

3. Unpacking the archives
XFree86/OS2 assumes a certain directory hierarchy starting from Y:\XFree86. This can be changed, but is strictly discouraged. As already mentioned above, the directory XFree86 is best placed in the root of the chosen drive, since some programs will refuse to work due to hardcoded paths.

Ensure that drive Y: supports long filenames and has sufficient free space.

Open an OS/2 commandline and unpack all archives located in X:\xtemp by issueing the commands:

[C:\] Y:   [Y:\] cd \ [Y:\] unzip X:\xtemp\*.zip

During the unpacking process UNZIP may report that some files already exist, e.g. the X server archives contain README files that are also included in Xdoc. These files are identical. Don't worry and let UNZIP replace the files. By entering A (in uppercase!) all subsequent files will be overwritten if they already exist without asking again.

No special sequence is required for unpacking the archives.

4. Changing CONFIG.SYS
XFree86/OS2 requires a number of settings in CONFIG.SYS to work correctly. Please add the following changes to your CONFIG.SYS and in particular take care of the writing of paths with slash "/" and backslash "\". You can transfer the settings with cut & paste and then adapt them to your system.

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 which can be used in place of termcap files that come with EMX, EMACS, or other ported software.

TERMCAP - This variable must contain the path to the termcap file which is used for the above TERM setting. If you want to use termcap.x11 that comes with XFree86/OS2 the correct setting is

SET TERMCAP=Y:/XFree86/lib/X11/etc/termcap.x11

Note the usage of "/" as path seperator.

ETC - Normally, this variable already points to the TCP/IP ETC directory. For Warp 4 e.g.

SET ETC=C:\MPTN\ETC

may be set. This setting is OK.

TMP - Set this to a TMP directory for temporary files which should reside on a HPFS formatted drive. (Instead of HPFS you can also use other file systems that support real long names like JFS, ext2fs or NFS.) Often this variable already has been set by other software to something like

SET TMP=C:\IBMCPP\TMP

In most cases, you can leave it this way. However, some packages require that the TMP directory is called TMP and resides in the root of the drive that XFree86/OS2 has been installed to.

HOSTNAME - Set this to your hostname. Normally, this is already set by the TCP/IP installation program, e.g. to

SET HOSTNAME=myhost

With the IAK or TCP/IP without a networking card, you should activate the loopback interface (refer to Network configuration) and set this to the following:

SET HOSTNAME=localhost

USER, LOGNAME - Set both to a user name or your network login-ID. Some programs like e-mail or IRC clients require the setting.

HOME - This entry determines the home directory for your user ID in which programs place their user specific data on Unix. If your user ID is e.g. myuserid a good choice would be

SET HOME=Y:\home\myuserid

CAUTION: The directory myuserid must exist!

X11ROOT - This is one of the most important settings. It determines the root of the XFree86 directory tree. Normally, it is set to the drive letter of the partition where the \XFree86 tree begins. In this case where we assume Y:\XFree86 the correct setting is

SET X11ROOT=Y:

If you want to try to place the XFree86 tree into a subdirectory, e.g. Y:\OS2\X11\XFree86, the setting would have to be changed to say

SET X11ROOT=Y:/OS2/X11

This is strongly discouraged since some programs may not accept this.

Note the use of "/" as path separator.

DISPLAY - This variable chooses the display to be used for displaying X clients. Normally, it is set to the same value as HOSTNAME with a :0.0 (zeroes!) appended, as in

SET DISPLAY=myhost:0.0

Read the X11 man pages for the exact meaning and more options.

XSERVER - This variable must point to the program name of the X server to be used, with the setting being a complete path. If you are using the SVGA server the correct entry would be:

SET XSERVER=Y:/XFree86/bin/XF86_SVGA.EXE

PATH - Add the directory the X11 programs reside in to your path. This is normally the \XFree86\bin directory, in this case Y:\XFree86\bin. If you didn't have emx installed on your machine, you also have to add Y:\emx\bin.

LIBPATH - The XFree86/OS2 DLL directory is \XFree86\lib and should not be changed, since it contains several subdirectories that are referred to by using %X11ROOT%\XFree86\lib as a base. In our example this would be Y:\XFree86\lib. If you didn't have emx installed, you will need to add Y:\emx\dll, too.

MANPATH - If you want to use xman or man to view the man pages, this variable has to point to the directories with man pages. Subdirectories will be taken into account automatically. Like with the PATH variable more than one entry is possible. For instance:

SET MANPATH=Y:\XFree86\man;Y:\man;Y:\emx\man

CAUTION: xman or man alone might not be sufficient to view the different Unix man pages. You should also install GNU groff (refer to Setting up a Unix-like environment).

OS2_SHELL, COMSPEC, SHELL, X11SHELL - Some XFree86 scripts rely on a shell that is compatible to the standard OS/2 commandprocessor. CMD.EXE has some essential properties that allows it to work correctly in an xterm. Third party shells may directly access keyboard and video services and not accept input/output via stdin/stdout. The above variables allow reconfiguration of your system in order to run any favorite shell outside XFree86 and still have XFree86 use CMD.EXE by setting X11SHELL=CMD.EXE.

On the other hand it is often desireable to use Unix shell scripts under XFree86/OS2. This is often mandatory for e.g. compiling software. However, CMD.EXE is not capable of executing these scripts. For these tasks the port of the Public Domain Korn Shell or pdksh is strongly recommened, as it is also capable of recognizing REXX scripts and handing them on to CMD.EXE.

A suitable setting would be

SET X11SHELL=Y:/bin/ksh.exe

For more information about this topic please refer to the Setting up a Unix-like environment guide at this site.

CAUTION! Alternative shells might require different Paramters than CMD.EXE. To use the Korn shell, the file \XFree86\bin\startx.cmd has to be adapted. Change the line

xinit os_shell' /c 'clientargs' -- 'serverargs

to read

xinit os_shell' -c 'clientargs' -- 'serverargs

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. Also, the X server itself will do some checking and will refuse to start if something is wrong.

5. 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). You may want to check OS/2 internet publications like OS/2 eZine, the VOICE Newsletter, Walter Metcalf's archive of Focus on OS/2 articles.

In any case, you should configure and activate the so-called loopback interface that can be used for contacing the same machine via network internally. Dependent on the version of OS/2 this can be done differently. Otherwise you will have to establish a network/internet connection and have to fight problems with dynamic IPs.

Create a hosts file in the directory the ETC variable points to. Add the line

127.0.0.1 localhost

to the file. This line must end with RETURN/ENTER.

If you don't have a correctly installed networking card, add

SET HOSTNAME=localhost

to CONFIG.SYS. Take care of the connection to the DISPLAY variable.

Add the following line to your CONFIG.SYS:

SET USE_HOSTS_FIRST=1

That way the file hosts is searched first upon resolving domain names instead of immediately connecting to a domain name server.

Activate the interface. If you use Warp 3 and the IAK, add the following line to the file \tcpip\bin\tcpstart.cmd:

ifconfig lo 127.0.0.1 up

On Warp 3 Connect and Warp 4 machines the file is called \MPTN\BIN\MPTSTART.CMD. If such a file does not exist, create one and add the line

CALL=C:\OS2\CMD.EXE /Q /C C:\tcpip\bin\tcp-start.cmd >NUL:

(or MPTSTART.CMD, respectively) to your CONFIG.SYS.

Using Warp 4 you can also activate the interface by opening the TCP/IP-Configuration (LAN) object, selecting the notebook page Network, selecting loopback interface for configuration and ticking the configuration option Activate interface. The entry field IP Address must contain the 127.0.0.1 address.

After a reboot you can check the new configuration. Open an OS/2 commandline and enter the following command:

ping localhost

If all is correct the values for "time" should be 0 seconds each. Terminate the program after some time by pressing CTRL-C. A packet loss of 0% should be displayed.

6. Configuring X for your hardware
Now XFree86/OS2 has to be adapted for your hardware, i.e. the video card, the monitor and the keyboard. For this the output of Superprobe (video chip, amount of video memory, RAMDAC), the horizontal and vertical refreshrates of your monitor (from your monitor's manual) and data about your keyboard (number of keys, country version) are required.

The configuration is done with the help of the xf86config program that is started via the OS/2 commandline. This tool generates the configuration file Y:\XFree86\lib\X11\XF86Config.

In the following I am demonstrating the configuration via xf86config of my own hardware. Any input has to be confirmed by pressing ENTER.

The first page provides some general information and can be confirmed with ENTER. The program can always be terminated by pressing CTRL-C.

Now xf86config asks if you want to use the new method for managing keyboard layouts with XKB. As there is no reason not to do so, "y" is a good answer.

Then comes the announcement that next you can choose a variety of pre-defined layouts from a menu. If none suites your needs the program will try to create a new one after asking additional questions. Since the result has not been tested you may have to apply some changes yourself. Press ENTER.

Since I have a Siemens keyboard with German layout and 105 keys, none of the 11 offered choices is the correct one and I select "12 - None of the above". One ought to substract the three Windows keys from the number of 105, so mine becomes a keyboard with 102 keys.

"2 - Standard 102-key keyboard" is the way to go.

A country list is announced next. Press ENTER.

Number 9, "9 - Germany" is correct. In case your country isn't listed first you can scroll through the whole list by pressing ENTER.

Now things are getting technical. The choice of the monitor features is announced. Note that wrong values can result in damaging your monitor. The file \XFree86\lib\X11\doc\Monitors contains some definitions that are known to be working. WARNING: Sometimes there are major differences between monitors of the same model. Confirm with ENTER.

Now a list with possible ranges for horizontal refresh rates is displayed. If you are in doubt about your monitor's capabilities it is safer to select lower rates. My SONY Multiscan 15sf has a range of 31.5 - 64 kHz. Since I'm the cautious type I don't select "8 - 31.5 - 64.3; Monitor that can do 1280x1024 @ 60Hz", but "11 - Enter your own horizontal sync rate" and I enter the according values. CAUTION: Always use dots here, no comma!

After that xf86config asks about the range for vertical refresh rates. That of my monitor is 50-100Hz, so I can select "3 50-100".

Then I enter "SONY Multiscan 15sf" as Identifier, "SONY" as Vendor name and "Multiscan 15sf" as Model name.

The tool contains a large database of video cards. However, there can be differences within a model's series, so sometimes the values presented have to be used with care. You should only select a model that completely matches your card's name. Answer "y" to the question if you want to use the database.

Now you can step through the database by pressing ENTER. I select "416 Matrox Millennium G400 16MB".

The program displays the card definition including the chipset and also the preferred X server, XF86_SVGA in this case. (The SVGA server includes full hardware acceleration for Matrox cards.) Note the important recommendation: "Do NOT probe clocks or use any Clocks line." Confirm by pressing ENTER.

Next several X servers are offered to choose from. XF86_Mono (monochrome) and XF86_VG16 (VGA) should work with pretty much any card, XF86_SVGA (Super VGA, acceleration for some chips) with all SVGA cards. The fourth choice lists accelerated servers. I choose the fifth option that always resembles the server that is recommened in the card definition.

When it's time to enter the amount of video memory I select "6 Other", because the G400 has 16MB of memory. The number to enter is "16384", as the program asks for a value in kilobytes.

In the following you can enter identifiers for the vendor and model of your video card as you did for your monitor.

Then you can choose a clockchip. Remember the warning from the card definition? I choose none by pressing ENTER.

The program now offers to run X -probeonly to retrieve information about the clock chip. Because of unexact measurements and programmable clock chips this is neither necessary nor desirable for today's video cards. Since the card definition also said not to do it, enter "n".

On the next page the possible and desired display resolutions for the different color depths can be configured. The resolution displayed first is valid upon start of the X server.

My SONY 15sf has a 15" screen, so 640x840 is not a good choice. In addition many programs need a lot of room on the display. So 800x600 is not the way to go either, and a sequence of e.g. 1024x768, 800x600, 640x480 sounds good. This is suitable for normal work at 16-bit color depth or higher. For some games, however, a resolution of 640x480 at 8-bit color depth is the optimum. After selecting the color depth you can choose the resolutions by entering certain values, e.g. "432" for 1024x768, 800x600, 640x480. Later you can step through these resolutions while the X server is running by pressing CTRL-ALT-+. After you have entered the combination the virtual screen can be configured. Once it is activated, you'll have a screen that is larger than that of your monitor. The visible area can be scrolled with the mouse.

At last there is a security check and you have to decide whether you want the configuration file written or not. Select "y". If you select "n", you can specify an alternative path for the configuration file so the current won't be overwritten.

If you have a Matrox video card it might occur that the X server only can be started in 320x200 mode. If this happens, open the new XF86Config file, go to the section "Server-Flags" and add a line PCIProbe2. That should do the trick. 7. Starting the X server

Now you can start XFree86/OS2 from a commandline via:

startx

If you prefer another color depth than the default of 8-bit, enter the following for e.g. 16-bit:

startx -- -bpp 16

I recommened to create a program object for XFree86/OS2 on your desktop. Enter the following for Path and filename:

Y:\XFree86\bin\startx.cmd

And for Parameters:

-- -bpp  2>Y:\xerror.log

with being the bit value forthe preferred color depth. The parameter 2>Y:\xerror.log redirects the error output of the X server to the file Y:\xerror.log, so you can get some hints on problems, just in case.

8. Changing the Window Manager
By default XFree86/OS2 uses twm or IceWM as Window Manager. Since especially twm offers only very basic features, you'll probably soon consider using another Window Manager. To activate your new alternative, open the file XINITRC.CMD that normally resides in Y:\XFree86\lib\X11\xinit in an editor and replace the line 'twm' or 'icewm' by 'your_window_manager_executable', e.g. 'enlightenment'. The single quotes are not optional!

Installation version 4.4 and later
XFree86/OS2 4.x is available for download from Netlabs. The binary distribution consists of a number of ZIP files which are containing programs, servers, fonts, libraries, include files, man documentation pages and configuration files. The complete distribution requires 57MB space on your harddisk.

1. Choosing the software
The XFree86/OS2 distribution only includes the "core" and no applications and consists of the following packages with their approximate size in brackets. The real filenames of packages from the XFree86/OS2 distribution consist of a version id like X450 for version 4.5.0, the package names as used in the following, and the ".zip" file extension. Content and naming of packages can slightly vary between versions.

Required packages

 * bin (4MB) - all executables, both X client and supplementary tools
 * lib (7MB) - shared libraries and headers
 * X11 (2MB) - READMEs, locale and xkb support and other stuff
 * fnts (10MB) - miscellaneous, Type-1, TTF, Cyrillic fonts
 * f75dpi (10MB) - 75dpi fonts
 * sup (20KB) - special support driver and shared memory library
 * emxrt - EMX runtime library (only if you don't have EMX installed on your system, download this from Hobbes)

In contrary to XFree86/OS2 3.3.x, there are no extra X server packages.

Optional packages:

 * f100dpi (11.5MB) - 100dpi fonts
 * doc (10MB) - documentation in man and HTML formats
 * prog (2MB) - application developer kit
 * extras (4MB) - Xnest, Xvfb, DMX
 * ncurses-5.3-os2 (1.34MB) - ncurses library, required for using the graphical configuration program xf86cfg in textmode (download from Hobbes)

Bug fixes:
If bugs are found and fixed after the release of a new version of XFree86/OS2, the fixes will be published in a subdirectory of the respective version. In general, you are strongly encouraged to install those packages, too. Be sure to read the included documentation!

In order to save space on your disk and reduce net bandwidth, choose the software to obtain carefully.

2. Pre-checking the compatibility of the video hardware
Of course it would be best, if you found out whether your particular video adapter is supported by XFree86/OS2 or not prior to downloading all the software. Information on supported chip sets is available at the Driver Status for XFree86 page. This information is also available in several files in the \usr\X11R6\lib\X11\doc\html directory of the distribution, which can be found in the X11 archive.

In all cases, please take some time to carefully check the accompanying README.* file in the Y:\usr\X11R6\lib\X11\doc directory for special precautions, options, or features of the card.

3. Unpacking the archives
In the following we assume that you install XFree86/OS2 on drive Y: in the directory Y:\usr\X11R6. Please adapt the commands and file entries according to your real choice. Naming the directory \usr\X11R6 and placing it in the root of the drive is now mandatory! If you don't follow this standard, XFree86/OS2 will not work! We also assume that the XFree86/OS2 distribution's archives reside in a directory X:\temp.

CAUTION: The drive you install XFree86/OS2 to must support long filenames! If you want to use TVFS, do not install XFree86/OS2 4.x onto such a drive, but to the real drive instead, and use TVFS later when all configuration tasks have been finished.

Ensure that drive Y: supports long filenames and has sufficient free space (roughly 90 MB for the complete distribution).

Open an OS/2 command line, switch to the root of drive Y:, and unpack all archives which are located in X:\xtemp by issueing the command:

unzip X:\xtemp\*.zip

During the unpacking process UNZIP may report that some files already exist. Usually you can let UNZIP replace the files without worrying. By entering A (in uppercase!) all subsequent files will be overwritten if they already exist without asking again.

CAUTION: If fixes are available for the current version, the order of unpacking the archives does matter. Ensure that the fix packages are extracted after the those of the actual distribution.

4. Changing CONFIG.SYS
XFree86/OS2 requires a number of settings in CONFIG.SYS to work correctly. Please add the following changes to your CONFIG.SYS and in particular take care of the writing of paths with slash "/" and backslash "\". You can transfer the settings with cut & paste and then adapt them to your system.

XF86SUP.SYS - This driver is mandatory for XFree86/OS2 to work at all. It provides a number of system-related functions and is even quite useful if you don't run XFree86/OS2 because of its extended process-killing abilities. To make OS/2 load it at boot time add the following statement:

DEVICE=Y:\usr\X11R6\lib\xf86sup.sys

The XF86SUP.SYS driver offers an interesting option: /Hx specifies the number of bytes (x) to allocate for the history buffer for so-called PTYs. Possible values are 80 to 32768, the default is 80. This buffer is accessed when you use the  and  keys to step through the command history in an xterm. If you want to be able to access more previously issued commands, try increasing this value. A good start would be /H2048.

TERM - Set the preferred terminal type for the xterm or editor to be used. Some programs require this setting. For use with XFree86/OS2 try

SET TERM=xterm

or

SET TERM=xterm-color

to add some nice colors. \usr\X11R6\lib\X11\etc\xterm.termcap contains a suitable termcap file for the above definitions, which can be used in place of termcap files which come with EMX, EMACS, or other ported software.

CAUTION: Using this file outside of XFree86/OS2, e.g. with normal ported Unix applications will most likely result in an unreadable display. Use e.g. the termcap file which is provided with EMX instead and the following setting:

SET TERM=ansi

On the other hand, with the termcap file from EMX you won't be able to use all keys in an xterm. You can switch between those files and settings by changing them from the command line, running a script before starting XFree86/OS2, or modifying XFree86/OS2's startup files.

TERMCAP - This variable must contain the path to the termcap file which is used for the above TERM setting. If you want to use xterm.termcap which comes with XFree86/OS2, the correct setting is

SET TERMCAP=Y:/usr/X11R6/lib/X11/etc/xterm.termcap

Note the usage of "/" as path seperator.

TERMINFO - Only required if you want to use the graphical configuration program in textmode which requires the ncurses library. This variable points to the directory tree with terminal descriptions for said library. If you extracted the packages as described above, the correct setting is

SET TERMINFO=Y:/share/terminfo

ETC - Normally, this variable already points to the TCP/IP ETC directory. For Warp 4 e.g.

SET ETC=C:\MPTN\ETC

may be set. This setting is OK.

TMP - Set this to a TMP directory for temporary files which should reside on a HPFS formatted drive. (Instead of HPFS you can also use other file systems which support real long names like JFS, ext2fs or NFS.) Often this variable has already been set by other software to something like

SET TMP=C:\IBMCPP\TMP

In most cases, you can leave it this way. However, some packages require that the TMP directory is called TMP and resides in the root of the drive which XFree86/OS2 has been installed to.

HOSTNAME - Set this to your hostname. Normally, this is already set by the TCP/IP installation program, e.g. to

SET HOSTNAME=myhost

With the IAK or TCP/IP without a networking card, you should activate the loopback interface (refer to Network configuration) and set this to the following:

SET HOSTNAME=localhost

USER, LOGNAME - Set both to a user name or your network login-ID. Some programs like e-mail or IRC clients require this setting.

HOME - This entry determines the home directory for your user ID in which programs place their user specific data on Unix. If your user ID is e.g. myuserid a good choice would be

SET HOME=Y:\home\myuserid

CAUTION: The directory which you speficy here must exist! Otherwise, applications are likely to crash.

X11ROOT - This is one of the most important settings. It determines the root of the XFree86 directory tree. This must be set to the drive letter of the partition where the \usr\X11R6 tree begins. In this case where we assume Y:\usr\X11R6 the correct setting is

SET X11ROOT=Y:

DISPLAY - This variable chooses the display to be used for displaying X clients. Normally, it is set to the same value as HOSTNAME with a :0.0 (zeroes!) appended, like in

SET DISPLAY=myhost:0.0

Read the X11 man pages for the exact meaning and more options.

For local applications (i.e. ones which are running on the same machine) performance can be much improved by using the OS/2 pipe transport mechanism. To do so, use either of the following statements:

SET DISPLAY=local/myhost:0 or

SET DISPLAY=:0

Note that the latter statement can cause problems with some applications which are not able to read the environment variable DISPLAY correctly.

XSERVER - This variable must point to the program name of the X server to be used, with the setting being a complete path. In contrary to versions prior to 4.x, there is now one X server only, so the correct entry is always:

SET XSERVER=Y:/usr/X11R6/bin/XFree86.exe

PATH - Add the directory which the X11 programs reside in to your path. This is normally the \usr\X11R6\bin directory, in this case Y:\usr\X11R6\bin. If you didn't have EMX installed on your machine, you also have to add Y:\emx\bin.

To be able to run applications that have been compiled for the old directory tree standard \XFree, you also have to add Y:\XFree86\bin after Y:\usr\X11R6\bin.

LIBPATH - The XFree86/OS2 DLL directory is \usr\X11R6\lib and should not be changed, since it contains several subdirectories that are referred to by using %X11ROOT%\usr\X11R6\lib as a base. In our example this would be Y:\usr\X11R6\lib. If you didn't have EMX installed, you will need to add Y:\emx\dll, too.

To be able to run applications that have been compiled for the old directory tree standard \XFree, you also have to add Y:\XFree86\lib after Y:\usr\X11R6\lib.

MANPATH - If you want to use xman or man to view the man pages, this variable has to point to the directories with man pages. Subdirectories will be taken into account automatically. Like with the PATH variable more than one entry is possible. For instance:

SET MANPATH=Y:\usr\X11R6\man;Y:\man;Y:\emx\man

To be able to run applications that have been compiled for the old directory tree standard \XFree, you also have to add Y:\XFree86\man after Y:\usr\X11R6\man.

CAUTION: xman or man alone might not be sufficient to view the different Unix man pages. You should also install GNU groff (refer to Setting up a Unix-like environment).

OS2_SHELL, COMSPEC, SHELL, X11SHELL - Some XFree86 scripts rely on a shell which is compatible to the standard OS/2 command processor. CMD.EXE has some essential properties which allow it to work correctly in an xterm. Third party shells may directly access keyboard and video services and not accept input/output via stdin/stdout. The above variables allow reconfiguration of your system in order to run any favorite shell outside XFree86 and still have XFree86 use CMD.EXE by setting X11SHELL=CMD.EXE. On the other hand it is often desireable to use Unix shell scripts under XFree86/OS2. This is often mandatory for e.g. compiling software. However, CMD.EXE is not capable of executing these scripts. For these tasks the port of the Public Domain Korn Shell or pdksh is strongly recommened, as it is also capable of recognizing REXX scripts and handing them on to CMD.EXE. A suitable setting would be

SET X11SHELL=Y:/bin/ksh.exe

For more information about this topic please refer to the Setting up a Unix-like environment guide at this site.

CAUTION! Alternative shells might require different Paramters than CMD.EXE. To use the Korn shell, the file \usr\X11R6\bin\startx.cmd has to be adapted. Change the line

xinit os_shell' /c 'clientargs' -- 'serverargs

to read

xinit os_shell' -c 'clientargs' -- 'serverargs

EMXOPT - This setting defines how EMX behaves in a number of situations. XFree86/OS2 and many applications which you may want to use (e.g. GIMP) require a large number of files to be opened during operation. By default, EMX only allows a smaller number of open files and may run out of file handles, if you try to run XFree86/OS2. To increase this number speficy it using the "-h" parameter. A suitable number would be 256 and above, as in:

SET EMXOPT=-h256

If an application crashes or refuses to run without reason, try increasing this number.

Be sure to double-check that everything has been entered correctly. The X server itself will do some checking and will refuse to start, if something is wrong, or print error messages to the file \usr\adm\XFree86.0.log.

5. Network configuration
It is beyond the scope of this document to even give an introduction to 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 which is working well in a TCP/IP based LAN network will also work with XFree86/OS2 (when all other prerequisites are matched as well). You may want to check OS/2 internet publications like OS/2 eZine, the VOICE Newsletter, or Walter Metcalf's archive of Focus on OS/2 articles.

In any case, you should configure and activate the so-called loopback interface, which can be used for contacing the same machine via network internally. Dependent on the version of OS/2 this can be done differently. Otherwise you will have to establish a network/internet connection and have to fight problems with dynamic IPs.

Create a hosts file in the directory which the ETC variable points to. Add the line

127.0.0.1 localhost

to the file. This line must end with RETURN/.

If you don't have a correctly installed networking card, add

SET HOSTNAME=localhost

to CONFIG.SYS. Take care of the connection to the DISPLAY variable.

Add the following line to your CONFIG.SYS:

SET USE_HOSTS_FIRST=1

That way the file hosts is searched first upon resolving domain names instead of immediately connecting to a domain name server.

Activate the interface. Depending on which version of OS/2 you use, this has to be done differently:

If you use Warp 3 and the IAK, add the following line to the file \tcpip\bin\tcpstart.cmd:

ifconfig lo 127.0.0.1 up

On Warp 3 Connect and Warp 4 machines the file is called \MPTN\BIN\MPTSTART.CMD. If such a file does not exist, create one and add the line

CALL=C:\OS2\CMD.EXE /Q /C C:\tcpip\bin\tcp-start.cmd >NUL:

(or MPTSTART.CMD, respectively) to your CONFIG.SYS.

Using Warp 4 or later you can also activate the interface more conveniently by opening the TCP/IP Configuration (LAN) object, selecting the notebook page Network, selecting loopback interface for configuration and ticking the configuration option Activate interface. The entry field IP Address must contain the 127.0.0.1 address.

Reboot. Now check the new configuration. Open an OS/2 command line and enter the following command:

ping localhost

If all is correct, the values for "time" should be 0 seconds each. Terminate the program after some time by pressing . A packet loss of 0% should be displayed.

6. Configuring X for your hardware
Now XFree86/OS2 has to be adapted for your hardware, i.e. the video adapter, the monitor and the keyboard. For this the horizontal synch rates and vertical refresh rates of your monitor and data about your keyboard (number of keys, country version) are required. If your monitor supports DDC, as will be most probably the case with modern monitors, XFree86/OS2 will be able to detect its capabilities automatically. Otherwise you will need to get the values from your monitor's manual.

Configuration can be done in a number of different ways. In the following the most convenient is described.

1. First you need to create an initial configuration file and see if the X server detects your hardware. Open an OS/2 window, switch to the drive where XFree86/OS2 is installed, and issue the following command:

xfree86 -configure

The screen will go black, some text will scroll by and then the desktop should reappear after a short time. If it does not do so, press  to kill the X server. If that still does not work, you will have to reboot the machine by pressing  and ask for help.

2. Take a look at the file Y:\usr\adm\XFree86.0.log. If your CONFIG.SYS and network settings are correct, you will see that the server loaded a large number of modules to detect your hardware. Otherwise it should complain about certain variables not being set and the like. Scroll to the bottom of the file. You should see some messages from the driver for your chip. A typical output for a Matrox G400 card would look like this:

(II) MGA(0): VESA BIOS detected (II) MGA(0): VESA VBE Version 3.0 (II) MGA(0): VESA VBE Total Mem: 16384 kB   (II) MGA(0): VESA VBE OEM: Matrox Graphics Inc.    (II) MGA(0): VESA VBE OEM Software Rev: 2.1 (II) MGA(0): VESA VBE OEM Vendor: Matrox (II) MGA(0): VESA VBE OEM Product: Matrox G400 (II) MGA(0): VESA VBE OEM Product Rev: 00

If your monitor supports DDC, you should also see something like the following:

(II) Loading sub module "ddc" (II) LoadModule: "ddc" (II) Loading j:/usr/X11R6/lib/modules/libddc.a   (II) Module ddc: vendor="The XFree86 Project - XFree86/OS2" compiled for 4.4.0, module version = 1.0.0 ABI class: XFree86 Video Driver, version 0.6 (II) MGA(0): VESA VBE DDC supported (II) MGA(0): VESA VBE DDC Level 2 (II) MGA(0): VESA VBE DDC transfer in appr. 1 sec.   (II) MGA(0): VESA VBE DDC read successfully

If DDC is not reported to be supported, you will need to provide the information about your monitor's capabilities yourself (get them from your monitor's manual).

Last, you should see a message that a new configuration file called XF86Config.new has been written to your HOME directory.

3. If the log file shows no errors and the detected hardware matches your real one, copy the file XF86Config.new from your HOME directory to Y:\usr\X11R6\lib\X11 and rename it to XF86Config.

Now we need to use XFree86's new configuration program. It offers both a GUI and a plain menu-driven textmode interface, each of which have their advantages. While the GUI provides more options and flexibility, the textmode version has less "distractions" and does not require the X server to be running. Note however, that the textmode version requires the ncurses library to be installed correctly. So if you aren't sure that the X server has detected your hardware correctly, you may want to use the textmode version and continue with [#|chapter 6.2].

6.1 Using the graphical interface
4. In the following, the behaviour of GUI elements is different from standard OS/2. To invoke any pop-up menus and select items from them or menu bars, you need to click and hold the mouse button!

It is time to start the X server. Open a command line, switch to the XFree86/OS2 drive, and start the X server by issueing the following command:

startx

The screen should go black with some text displayed for a short time. Then the system should switch to graphics mode and you should see a black "X" cursor on a grey pattern background. Some seconds later, you should notice some hard disk activity and two windows should appear, one with a command line prompt on the top left and a clock on the top right.

WARNING: If this does not happen and you see a distorted display or your monitor starts making strange noises, press  to kill the X server immediately! Otherwise your hardware may get damaged.

Note: Depending on the detected hardware's capabilities, the X server might start at an enormously high, interlaced resolution. While this is not good for your eyes, it shouldn't pose any problems for your hardware.

5. Click on the command line window and start the graphical configuration program:

xf86cfg

Then the outline of the configuration programs window will be displayed for you to determine where to display the full window. Place it anywhere you can view the complete content. The command line window will display a large number of messages about modules being loaded. Unless the program crashes completely, it is safe to ignore any error messages about not loadable modules.



6. XFree86/OS2 always uses the OS/2 mouse driver, so there is no reason to change the mouse settings. Actually, changing them to anything else than OS2Mouse is likely to cause problems.

7. Right-click on the keyboard icon in the layout display and choose the configure item from the pop-up menu. In the keyboard configuration dialog, select your keyboard from the keyboard model drop-down list. Most people, who own a keyboard with Windows keys, may want to select one of the Generic 104-key PC or Generic 105-key (Intl) PC models. Then select your language-specific layout from the keyboard layout drop-down list. Note that this only specificies the keyboard's layout, not any internationalisation support. Confirm the changes and leave the dialog by pressing Ok.



8. If your monitor does not support DDC, right-click on the monitor icon and select configure. This will bring up the monitor configuration dialog. There you need to specify horizontal and vertical refresh rates. You can do this by either clicking on one of the predefined values (clicking on the descriptive entries in the list for horizontal refresh rates will result in the accompanying rate range being displayed in the entry field above), or by manually specifying ranges in the respecitive entry fields.

WARNING: Wrong values can result in damaging your monitor! If you are in doubt about your monitor's capabilities, it is safer to select lower rates.

CAUTION: When specifying decimal values, always use a dot as seperator, no comma!



Example: An old SONY Multiscan 15sf is not capable of DDC and has a horizontal refresh rate range of 31.5 - 64 kHz. The list entry Monitor that can do 1280x1024 @ 60Hz equals a range of 31.5 - 64.3 kHz. Being the cautious type we don't select that entry, but define my our range by entering the according values in the entry field. The SONY's range for vertical refresh rates is 50 - 100 Hz, so it's safe to select the 50 - 100 item.

Confirm the changes and leave the dialog by pressing OK.

9. If the X server didn't detect the hardware correctly, or you want to change the video adapter definition for some reason, right-click on the video adapter symbol and select configure. The configuration dialog will present you with a large scrollable list of chips. If you only want to choose from the models of a certain vendor, type in the chip name in the Card model filter entry field and press . Note that you will have to specify the chip's ID, not the vendor name. Matrox won't work, for instance, but mga does. After you have selected a card model from the list, the dialog automatically selects the appropriate driver from the Driver drop-down list. You can also select the driver directly yourself, of course. Confirm the changes and leave the dialog by pressing OK.



Example: For a Matrox G400 Double Head with 16 MB of video RAM, scroll down to and select mga mgag400. The rest should be detected automatically on startup.

Depending on the video chip in your hardware, the XFree86 drivers often offer a number of special options to enable or configure support for advanced features. Normally, you don't need to change any of these options.

To set these options, right-click on the video adapter symbol and select options. A dialog will show up which allows you to select from the options which are available for the current driver. For details about the available options, see the HTML files in Y:\usr\X11R6\lib\X11\doc\html. These files follow the .4.html naming scheme.

10. Next, we need to specify some screen resolutions and color depths for XFree86/OS2 to run at which don't hurt our eyes. Click on the Configure layout item in the menu bar and select Configure screen. (To get back to the main menu, select Configure screen in the menu bar and select Configure layout.)



Right-click on the monitor symbol and select configure. The default color depth of 8 bit resembles 256 colors, which is too few for most of today's applications. Choose 16 bit for 65536 colors or 24 bit for 16.7 million colors. If required, you can still start the X server at a different color depth via a command line option later. The left pane below shows the scrollable list of available resolutions, while the right pane shows the selected ones. With the arrow buttons in the middle you can add resolutions to or remove resolutions from the right and move them up or down in the right list.



The list of resolutions on the right defines the resolutions which the X server will be able to use at a given color depth. The topmost resolution will be the default resolution which the X server uses upon startup. If later while running XFree86/OS2 you should feel the need to use another of the other resolutions in the list, e.g. to play a game which requires a resolution of 640x480, or to work with some graphical application which consumes a lot of screen real estate, press the key combination  or  (+/- from the numeric key block only) to cycle through the list of defined resolutions.

CAUTION: Note that xf86cfg creates the necessary entries in XF86Config for the default color depth only! If you start the X server at another color depth, don't be surprised, if it used another resolution. To workaround this problem, make a color depth which you want to setup resolutions for the default, setup the resolutions, and close the dialog by pressing Ok. Then re-open the dialog and repeat the same for the next color depth. When you have configured all color depths, open the dialog a last time, mark the default color depth, and close the dialog again by pressing Ok.

Example: For a 19" monitor a good choice would be to use 1280x1024 as default resolution (at the top of the right list). If you like to play a game now and then and the game is not able to use more than 640x480 pixels, add 640x480. Then you can switch to 640x480 by pressing  whilst running at 1280x1024.

Confirm the changes and leave the dialog by pressing OK.

11. To leave the configuration program, select Quit. In the confirmation dialog, you can finally choose whether to save the changes or not and to which file. If everything is OK, select Yes to save the main configuration file XF86Config. Otherwise select No to quit without saving or Cancel to continue with configuration.



If you press Yes, another confirmation for the keyboard settings file with the same choices will appear. Press OK to save settings and quit the program.



12. To enable the changes, you need to terminate and restart XFree86/OS2 now. Close the command line window by entering

exit

Finally, quit the window manager session (and thereby XFree86/OS2) by left-clicking on the desktop background and selecting Exit.

Please continue with [#7. Starting the X server|chapter 7].

6.2 Using the textmode interface
4. While the textmode interfaces offers graphical menus, it does not support the mouse. Navigation is done with the arrow keys, checkboxes are selected by pressing the space bar, and control elements which have the focus (colored blue) are activated by pressing .

Open an OS/2 command line and switch to the drive where XFree86/OS2 is installed. Then start the configuration program by entering:

xf86cfg -textmode

You will see a lot of messages regarding the loading of modules scroll by. Unless any severe error occurs, you should see the following welcome message:



5. XFree86/OS2 always uses the OS/2 mouse driver, so there is no reason to change the mouse settings. Actually, changing them to anything else than OS2MOUSE is likely to cause problems.

6. Select the Configure keyboard menu item by pressing the down-arrow key and press  to confirm your selection. This will invoke the Keyboard configuration menu:

Select Edit Keyboard0 and press  to edit the keyboard definition. The Keyboard model dialog lets you select your type of keyboard. Note that the list of available models is very long. Scroll with the up and down arrow keys to see which menu item suits your keyboard best.



Most people who own a modern standard keyboard with Windows keys will want to select one of the Generic 104-key PC or Generic 105-key (Intl) PC models. Select your preferred item and press <ENTER>.

Then select your language-specific layout from the Keyboard layout list. Note that this only specificies the keyboard's layout, not any internationalisation support.



Confirm your selection and finish keyboard configuration by pressing <ENTER>.

7. If your monitor does not support DDC, select the Configure monitor item and press <ENTER>. This will bring up the Monitor configuration dialog:



To configure your monitor, select Edit Monitor0 and press <ENTER>. This brings up the Monitor HorizSync dialog, where you need to specifiy the range of horizontal sync rates which your monitor is capable of. You can do this by either selecting one of the predefined values (the values of the beginning of each line specify the rate, rates, or range of rates), or by selecting Enter your own horizontal sync range to manually specify the range.



Next we need to specify the vertical refresh rates in the Monitor VertRefresh dialog. You can do this by either selecting one of the predefined ranges, or by selecting Enter your own vertical sync range to manually specify the range.



8. WARNING: In both cases, wrong values can result in damaging your monitor! If you are in doubt about your monitor's capabilities, it is safer to select lower rates. CAUTION: When specifying decimal values, always use a dot for seperation, no comma!

Example: An old SONY Multiscan 15sf is not capable of DDC and has a horizontal refresh rate range of 31.5 - 64 kHz. The list entry Monitor that can do 1280x1024 @ 60Hz equals a range of 31.5 - 64.3 kHz. Being the cautious type we don't select that entry, but define our own range by selecting Enter your own horizontal sync range and entering the according values in the entry field and pressing <ENTER>:



9. The SONY's range for vertical refresh rates is 50 - 100 Hz, so it's safe to select the 50 - 100 item and finish with <ENTER>.

10. If the X server didn't detect the hardware correctly, or you want to change the video adapter definition for some reason, select Configure card and press <ENTER>. This brings up the Card configuration dialog which asks whether you want to select your card from a large database of video card definitions:



11. The database of video card definitions provides a convenient way to choose the appropriate drivers. So unless you have some very new or exotic stuff, select Yes with the arrow keys and press <ENTER>.

The Card database dialog presents you with a large scrollable list of video chip sets. Note that chip IDs are listed only, not the vendor name. Looking for Matrox won't work, for instance, but mga does. You can also jump to the first chip name that begins with a certain character by pressing the according key.



12. Example: For a Matrox G400 Double Head with 16 MB of video RAM, scroll down to and select mga mgag400. The rest should be detected automatically on startup.

When you select a card, the dialog will automatically select a suitable driver in the following Card driver dialog:



If you think that xf86cfg did not select the correct driver, you can still change it by selecting from the scrollable list. The vga driver should always work, but it is very slow and only works at a resolution of 320x200.

Finally, you need to specify the card bus ID. Do not change this field unless you have more than one video card and simply finish by pressing <ENTER>.



13. Next, we need to specify some screen resolutions and color depths for XFree86 to run at which don't hurt our eyes. Select Configure screen to bring up the Screen configuration dialog:



Select Edit Screen0 and press <ENTER> to bring up the Screen depth dialog. There you can specify which color depth you want XFree86/OS2 to use by default. The default color depth of 8 bits resembles 256 colors, which is too few for most of today's applications. Choose 16 bits for 65536 colors or 24 bits for 16.7 million colors. If required, you can still start the X server at a different color depth via a command line option later.



The list of resolutions in the Screen modes dialog defines the resolutions which the X server will be able to use at a given color depth. Select all resolutions you want to use by highlighting them and pressing the space bar. The highest selected resolution will be the default resolution which the X server uses upon startup. If later while running XFree86/OS2 you should feel the need to use another of the other resolutions in the list, e.g. to play a game which requires a resolution of 640x480, or to work with some graphical application which consumes a lot of screen real estate, press the key combination <CTRL-ALT-+> or <CTRL-ALT--> (+/- from the numeric key block only) to cycle through the list of defined resolutions. Finish your selection by pressing <ENTER>.



CAUTION: Note that xf86cfg creates the necessary entries in XF86Config for the default color depth only! If you start the X server at another color depth, don't be surprised, if it used another resolution. To workaround this problem, make a color depth which you want to setup resolutions for the default, setup the resolutions, and finish. Then re-open the dialog and repeat the same for the next color depth. When you have configured all color depths, open the dialog a last time, mark the default color depth, and finish setup again.

Example: For a 19" monitor a good choice would be to use 1280x1024 as default resolution. If you like to play a game now and then and the game is not able to use more than 640x480 pixels, add 640x480. Then you can switch to 640x480 by pressing <CTRL-ALT-+> whilst running at 1280x1024.

14. To leave the configuration program, select Write XF86Config and quit. In the confirmation dialog, you can finally choose whether to save the changes or not and to which file:



If everything is OK, select OK to save the main configuration file XF86Config. Otherwise select Cancel to return to the main menu.

7. Starting the X server
Now you can start XFree86/OS2 from a command line via:

startx

If you prefer another color depth than the default, enter the following for e.g. 16 bit:

startx -- -depth 16

It is recommended to create a program object for XFree86/OS2 on your desktop. Enter the following for Path and filename:

Y:\usr\X11R6\bin\startx.cmd

And for Parameters:

-- -depth <color_depth> 2>Y:\xerror.log

with being replaced with the desired value. The parameter 2>Y:\xerror.log redirects the error output of the X server to the file Y:\xerror.log, so you can get some hints on problems, just in case.

WARNING: Version 4.3 offered the special command line parameter -os2HRTimer that allowed to increase performance for remote applications. This mechanism has been replaced with different routines, and the parameter has been removed. If it is still speficied, the X server will not start!

8. Changing the Window Manager
By default XFree86/OS2 uses twm as Window Manager. Since especially twm offers only very basic features, you'll probably soon consider using another Window Manager. To activate your new alternative, copy the file XINITRC.CMD which normally resides in Y:\usr\X11R6\lib\X11\xinit to your HOME directory, open it in an editor and replace the line 'twm' by 'your_window_manager_executable', e.g. 'enlightenment'. The single quotes are not optional! XFree86/OS2 will find the changed file upon startup and use it instead of the original one in Y:\usr\X11R6\lib\X11\xinit.

Window manager
To use XFree86/OS2 you will need additional programs, the so-called window managers. These programs determine the look of window title bars and frames as well as reaction to certain events like mouse clicks and keyboard presses. The window managers can roughly be compared to the Presentation Manager, but they don't provide the WPS' functionality by far. To reach that level of functionality the use of so-called desktops like KDE or GNOME, which are far more complex, becomes necessary. An interesting fact is that the goal of the GNOME project is to bring the functionality of OS/2's Workplace Shell to Unix systems. Many of the GNOME parts have been ported to OS/2 meanwhile.

The following paragraphs give you an overview on some of the available window managers. Which one you are going to use is a question of personal taste and the computational resources. Most of the window managers but Enlightenment can be aquired from UnixOS2.


 * XFree86/OS2 3.3.x comes with two window managers, twm and IceWM, with IceWM activated as default, while XFree86/OS2 version 4.x only comes with twm. twm is so feature-poor that you probably won't be interested. IceWM can look quite Warp-like, but it doesn't provide the functionality of larger WMs. Any configuration has to be set by editing configuration files by hand. (Be sure to use only suitable editors!)
 * fvwm2 could be called the classic of window managers. It offers features like virtual desktops, a display for minimized windows and buttonbars. There are several flavours of this window manager available, each with a certain look & feel. E.g. there are version resembling the CDE desktop and Windows 95. fvwm also has to be configured by hand editing configuration files. (Be sure to use only suitable editors!)
 * WindowMaker is a step forward in terms of user friendliness. It resembles the look & feel of the NeXT desktop and settings can be configured using a GUI and drag & drop. Additionally, its look can be changed by using so-called themes (colours, background, etc.). Another advantage of WindowMaker is its interface for GNOME and KDE so it can be used as a replacement for their window managers. This can come in very handy, if your system suffers from low available RAM and/or CPU power.
 * In case you have enough RAM (64MB minimum) and enough CPU power (Pentium 200 class minimum) have a look at Enlightenment. Most parts of Enlightenment can be configured easily using a GUI. In terms of customizability, Enlightenment beats anything I have seen so far. Using themes its look & feel can be completely changed. The internet site e.themes.org holds most available themes. You can get Enlightenment itself at the offcial GNOME/2 and Enlightenment/2 Homepage.