1BZFlag README for Mac OS X
2==========================
3
4BZFlag is supported on Mac OS X 10.7 and later. Included below are
5instructions on installing BZFlag both from a binary and from a released
6source distribution.
7
8Binary Distribution
9-------------------
10
11See the project site downloads of BZFlag at
12https://github.com/BZFlag-Dev/bzflag/releases to obtain the latest binary
13distribution.
14
15Once you've obtained a binary distribution of BZFlag, installation should be a
16simple matter of decompressing the downloaded file and then copying the
17program to your Applications folder. If you cannot run the client at all (i.e.
18it starts to a black screen, or the icon bounces but then nothing happeys),
19you can try several things:
20
21  1) Move or delete the BZFlag directory in your personal application support
22     folder at ~/Library/Application Support/BZFlag. As of Mac OS X 10.7, the
23     ~/Library directory is hidden by default. You can open it by navigating
24     to your home directory, entering the Command-Shift-G key sequence, then
25     typing "Library" and clicking "Go." Note that this directory contains
26     your saved configuration, screenshots, and map files, so you may want to
27     move or delete only your configuration file (stored in the directory with
28     the BZFlag version number).
29
30  2) Check your console for error messages. Open your console application at
31     /Utilities/Console.app, and expand the "User Diagnostic Reports" list in
32     the sidebar under "Diagnostic and Usage Information." Any crash reports
33     should be listed there and will start with "BZFlag."
34
35  3) Run the binary directly by using Terminal:
36       /Applications/BZFlag-#.#.#.app/Contents/MacOS/BZFlag
37       (replace "#.#.#" with your actual BZFlag version number)
38
39Source Distribution
40-------------------
41
42You can build BZFlag from source using Xcode version 7 and later (You may also
43be able to build with Xcode versions as early as 4.2, but you will need to
44update the locations of libncurses, libcurl, and libz since those changed in
45the Mac OS X 10.11 SDK). As of BZFlag version 2.4.4, BZFlag has a fully native
46Xcode project file. The earlier method of using the Xcode project file as a
47wrapper for autotools is no longer supported. If you have a version of Xcode
48which includes autotools, or have installed autotools yourself, you may
49additionally be able to build using the traditional autotools method. See the
50README file for further information. You will still need to install the SDL 2
51framework as detailed below.
52
53BZFlag has three external dependencies: SDL 2, GLEW, and c-ares.
54
55Download the latest version of the SDL 2 framework from
56https://www.libsdl.org/download-2.0.php. Version 2.0.3 or later is required,
57but version 2.0.4 or later is highly recommended because it includes a new
58function for capturing mouse input to help address a mouse warping problem.
59If you obtained a binary release of SDL 2, mount the disk image and place the
60file "SDL2.framework" in your /Library/Frameworks directory (an administrator's
61account may be required). If you built SDL 2 from source, locate the file
62"SDL2.framework" and copy it into that same location.
63
64This project expects the GLEW and c-ares libraries and header files to be
65located in /usr/local. If you install them elsewhere, you must update the
66library and header search paths in this project file appropriately.
67
68Download the latest version of GLEW from
69https://github.com/nigels-com/glew/releases. Extract the package, and then
70build it with the following commands (WARNING: this will remove all shared
71libraries for GLEW under /usr/local, even older versions you may have
72installed; this is necessary because it appears there is currently no way to
73configure GLEW to build without shared libraries):
74
75$ export MACOSX_DEPLOYMENT_TARGET=10.7
76$ export GLEW_DEST=/usr/local
77$ make glew.lib
78$ sudo make install
79$ sudo rm /usr/local/lib/libGLEW*.dylib
80
81Download the latest version of c-ares from http://c-ares.haxx.se.
82Extract the package, and then build it with the following commands:
83
84$ export MACOSX_DEPLOYMENT_TARGET=10.7
85$ ./configure --disable-shared
86$ make
87$ sudo make install
88
89Obtain the latest BZFlag source archive from GitHub at
90https://github.com/BZFlag-Dev/bzflag. Once you have obtained the source code,
91open the BZFlag.xcodeproj file located in the Xcode/ directory.
92
93The default behavior is to build a debug client. If you want a standard
94client, click the "BZFlag" scheme button at the top left corner of the screen,
95scroll down, and click "Edit Scheme..." at the bottom of the pop-up menu. In
96the left sidebar, click the Run phase, and in the right area select the
97Info tab. Under Build Configuration, select the desired scheme of Debug or
98Release.
99
100To build the client, select Build from the Product menu or enter the Command-B
101key sequence. Note that the BZFlag version is no longer automatically
102appended to the build product.
103
104If the build was successful, you can run the application from Xcode selecting
105the Product menu and clicking Run or by entering the Command-R key sequence.
106You will also want to locate the application you just built. Make sure the
107Navigator pane is visible and select the Project Navigator, then expand the
108"BZFlag" project container and the "Targets" group within it. Click the
109"BZFlag.app" target. Make sure the Utilities pane is visible, and under
110the Identity and Type panel it will show the full path to the application.
111Click the small grey right arrow at the bottom right corner of the path to
112reveal the application in the Finder.
113
114NOTICE: If you're compiling from source, it is expected that you have
115sufficient/proficient understanding of how to compile applications on the
116command line or using XCode and how to perform compilation troubleshooting
117without assistance.  This holds particularly true for all alpha/beta testing
118releases as well as for any sources pulled directly from the Subversion source
119repository checkout. If you have problems building from a checkout, you should
120try building from an official release that we have posted to GitHub to
121see if you can duplicate the issue, and then ask us for assistance.
122
123Usage
124-----
125
126To install BZFlag, copy the application you obtained as a binary distribution
127or built from source into your /Applications directory, or use it from another
128location of your choice. Different client versions may exist simultaneously on
129any system without issue.
130
131To access the bzadmin text client or the bzflag server bzfs, right click the
132application, click "Show Package Contents," and navigate to Contents/MacOS.
133Server plugins are located at Contents/PlugIns. Note that while the plugin
134names are different from Windows and Linux (something like "<name>.dylib"
135instead of "<name>.dll or "<name>.so"), bzfs will still load them when you
136specify the full plugin path.
137