X.Org X on Darwin and Mac OS X
           _______________________________________________

   Table of Contents
   Introduction
   Hardware Support and Configuration
   Getting Started
   Run the X Window System

Introduction

   Xorg, a freely redistributable open-source implementation of
   the X Window System, has been ported to Darwin and 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 XonX project at 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 XonX
   project.
     __________________________________________________________

Hardware Support and Configuration

   The X window server for Darwin and Mac OS X provided by the
   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 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 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 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:

     * DarwinPorts: An easy way to install various open-source
       software products on Darwin and Mac OS X.
     * Fink: A package manager that will easily download, compile,
       and install lots of open source software from the Internet.
     * GNU-Darwin: A source for tons of software ported to Darwin.

   Good luck!
