                       XFree86 on Darwin and Mac OS X

                               Torrey T. Lyons

                                 25 May 2001

1.  Introduction

XFree86, a free implementation of X Windows, has been ported to Darwin and
Mac OS X. This document is a collection of information for anyone experiment-
ing with running X Windows on Apple's next generation operating system.
Please send any comments on this page to <torrey@mrcla.com>.  If you are also
working on modifications to the Darwin X server, please let me know.

2.  Hardware Support and Configuration

XFree86 can be run either from the console or side by side with Mac OS X's
Aqua desktop in a full screen mode. In full screen mode with Aqua, when the X
window system is active, it takes over the entire screen. You can switch back
to the Mac OS X desktop by holding down Command-Option-A. This key combina-
tion can be changed in the user preferences. From the Mac OS X desktop, just
click on the XDarwin icon in the floating switch window to switch back to the
X window system.  You can change this behavior in the user preferences so
that clicking on the XDarwin icon in the Dock switches as well. The full
screen cooperative mode with Aqua is known as Quartz mode, named after the
Quartz 2D compositing engine used by Aqua.

From the console, the Darwin port of XFree86 uses the IOKit for device driver
loading and discovery, rather than the XFree86 module loader.  Because of
this, the XFree86 configuration file is not used on Darwin or Mac OS X sys-
tems. The descriptions found elsewhere of devices supported by XFree86 for
other operating systems also do not apply.  Running XFree86 from the text
console is known as IOKit mode.

XFree86 for Darwin or Mac OS X will work with any video card that you have an
IOKit driver for. If you are running Mac OS X, this typically means any card
that has been shipped by Apple. If a card works for you with the Mac OS X
GUI, it will work on the same machine with XFree86. If you have a pure Darwin
installation, you may need to download additional third-party drivers from
Apple's Darwin site. IOKit drivers are typically installed in /Sys-
tem/Library/Extensions/ or /Library/Extensions/.

Multi-button and scroll wheel mouse support works well with all USB mice that
I have tested. I have done no testing with serial mice.

3.  Getting Started

Following are instructions for building and running your own copy of XFree86.
The procedure for getting your X server up and running on Darwin and Mac OS X
are very similar. Where there are differences I have noted them below. Note
that to build XFree86 for yourself on Mac OS X, you will need to install the
Developers' Tools.

If you don't feel the need to live on the cutting edge, you can save some
time and effort by using the precompiled binaries available on the XFree86
FTP server at <URL:ftp://ftp.xfree86.org/pub/XFree86/4.1.0/binaries/Darwin/>.
Follow the instructions in the Install document to install it. This will cre-
ate two new directory trees, /usr/X11R6 and /etc/X11 For Mac OS X Quartz sup-
port, download the optional Xquartz.tgz tarball.

If you get the precompiled binaries you can skip ahead to the section on run-
ning the X window system (section 4., page 1) On the other hand, if you want
to build things yourself from scratch, follow the directions below.

3.1  Get the Code

The first thing you need to do is to get the source code from the XFree86
project.

   o  Setup CVS: Both Darwin and Mac OS X include CVS (Concurrent Versions
     System), which is an easy way to download and keep up to date with open
     source code released by XFree86 and others. You do have to setup CVS
     properly, however, to tell it where to look. Follow the XFree86 instruc-
     tions on how to do this either via ssh or via the cvs pserver.

   o  Now make a directory in some convenient place which will serve as your
     top level directory for you open source development efforts. I am going
     to call this directory sandbox/ in the following discussions and you
     could put this directory, for example, in ~/sandbox/.

   o From the command line type:

          cd sandbox
          cvs checkout xc

     Wait for all the files to complete downloading.

3.2  Build XFree86

Once you have everything ready it is easy to build and install XFree86. From
the command line:

     cd sandbox/xc
     make World >& world.log

     (wait for several hours)

     sudo make install >& install.log
     sudo make install.man >& man.log

4.  Run the X Window System

You will want to add the X window executables to your path. Your path is the
list of directories to be searched when you type a command. You will also
want to add the man pages from XFree86 to the list of pages to be searched
when you are looking for documentation. The way to do this depends on the
shell you are using. With tcsh or csh add the following two lines to a file
named ~/Library/init/tcsh/path: (You may need to create this file and direc-
tory path if it does not exist already.)

     setenv PATH "${PATH}:/usr/X11R6/bin"
     setenv MANPATH "${MANPATH}:/usr/X11R6/man"

The next time you login or open a Terminal window, this file will be executed
automatically.

You are now ready to go. On Mac OS X, you can run XFree86 from the text con-
sole or in full screen mode with Aqua. To get to the text console in Mac OS X
you need to logout and type ``>console'' as the user name. This will shutdown
Core Graphics and bring up the console login prompt. Login again as your
user.

From the text console you can start the X Window System by typing ``startx''.
After a brief wait at least one terminal window should pop up for you.  So
far it probably isn't very impressive as you might not even have a window
manager running to allow you to move windows around.

When you are ready to quit XFree86 type ``exit'' in the main terminal window
or quit with the window manager if you have one running. Unfortunately the X
server won't shutdown correctly and you will get an apparently frozen screen
with only a spinning beachball cursor on it. Nothing you type shows up on the
screen, but in fact your keystrokes are being received by the console. Type
``logout'' to return to normalcy after a brief delay. With Darwin this should
put you back at the text console login prompt. With Mac OS X, Core Graphics
will restart and you should be given a login window.

To start XFree86 in Quartz mode you can launch the XDarwin application in the
/Applications folder, or from the command line type ``startx -- -quartz''.
When the X window system is active, it takes over the entire screen. You can
switch back to the Mac OS X desktop by holding down Command-Option-A. This
key combination can be changed in the user preferences. From the Mac OS X
desktop, just click on the XDarwin icon in the floating switch window to
switch back to the X window system. You can change this behavior in the user
preferences so that clicking on the XDarwin icon in the Dock switches as
well.

Customize X Windows

The X window system is very customizable and you will certainly want to
change some things. There is a lot you can do to control how your windows
look, how the windows are moved, resized, etc. You will likely want to get a
better window manager than twm, which is included with XFree86. The .xinitrc
file in your home directory controls what programs are run when you start the
X window system. You can find a sample .xinitrc file in /etc/X11/xinit/xini-
trc.

There are several window managers that have been ported to Darwin.  The best
collection of window managers and other X window clients is at Darwinfo's
ports page. Another good place to look for Darwin ports in general is at
Stepwise's Softrak site.

Good luck!

5.  Outstanding Issues with the X server

There is a still a lot to be done with the X server. As always please let me
know if you are interested in working on any of these issues.

Things that are broken:

   o The bell does not work in IOKit mode.

   o Server shutdown problem: After quitting the X server in IOKit mode, the
     colored beachball cursor reappears, but the screen never returns to the
     console display. The console is accepting input however, so typing
     ``logout'' will return you to the login prompt.

   o Only one display is currently supported.

   o The display mode can not be changed once  the  X  server has started.

   o A screen saver is not supported.

     Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/Darwin.sgml,v 1.4.4.2 2001/06/02 04:44:37 torrey Exp $


$XFree86: xc/programs/Xserver/hw/xfree86/doc/README.Darwin,v 1.3.4.4 2001/06/02 16:02:08 dawes Exp $
