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.6 2001/06/07 05:11:41 torrey Exp $ </ident> <toc> <sect>Introduction <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 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 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. 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 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. 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 <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>. 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 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 url="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/binaries/">. 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 X Quartz support, download the optional Xquartz.tgz tarball. 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 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 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 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"> 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. You are now ready to go. On Mac OS 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 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 <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 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. <bf/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 <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>. 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">. Good luck! <sect>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. <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>