                         X.Org X on Darwin and Mac OS X

            -------------------------------------------------------

   Table of Contents

   [1]Introduction

   [2]Hardware Support and Configuration

   [3]Getting Started

   [4]Run the X Window System

Introduction

   [5]Xorg, a freely redistributable open-source implementation of the [6]X
   Window System, has been ported to [7]Darwin and [8]Mac OS X. This document
   is a collection of information for anyone running Xorg's X server on
   Apple's next generation operating system.

   Most of the current work on X for Darwin and Mac OS*X is centered around
   the [9]XonX project at [10]SourceForge. If you are interested in
   up-to-date status, want to report a bug, or are interested in working on
   Xorg for Darwin, stop by the [11]XonX project.

   --------------------------------------------------------------------------

Hardware Support and Configuration

   The X window server for Darwin and Mac OS*X provided by the [12]X.Org
   Foundation. is called XDarwin. XDarwin can run in three different modes.
   On Mac OS*X, XDarwin runs in parallel with Aqua in full screen or rootless
   modes. These modes are called Quartz modes, named after the Quartz 2D
   compositing engine used by Aqua. XDarwin can also be run from the Darwin
   console in IOKit mode.

   In full screen Quartz mode, 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, click on the XDarwin icon in
   the Dock to switch back to the X window system. (You can change this
   behavior in the user preferences so that you must click the XDarwin icon
   in the floating switch window instead.)

   In rootless mode, the X window system and Aqua share your display. The
   root window of the X11 display is the size of the screen and contains all
   the other windows. The X11 root window is not displayed in rootless mode
   as Aqua handles the desktop background.

   From the console, the Darwin port of X11R7.2 uses the IOKit for device
   driver loading and discovery, rather than the X11R7.2 module loader.
   Because of this, the X11R7.2 configuration file is not used on Darwin or
   Mac OS*X systems. The descriptions found elsewhere of devices supported by
   X11R7.2 for other operating systems also do not apply.

   X11R7.2 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 X11R7.2. If you have a
   pure Darwin installation, you may need to download additional third-party
   drivers from [13]Apple's Darwin site. IOKit drivers are typically
   installed in /System/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 ADB mice, but without a
   special driver, only a single mouse button will work on an ADB mouse.

   --------------------------------------------------------------------------

Getting Started

   Following are instructions for building and running your own copy of
   X11R7.2. 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 X11R7.2 for yourself on Mac OS*X, you need
   to install the Developers' Tools.

   /Applications.

   If you get the precompiled binaries you can skip ahead to the section on
   [14]running the X window System On the other hand, if you want to build
   things yourself from scratch, follow the directions below.

   --------------------------------------------------------------------------

  Get the Code

   The first thing you need to do is to get the source code from the X.Org
   Foundation project.



     * 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 the X.Org Foundation and others. You do
       have to setup CVS properly, however, to tell it where to look. Follow
       the [15]X.Org CVS instructions on how to do this either via ssh or via
       the cvs pserver.

     * 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/.

     * From the command line type:

       cd sandbox
       cvs checkout xc

       Wait for all the files to complete downloading.



   --------------------------------------------------------------------------

  Build X11R7.2

   Once you have everything ready it is easy to build and install X11R7.2.
   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



   --------------------------------------------------------------------------

Run the X Window System

  Setting Your Path

   You need to add the X Window System executables to your path. Your path is
   the list of directories to be searched for executable commands. The X11
   commands are located in /usr/X11R6/bin, which needs to be added to your
   path. In Quartz mode, the XDarwin application does this for you
   automatically. It can also be configured to add additional directories
   where you have installed command line applications. When running from the
   Darwin console, you will need to set the path correctly for your shell as
   XDarwin will not do this for you.

   More experienced users will have already set their path correctly using
   the initialization files for their shell. In this case, you can inform
   XDarwin not to modify your path in the preferences. XDarwin launches the
   initial X11 clients in the user's default login shell. (An alternate shell
   can also be specified in the preferences.) The way to set the path depends
   on the shell you are using. This is described in the man page
   documentation for the shell.

   In addition you may also want to add the man pages from X11R7.2 to the
   list of pages to be searched when you are looking for documentation. The
   X11 man pages are located in /usr/X11R6/man and the MANPATH environment
   variable contains the list of directories to search.

   --------------------------------------------------------------------------

  Starting the X Server

   On Mac OS*X, you can run X11R7.2 from the Darwin text console or in
   parallel 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 ``exec
   startx''.

   When you are ready to quit X11R7.2 type ``exit'' in the main terminal
   window or quit with the window manager if you have one running.
   Unfortunately in IOKit mode, the X server does not shutdown correctly and
   if you did not start with ``exec startx'', 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 X11R7.2 in Quartz mode you can launch the XDarwin application in
   the /Applications folder, or from the command line type ``startx --
   -quartz''. By default this will give you a mode picker to choose between
   full screen or rootless mode. You can change the default to always use a
   particular mode in the preferences, or you can specify the ``-fullscreen''
   or ``-rootless'' options on the command line instead of ``-quartz''.

   --------------------------------------------------------------------------

  Double-clickable X11 Executables

   Mac OS*X 10.3 can be configured to automatically launch XDarwin when you
   double-click an X11 executable in the Finder. When an executable file is
   double-clicked Launch Services checks to see if it is linked against the
   X11 libraries. If it is, Launch Services opens the default X server. To
   set the default X server, do the following:



     * Create a simple file which ends in ''.x11app''.

     * Open the file with Get Info in the Finder.

     * Under ''Open with:'' select the XDarwin application.

     * Select ''Change All...'' to set XDarwin as the default.



   On Mac OS*X 10.3 the default X server is started when an X11 executable is
   double-clicked, whether or not its extension is ''.x11app''. On previous
   versions of Mac OS*X, an X11 executable must have a ''.x11app'' extension
   for this to work.

   --------------------------------------------------------------------------

  Customize the X Window System

   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 fancier window manager than twm, which is included with X11R7.2. 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/xinitrc.

   There are many window managers that have been ported to Darwin. The
   following pages contain collections of window managers and other X window
   system clients:



     * [16]DarwinPorts: An easy way to install various open-source software
       products on Darwin and Mac OS*X.

     * [17]Fink: A package manager that will easily download, compile, and
       install lots of open source software from the Internet.

     * [18]GNU-Darwin: A source for tons of software ported to Darwin.



   Good luck!

References

   Visible links
   1. file:///tmp/html-O11237#AEN8
   2. file:///tmp/html-O11237#AEN19
   3. file:///tmp/html-O11237#AEN31
   4. file:///tmp/html-O11237#RUNNING
   5. http://www.freedesktop.org/Software/xorg
   6. http://www.x.org/
   7. http://www.opensource.apple.com/projects/darwin/
   8. http://www.apple.com/macosx/
   9. http://sourceforge.net/projects/xonx/
  10. http://sourceforge.net/
  11. http://sourceforge.net/projects/xonx/
  12. http://www.x.org/
  13. http://developer.apple.com/darwin/
  14. file:///tmp/html-O11237#RUNNING
  15. http://x.org/
  16. http://darwinports.opendarwin.org/
  17. http://fink.sourceforge.net/
  18. http://gnu-darwin.sourceforge.net/
