@html_text_substitution=readme.txt|<a href="../readme.html">readme.txt</a>
@external-css=../allegro.css
@document_title=Allegro MacOS X-specific information
@<pre>
     ______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___ 
     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
	\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
				       /\____/
				       \_/__/


		MacOS X-specific information.

	 See readme.txt for a more general overview.
@</pre>



@heading
MacOS X notes

   This is a full featured native MacOS X port. The whole codebase is young,
   so it may hold some bugs; feedback is welcome!



@heading
Required software

   To build Allegro under MacOS X, you need:

      <ul><li>MacOS X 10.2.x or newer
      <li>Apple Developer Tools (December 2002 or newer edition)</ul>

   If you don't have the Developer Tools installed, you can get the
   latest release at:
<blockquote>
      <link>http://developer.apple.com/tools/download</a>
</blockquote>
   On the same page you will also find instructions on how to install them.
   Note that system version 10.2.x is required to compile Allegro, but
   the library will still work on 10.1.x.



@heading
Installing Allegro

   Allegro ships in source code form; this means you need to compile it
   before you can use it. You do this easily from a terminal window.
   Due to the multiplatform nature of the library, the first step is to
   fix it so it can be built under MacOS X, by running:
<textblock>
      chmod +x fix.sh
      ./fix.sh macosx
<endblock>
   If you have checked out a development version from Allegro's SVN
   repository, run the following command. Otherwise, skip this step:
<textblock>
      make depend
<endblock>
   Now Allegro is ready to be compiled. Start building it:
<textblock>
      make
<endblock>
   And finally you install it (you need the root password for this step):
<textblock>
      sudo make install
<endblock>
   Allegro has now been installed in your system as a standalone shared
   library, in <tt>/usr/local/lib</tt>.
   You may also wish to install the man pages:
<textblock>
      sudo make install-man
<endblock>
   Alternatively, you can view the documentation in the Mac Help Center:
<textblock>
      sudo make install-applehelp
<endblock>
   You may also wish to install the library as a standard MacOS X framework:
<textblock>
      sudo make install-framework
<endblock>
   The "Allegro" framework will be created into <tt>/Library/Frameworks</tt>.
   Note that the framework is standalone: it contains its own copy of the
   dynamic library, so it can be safely copied around.
   If you plan to embed the Allegro framework inside your application
   bundles, you must install a special embeddable version of it:
<textblock>
      sudo make install-framework EMBED=1
<endblock>
   Embedding the framework into your application bundles ensures they will
   work also on machines where Allegro is not installed. Note that if you
   embed the non-embeddable version of the framework into your app bundle,
   your program will not be able to load it and it will not work.
   Finally, if you plan on using Project Builder to code your apps, you
   may find useful installing an Allegro application PB project template:
<textblock>
      sudo make install-template
<endblock>
   The dynamically linked version of the library gets built by default, but
   if you want to build a statically linked one, write the following on the
   command line:
<textblock>
      export STATICLINK=1
<endblock>
   In the same manner we can also enter one of the following lines to
   build either the debug or the profiling version of the library:
<textblock>
      export DEBUGMODE=1
      export PROFILEMODE=1
<endblock>
   Then restart the build process by issuing:
<textblock>
      make
      sudo make install
<endblock>
   The static library will be installed in <tt>/usr/local/lib</tt> as the shared
   one, but you will not be able to install the framework nor the Project
   Builder template, which require a dynamically linked Allegro version.

   If you have OS X 10.4 and you want to build a Universal Binary version of
   the library (i.e. one that will run on both PowerPC and Intel Macs) you
   can type
<textblock>
      ./fix.sh macosx-universal
<endblock>
   instead of the <tt>fix.sh</tt> line given above. Note that you'll still need
   to specify the appropriate flags when you link your program, otherwise
   gcc will 'thin' the binary so it only includes the native code.

   For more information see 
   http://developer.apple.com/documentation/MacOSX/Conceptual/universal_binary/


@heading
Using Allegro from the command line

   The options for linking with Allegro are quite long, expecially for
   static versions of the library as you need to pull in several different
   frameworks (Cocoa, QuickTime, etc.) other than Allegro itself. When
   linking against the shared library version, things are also different.
   To avoid you having to work out the right linker commands for yourself,
   the installation creates a script, <tt>allegro-config</tt>, that will print out a
   suitable commandline. You can use this inside a backtick command
   substitution, for example:
<textblock>
      gcc myfile.c -o myprogram `allegro-config --libs`
<endblock>
   Or if you want to build a debug version of your program, assuming that 
   you have installed the debug version of Allegro:
<textblock>
      gcc myfile.c -o myprogram `allegro-config --libs debug`
<endblock>
   You can also link against the Allegro framework, providing you previously
   installed it via <tt>make install-framework</tt>:
<textblock>
      gcc myfile.c -o myprogram `allegro-config --frameworks`
<endblock>
   Unix newbies, take note that these are ` backticks, not normal ' quotes!

   There are also switches for printing out the Allegro version number, 
   overriding the install paths, and selecting between shared and static 
   libraries, in case you installed both. Run <tt>allegro-config</tt> without any
   arguments for a full list of options.

   If you get an error like '<tt>allegro-config: program not found</tt>', and
   you're sure you have built and installed the library as described above, it
   probably means that <tt>/usr/local/bin</tt> is not on your path. The method
   to add it depends on the shell you're using. If you have tcsh, add the
   following line to the end of the <tt>.cshrc</tt> in your home directory.
<textblock>
     set path=($path /usr/local/bin)
<endblock>
   If you have bash, add the following line to the end of the <tt>.bash_profile</tt>
   file in your home directory:
<textblock>
     PATH=${PATH}:/usr/local/bin
<endblock>
   If you don't know which, just type <tt>echo $SHELL</tt> on the command 
   line, which will print either <tt>/bin/bash</tt> or <tt>/bin/tcsh</tt>.
   Newer versions of OSX use bash, older ones use tcsh.
   You will have to close the Terminal window and open a new one once
   you have made the changes, so it will have an effect.

@heading
Using Allegro from Project Builder (or XCode)

   To use Allegro from inside Apple's Project Builder, be sure you first
   installed the library as a framework and that you also installed the PB
   application template (see section "Installing Allegro" for details).

   Once you're ready, start up Project Builder and choose "New Project"
   from the "File" menu. On the very first dialog, you'll be prompted
   with a list of project templates with which to create your program.
   Select "Allegro Application" under the "Application" category and enter
   the project name and location in the next dialog. Once the setup is
   complete, you will find yourself with an opened Allegro application
   project, holding an unique source file (<tt>main.c</tt>) and some linked
   frameworks. The project can already be compiled to a working application;
   try it!

   Note that the same procedure applies to XCode, which is compatible
   with Project Builder.

   The <tt>main.c</tt> source file contains a very simple skeleton of an Allegro
   program that will open up a white window with the text "Hello, world!"
   in the center. This file is just a start: you can (and should) completely
   replace its contents to suit your needs.



@heading
Allegro and application bundles

   When you build applications from the command line, you're actually just
   creating the executable, so you can run it from the command line only,
   and not also from the finder like a common MacOS X application. In other
   words, compiling from the command line does not create application
   bundles.

   Allegro ships with a little tool, named fixbundle, which allows to build
   an application bundle out of an executable.
   The utility works from the command line and it accepts a variety of
   options to customize your bundle; the easiest way to use it is:
<textblock>
      fixbundle executable_name
<endblock>
   This will create an application bundle named "<tt>executable_name.app</tt>" that
   contains your program executable and will appear in the finder with the
   default application icon. A more complex usage example follows:
<textblock>
      fixbundle executable_name -m -o bundle_name -v "1.2" icon.bmp
<endblock>
   This creates a bundle named "<tt>bundle_name.app</tt>". The executable will be
   moved instead of copied into the bundle; the application will be marked
   as version "1.2" and icon.bmp will be converted to an icon for the
   bundle. You can specify more options and up to 4 differently sized
   icons (16x16, 32x32, 48x48 and 128x128) to be read from any Allegro
   supported image files or from datafile objects.
   Run fixbundle without arguments for the full list of known options.

   A special note is required for the "<tt>-e</tt>" switch; this lets you embed
   the Allegro framework inside the built application bundle, so your
   app will not require Allegro to be installed into the target machine
   in order to work. This flag assumes you previously installed the
   embeddable version of the Allegro framework, and that your executable
   has been linked to it, either via Project Builder or XCode, either
   via the allegro-config script.
   If one of these conditions is not met, the created app may not
   work on target machines.

   Bundles created by fixbundle have this default layout:
<textblock>
      bundle.app --- Contents --+--- MacOS --- executable
                                |
                                +--- Resources --+--- (bundle.icns)
                                |                |
                                |                +--- (executable/...)
                                |
                                |
                                +--- (Frameworks) --- (Allegro.framework/...)
                                |
                                +--- Info.plist
                                |
                                +--- PkgInfo
<endblock>
   If you are using Project Builder to compile your programs, there is no
   need to use fixbundle, as the IDE will do the work of generating an
   application bundle for you.

   When an Allegro program starts, it automatically detects if the
   executable lives inside a bundle or not. The working directory is
   always set up to be the directory where the standalone executable
   or application bundle is located, but there is an exception: if the
   application is a bundle and Allegro finds a directory under the bundle
   Contents/Resources path with the same name of the executable (note that
   here we mean the real executable name, not the bundle name), that
   directory is set to be the working one. This allows to easily package
   all the application data inside the bundle, and still have a working
   program without the need to tell your code about the changed location
   of your files.



@heading
Notes on drivers

   This section contains MacOS X-specific notes on the drivers available.
<blockquote><dl>
   <dt><b>System:</b></dt><dd>
        When the system driver is about to be initialized, we already
        have a working NSApplication object connected to the Window Server.
        At driver startup, the working directory is changed if inside a
        bundle with a proper data directory under the Contents/Resources
        path (see above).
        
        Display switching is possible, but only the </tt>SWITCH_BACKGROUND</tt>
        mode is supported, so your application will have to deal with it.</dd>

   <dt><b>Graphics:</b></dt><dd>
        The MacOS X windowed graphics mode uses a Cocoa window with a
        Quartz QuickDraw view as its content view. All combinations of
        window/desktop color depths are supported; if needed, color
        conversion will automatically be done transparently to the user.

        Fullscreen mode uses the CoreGraphics DirectDisplay API; only
        8, 15 and 32 bit color depths are supported.</dd>

   <dt><b>Sound:</b></dt><dd>
        The CoreAudio digital/MIDI drivers use V2 AudioUnits, and thus
        they require MacOS X 10.2.x (Jaguar) or newer to work. If this is
        not the case, you can fall back to the Carbon Sound Manager and
        Quicktime MIDI drivers.</dd>

   <dt><b>Keyboard:</b></dt><dd>
        MacOS X Allegro uses the current system keyboard mapping table
        to map scancodes to characters: the keyboard user settings in
        allegro.cfg have no effect.</dd>

   <dt><b>Mouse:</b></dt><dd>
        On MacOS X 10.2.x (Jaguar) or newer, Allegro will automatically
        detect the number of buttons of your mouse at driver initialization.
        If the 1-button Apple mouse is found, the library will activate an
        emulation mode that mimics the way MacOS X itself deals with
        1-button mice: depending on which key is pressed when the button is
        clicked, Allegro will report a different mouse button click.
        (Control + button) emulates a right click and (Option + button)
        emulates a middle click.

        On MacOS X 10.1.x, mouse autodetection is not possible, and Allegro
        will assume an 1-button mouse to always be present, activating
        buttons emulation accordingly.</dd>
</dl></blockquote>


@heading
Final notes

   There is a known compatibility problem when using gcc 4 on MacOS X 10.4
   that prevents binaries from working on older versions of MacOS X. While it
   is anticipated that a future update from Apple will fix this problem, you
   can use gcc 3 to work around it.

   As a final note, when coding Allegro programs don't forget that you
   need to use the <code>END_OF_MAIN()</code> macro right after your <code>main()</code> function!

