BZFlag README for Mac OS X
==========================

BZFlag is supported on Mac OS X 10.7 and later. Included below are
instructions on installing BZFlag both from a binary and from a released
source distribution.

Binary Distribution
-------------------

See the project site downloads of BZFlag at
https://github.com/BZFlag-Dev/bzflag/releases to obtain the latest binary
distribution.

Once you've obtained a binary distribution of BZFlag, installation should be a
simple matter of decompressing the downloaded file and then copying the
program to your Applications folder. If you cannot run the client at all (i.e.
it starts to a black screen, or the icon bounces but then nothing happeys),
you can try several things:

  1) Move or delete the BZFlag directory in your personal application support
     folder at ~/Library/Application Support/BZFlag. As of Mac OS X 10.7, the
     ~/Library directory is hidden by default. You can open it by navigating
     to your home directory, entering the Command-Shift-G key sequence, then
     typing "Library" and clicking "Go." Note that this directory contains
     your saved configuration, screenshots, and map files, so you may want to
     move or delete only your configuration file (stored in the directory with
     the BZFlag version number).

  2) Check your console for error messages. Open your console application at
     /Utilities/Console.app, and expand the "User Diagnostic Reports" list in
     the sidebar under "Diagnostic and Usage Information." Any crash reports
     should be listed there and will start with "BZFlag."

  3) Run the binary directly by using Terminal:
       /Applications/BZFlag-#.#.#.app/Contents/MacOS/BZFlag
       (replace "#.#.#" with your actual BZFlag version number)

Source Distribution
-------------------

You can build BZFlag from source using Xcode version 7 and later (You may also
be able to build with Xcode versions as early as 4.2, but you will need to
update the locations of libncurses, libcurl, and libz since those changed in
the Mac OS X 10.11 SDK). As of BZFlag version 2.4.4, BZFlag has a fully native
Xcode project file. The earlier method of using the Xcode project file as a
wrapper for autotools is no longer supported. If you have a version of Xcode
which includes autotools, or have installed autotools yourself, you may
additionally be able to build using the traditional autotools method. See the
README file for further information. You will still need to install the SDL 2
framework as detailed below.

BZFlag has three external dependencies: SDL 2, GLEW, and c-ares.

Download the latest version of the SDL 2 framework from
https://www.libsdl.org/download-2.0.php. Version 2.0.3 or later is required,
but version 2.0.4 or later is highly recommended because it includes a new
function for capturing mouse input to help address a mouse warping problem.
If you obtained a binary release of SDL 2, mount the disk image and place the
file "SDL2.framework" in your /Library/Frameworks directory (an administrator's
account may be required). If you built SDL 2 from source, locate the file
"SDL2.framework" and copy it into that same location.

This project expects the GLEW and c-ares libraries and header files to be
located in /usr/local. If you install them elsewhere, you must update the
library and header search paths in this project file appropriately.

Download the latest version of GLEW from
https://github.com/nigels-com/glew/releases. Extract the package, and then
build it with the following commands (WARNING: this will remove all shared
libraries for GLEW under /usr/local, even older versions you may have
installed; this is necessary because it appears there is currently no way to
configure GLEW to build without shared libraries):

$ export MACOSX_DEPLOYMENT_TARGET=10.7
$ export GLEW_DEST=/usr/local
$ make glew.lib
$ sudo make install
$ sudo rm /usr/local/lib/libGLEW*.dylib

Download the latest version of c-ares from http://c-ares.haxx.se.
Extract the package, and then build it with the following commands:

$ export MACOSX_DEPLOYMENT_TARGET=10.7
$ ./configure --disable-shared
$ make
$ sudo make install

Obtain the latest BZFlag source archive from GitHub at
https://github.com/BZFlag-Dev/bzflag. Once you have obtained the source code,
open the BZFlag.xcodeproj file located in the Xcode/ directory.

The default behavior is to build a debug client. If you want a standard
client, click the "BZFlag" scheme button at the top left corner of the screen,
scroll down, and click "Edit Scheme..." at the bottom of the pop-up menu. In
the left sidebar, click the Run phase, and in the right area select the
Info tab. Under Build Configuration, select the desired scheme of Debug or
Release.

To build the client, select Build from the Product menu or enter the Command-B
key sequence. Note that the BZFlag version is no longer automatically
appended to the build product.

If the build was successful, you can run the application from Xcode selecting
the Product menu and clicking Run or by entering the Command-R key sequence.
You will also want to locate the application you just built. Make sure the
Navigator pane is visible and select the Project Navigator, then expand the
"BZFlag" project container and the "Targets" group within it. Click the
"BZFlag.app" target. Make sure the Utilities pane is visible, and under
the Identity and Type panel it will show the full path to the application.
Click the small grey right arrow at the bottom right corner of the path to
reveal the application in the Finder.

NOTICE: If you're compiling from source, it is expected that you have
sufficient/proficient understanding of how to compile applications on the
command line or using XCode and how to perform compilation troubleshooting
without assistance.  This holds particularly true for all alpha/beta testing
releases as well as for any sources pulled directly from the Subversion source
repository checkout. If you have problems building from a checkout, you should
try building from an official release that we have posted to GitHub to
see if you can duplicate the issue, and then ask us for assistance.

Usage
-----

To install BZFlag, copy the application you obtained as a binary distribution
or built from source into your /Applications directory, or use it from another
location of your choice. Different client versions may exist simultaneously on
any system without issue.

To access the bzadmin text client or the bzflag server bzfs, right click the
application, click "Show Package Contents," and navigate to Contents/MacOS.
Server plugins are located at Contents/PlugIns. Note that while the plugin
names are different from Windows and Linux (something like "<name>.dylib"
instead of "<name>.dll or "<name>.so"), bzfs will still load them when you
specify the full plugin path.
