diff --git a/Makefile.am b/Makefile.am index c2563eb25e..ee8a3f24fa 100644 --- a/Makefile.am +++ b/Makefile.am @@ -39,7 +39,7 @@ EXTRA_DIST = \ README.IRIX \ README.Linux \ README.MINGW32 \ - README.MacOSX \ + README.macOS \ README.SOLARIS \ README.WINDOWS diff --git a/README.MacOSX b/README.MacOSX deleted file mode 100644 index e28364e851..0000000000 --- a/README.MacOSX +++ /dev/null @@ -1,136 +0,0 @@ -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 ".dylib" -instead of ".dll or ".so"), bzfs will still load them when you -specify the full plugin path. diff --git a/README.macOS b/README.macOS new file mode 100644 index 0000000000..fb31543596 --- /dev/null +++ b/README.macOS @@ -0,0 +1,86 @@ +BZFlag README for macOS +======================= + +BZFlag is supported on macOS 10.13 (High Sierra) and later, and official builds +are available for both Intel (x86_64) and Apple Silicon (arm64) processors. +BZFlag may be installed by downloading an official build from the BZFlag web +site (https://www.bzflag.org/downloads), expanding the archive (if necessary), +and moving the game to the Applications folder. Please note that the official +builds are not currently being signed or notarized by Apple, so on the first +launch you must bypass Gatekeeper using the contextual menu by right-clicking, +two-finger-clicking, or control-clicking on the application, selecting "Open," +and confirming when prompted. + +BZFlag is also available as a Homebrew cask using the following command (please +note the --no-quarantine flag to bypass Gatekeeper for the reason stated above): + + brew install --cask --no-quarantine bzflag + +The BZFlag macOS application package also contains the BZFlag server (bzfs), +the text-based client (bzadmin), server plugins, and various other tools. You +may access these additional components using a terminal application or by using +the contextual menu in the Finder (as described above) to explore the +application package contents. + +By default, the BZFlag configuration directory on macOS is located at the +following path (note that the ~/Library directory is hidden by default, but you +can open it using the command-shift-g key combination): + + ~/Library/Application Support/BZFlag + +When using a MacBook which has a camera notch in the display, you may also want +to enable the option "Scale to fit below built-in camera" in the "Get Info" +panel for the application to avoid a portion of the game window being obscured +while in fullscreen mode. + +Building from Source +-------------------- + +To build BZFlag from source code on macOS, you will first need to acquire the +source code from the GitHub repository (https://github.com/BZFlag-Dev/bzflag) +and install Xcode. You will also need to acquire our three library dependencies, +SDL2, GLEW, and c-ares. The recommended method for acquiring these dependencies +is to use our provided dependencies package, which can be accessed from the +GitHub repository (https://github.com/BZFlag-Dev/bzflag-dependencies). Look for +a release package for the BZFlag version you are building, or you may download +the dependencies source package and build them using the following command: + + ./buildmacOS.sh + +You should now have a directory named "dependencies" which you should copy to +the root of the main BZFlag source code directory so it is available while +building. + +Alternatively, the required dependencies may be installed at the system level +using autotools or may be installed via Homebrew. Keep in mind that either of +these these latter two options may cause a deployment target mismatch. + +The Xcode project file is located within the Xcode/ directory. Upon opening the +project, please ensure that your desired scheme (usually "BZFlag") is activated +at the top of the screen (you may also select "bzfs," "bzadmin," etc.). Please +note that a debug build is configured by default. A release build may be +configured by clicking the "BZFlag" scheme button at the top of the screen, +selecting "Edit Scheme..." at the bottom of the pop-up menu, selecting the "Run" +phase in the left sidebar, selecting the "Info" tab, and setting the desired +build configuration. To compile BZFlag for a different architecture, in the +project build settings set "Build Active Architecture Only" to "No" and manually +set "Architectures" to the target architecture name ("x86_64" or "arm64"). + +You may also build BZFlag from source code using the standard autotools build +process, but please keep in mind that this method on macOS receives less +maintenance effort than building with Xcode. To build via autotools, use the +following commands: + + ./autogen.sh + ./configure + make + +Issues +------ + +Due to diminishing support for OpenGL-based graphics on macOS, please note that +occasional graphical issues have been known to arise. Updating to the latest +macOS version has been known to improve graphics driver support in some cases. +Our goal is to fix or mitigate any reported issues (graphical or otherwise) to +the best of our ability. Please submit any bug reports or comments to the issue +tracker on our GitHub page (https://github.com/BZFlag-Dev/bzflag/issues). diff --git a/Xcode/BZFlag.xcodeproj/project.pbxproj b/Xcode/BZFlag.xcodeproj/project.pbxproj index 6cb7689536..d0a9b863d2 100644 --- a/Xcode/BZFlag.xcodeproj/project.pbxproj +++ b/Xcode/BZFlag.xcodeproj/project.pbxproj @@ -220,7 +220,7 @@ 036F58241DA2F8C800BF906C /* ChangeLog in Resources */ = {isa = PBXBuildFile; fileRef = 03D88EA81670CB1300725DBE /* ChangeLog */; }; 036F58251DA2F8CC00BF906C /* COPYING in Resources */ = {isa = PBXBuildFile; fileRef = 03E42D191B322DFC006EE763 /* COPYING */; }; 036F58261DA2F8D400BF906C /* README in Resources */ = {isa = PBXBuildFile; fileRef = 03D88EAB1670CB1300725DBE /* README */; }; - 036F58271DA2F90900BF906C /* README.MacOSX in Resources */ = {isa = PBXBuildFile; fileRef = 03D88EAC1670CB1300725DBE /* README.MacOSX */; }; + 036F58271DA2F90900BF906C /* README.macOS in Resources */ = {isa = PBXBuildFile; fileRef = 03D88EAC1670CB1300725DBE /* README.macOS */; }; 0370A48D1B0C924B00FEC9F7 /* modeltool.cxx in Sources */ = {isa = PBXBuildFile; fileRef = 0370A4691B0C8FBA00FEC9F7 /* modeltool.cxx */; }; 0370A48E1B0C924B00FEC9F7 /* Q3BSP.cxx in Sources */ = {isa = PBXBuildFile; fileRef = 0370A46A1B0C8FBA00FEC9F7 /* Q3BSP.cxx */; }; 0370A48F1B0C924B00FEC9F7 /* wavefrontOBJ.cxx in Sources */ = {isa = PBXBuildFile; fileRef = 0370A46C1B0C8FBA00FEC9F7 /* wavefrontOBJ.cxx */; }; @@ -1794,7 +1794,7 @@ 03D88EA91670CB1300725DBE /* DEVINFO */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; name = DEVINFO; path = ../DEVINFO; sourceTree = ""; }; 03D88EAA1670CB1300725DBE /* PORTING */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; name = PORTING; path = ../PORTING; sourceTree = ""; }; 03D88EAB1670CB1300725DBE /* README */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; name = README; path = ../README; sourceTree = ""; }; - 03D88EAC1670CB1300725DBE /* README.MacOSX */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; name = README.MacOSX; path = ../README.MacOSX; sourceTree = ""; }; + 03D88EAC1670CB1300725DBE /* README.macOS */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; name = README.macOS; path = ../README.macOS; sourceTree = ""; }; 03D926DF166C67EF00DDDBEB /* BZFlag.icns */ = {isa = PBXFileReference; lastKnownFileType = image.icns; path = BZFlag.icns; sourceTree = ""; }; 03DBE9BA1B30E12300711E71 /* Cocoa.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Cocoa.framework; path = System/Library/Frameworks/Cocoa.framework; sourceTree = SDKROOT; }; 03E42D121B321DF2006EE763 /* data */ = {isa = PBXFileReference; lastKnownFileType = folder; name = data; path = ../data; sourceTree = ""; }; @@ -3485,7 +3485,7 @@ 03D88EA91670CB1300725DBE /* DEVINFO */, 03D88EAA1670CB1300725DBE /* PORTING */, 03D88EAB1670CB1300725DBE /* README */, - 03D88EAC1670CB1300725DBE /* README.MacOSX */, + 03D88EAC1670CB1300725DBE /* README.macOS */, ); name = Documentation; sourceTree = ""; @@ -4924,7 +4924,7 @@ 036F58241DA2F8C800BF906C /* ChangeLog in Resources */, 036F58251DA2F8CC00BF906C /* COPYING in Resources */, 036F58261DA2F8D400BF906C /* README in Resources */, - 036F58271DA2F90900BF906C /* README.MacOSX in Resources */, + 036F58271DA2F90900BF906C /* README.macOS in Resources */, ); runOnlyForDeploymentPostprocessing = 0; };