<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN" [
<!ENTITY % defs SYSTEM "defs.ent"> %defs;
]>

<article>
<title>XFree86 on Darwin and Mac OS X
<author>Torrey T. Lyons
<date>25 May 2001

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

<toc>

<sect>Introduction
<p>
<htmlurl url="http://www.xfree86.org/" name="XFree86">, a free
implementation of X Windows, has been ported to <htmlurl
url="http://www.publicsource.apple.com/projects/darwin/" name="Darwin">
and <htmlurl url="http://www.apple.com/macosx/" name="Mac OS X">. This
document is a collection of information for anyone
experimenting with running X Windows on Apple's next generation operating
system. Please send any comments on this page to
<email/torrey@mrcla.com/.  If you are also 
working on modifications to the Darwin X server, please let me know.

<sect>Hardware Support and Configuration
<p>
XFree86 can be run either from the console or side by side with
Mac OS&nbsp;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&nbsp;X desktop by holding down
Command-Option-A. This key combination can be changed in the user
preferences. From the Mac OS&nbsp;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.

<p>
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&nbsp;X systems. 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.

<p>
XFree86 for Darwin or Mac OS&nbsp;X will work with any video card that
you have an IOKit driver for. If you are running Mac OS&nbsp;X, this
typically means any card that has been shipped by Apple. If a card works
for you with the Mac OS&nbsp;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
<htmlurl url="http://www.publicsource.apple.com/projects/darwin/"
name="Apple's Darwin site">. IOKit drivers are typically installed in
<tt>/System/Library/Extensions/</tt> or <tt>/Library/Extensions/</tt>.

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

<sect>Getting Started
<p>
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&nbsp;X are very similar. Where there are differences
I have noted them below. Note that to build XFree86 for yourself on
Mac OS&nbsp;X, you will need to install the Developers' Tools.

<p>
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
url="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/binaries/Darwin/">.
Follow the instructions in the <htmlurl
url="http://www.xfree86.org/&relvers;/Install.html" name="Install">
document to install it. This will create two new directory trees,
<tt>/usr/X11R6</tt> and <tt>/etc/X11</tt> For Mac OS&nbsp;X Quartz
support, download the optional Xquartz.tgz tarball.

<p>
If you get the precompiled binaries you can skip ahead to the section
on <ref id="running" name="running the X window system"> On the other hand,
if you want to build things yourself from scratch,
follow the directions below.

<sect1> Get the Code 

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

<itemize>
<item> Setup CVS: Both Darwin and Mac OS&nbsp;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
<htmlurl url="http://www.xfree86.org/cvs/" name="XFree86 instructions"> on
how to do this either via ssh or via the cvs pserver.

<item> 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 <tt>sandbox/</tt> in the following discussions
and you could put this directory, for example, in <tt>~/sandbox/</tt>.

<item>From the command line type:
<tscreen><verb>
cd sandbox
cvs checkout xc
</verb></tscreen>
Wait for all the files to complete downloading. 

</itemize>

<sect1> Build XFree86
<p>
Once you have everything ready it is easy to build and install
XFree86. From the command line: 

<tscreen><verb>
cd sandbox/xc
make World >& world.log

(wait for several hours)

sudo make install >& install.log
sudo make install.man >& man.log
</verb></tscreen>

<sect>Run the X Window System<label id="running">
<p>
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
<tt>~/Library/init/tcsh/path</tt>: (You may need to create this file and
directory path if it does not exist already.)

<tscreen><verb>
setenv PATH "${PATH}:/usr/X11R6/bin"
setenv MANPATH "${MANPATH}:/usr/X11R6/man" 
</verb></tscreen>
The next time you login or open a Terminal window, this file will be
executed automatically.

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

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

<p>
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&nbsp;X, Core Graphics will restart and you should be given a login
window.

<p>
To start XFree86 in Quartz mode you can launch the XDarwin application
in the <tt>/Applications</tt> 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&nbsp;X desktop by
holding down Command-Option-A. This key combination can be changed in
the user preferences. From the Mac OS&nbsp;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.

<p>
<bf/Customize X Windows/
<p>

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 <tt>.xinitrc</tt> file in your home directory controls what
programs are run when you start the X window system. You can find a sample
<tt>.xinitrc</tt> file in <tt>/etc/X11/xinit/xinitrc</tt>.  

<p>
There are several window managers that have been ported to Darwin.
The best collection of window managers and other X window clients
is at <htmlurl
url="http://www.darwinfo.org/ports.shtml#X Windows" name="Darwinfo's ports
page">. Another good place to look for Darwin ports in general is at
<htmlurl
url="http://softrak.stepwise.com/Apps/WebObjects/Softrak" name="Stepwise's
Softrak site">.  

<p>
Good luck!

<sect>Outstanding Issues with the X server

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

<bf/Things that are broken:/
<itemize>
<item>The bell does not work in IOKit mode. 

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

<item>Only one display is currently supported.

<item>The display mode can not be changed once  the  X  server
has started.

<item>A screen saver is not supported.

</itemize>

</article>

