#summary Instructions for building Hedgewars on macOS

#labels Phase-Implementation,Phase-Deploy,Phase-Support

= Building on macOS =

Also known as OS X or Mac OS X.

*Note:* These instructions were run on OS X 10.11 and backwards compiled for OS X 10.8 (Aug 2019). Newer versions will likely work but may require some adaptation.

== Prerequisites ==

=== Required Build Dependencies ===

Homebrew ([https://brew.sh/]) can be used to gather many of these dependencies, but is not required. All can be found as installers, frameworks, or built manually without Homebrew.

Unless otherwise specified, latest versions of the following dependencies can be used.

==== Compilers and Environment ====

 * Xcode command-line tools

 * CMake 3.9 or later

 * fpc 2.6.x OR fpc 3.1.1+ (nothing in between, due a crashing bug)

==== Libraries ====

Libraries can be dynamically linked libraries (`.dylib`) or Apple frameworks (`.framework`). All must be on the system library or framework paths for CMake to find them. Frameworks can be put in your home directory at `~/Library/Frameworks`.

 * Qt 5.9.x or later (unified installer works)

 * SDL2

 * SDL2_image (2.0.4 works, 2.0.5 might be buggy)

 * SDL2_mixer

 * SDL2_net

 * SDL2_ttf

 * Ogg

 * Vorbis

 * libpng 1.6.x

 * physfs 3.0.x

==== Notes ====

 # Other dependencies are linked with the SDL2 libraries, but not specifically used in Hedgewars. They may include:

  * !FreeType

  * FLAC

  * Opus

  * GLEW

  * modplug

  * mpg123

  * webp

 # Good places to find required frameworks are found in the development packages for the various SDL2 libraries. They are found in the `Frameworks` subdirectory within the .framework itself. Example: `SDL2_ttf.framework/Frameworks/FreeType.framework`

 # Another good place for the frameworks/libraries are in the `Hedgewars.app` of a previous version (E.g. Hedgewars 1.0.0 Beta 2)

=== Optional Dependencies ===

By default, the following optional features are turned on in the build system, and require the following dependencies:

 * Video recording

   * ffmpeg 4.2 (later versions are untested)

     * yasm 1.3+

 * Automatic updates

   * Sparkle

 * hedgewar-server

   * ghc, cabal (Haskell)

     * xz

==== Haskell Installation ====

Steps to get the Haskell environment set up for compiling hedgewars-server:

 # Install ghc, cabal with instructions at https://www.haskell.org/ghcup/

 # Load ghc environment: `source ~/.ghcup/env`

 # Install cabal-uninstall: `cabal install cabal-uninstall`

 # Install haskell packages: `cabal install vector bytestring 'network < 2.7' time mtl sandi 'hslogger < 1.3' process utf8-string SHA entropy zlib random regex-tdfa deepseq`

`cabal-uninstall` is for when you accidentally install newer package versions that don't work with hedgewars-server (e.g. hslogger-1.3.0.0)

== Building Hedgewars ==

=== Environment Setup ===

 * Set macOS version to target for Xcode tools. The earlier, the better:

{{{

export MACOSX_DEPLOYMENT_TARGET=10.8

}}}

 * (Optional) Load haskell environment:

{{{

source ~/.ghcup/env

}}}

 * Create (`mkdir`) a `build` subdirectory in the Hedgewars source code

=== Build ===

CMake is used to manage the build process, and is run with different flags depending on which optional dependencies you have elected to install.

Take note of where Qt is installed; it is a required build flag (see below).

Steps to build:

 # `cd /path/to/hg/hedgewars/build`

 # `cmake .. -DCMAKE_PREFIX_PATH=/Users/user/Qt/5.9.8/clang_64/ -DCMAKE_BUILD_TYPE=Release`

 # `make -j2`

 # `make install`

A `Hedgewars.app` file will be created in the same folder you ran CMake.

To build the DMG, also run:

 * `make dmg`

==== Notes ====

 * To build a debug build, use the flag `-DCMAKE_BUILD_TYPE=Debug` instead of the `Release` one

 * To build a minimum-features build, use the additional flags of `-DNOSERVER=1`, `-DNOVIDEOREC=1`, and `-DNOAUTOUPDATE=1`, for disabling of hedgewars-server, video recording, and Sparkle autoupdating, respectively.

 * The build uses CMake !BundleUtilities which automatically deploys all libraries and dependencies  into the `.app`, and repairs the `RPATH` of each library and binary as needed. If there is a missing dependency, the `make install` portion of the build will fail. The fix is usually to find the correct `.framework` and put in on library path, then run `make dmg` again.

Enjoy!