Setting up macOS for Development

Freeciv21 compiles and runs on Apple® macOS Sonoma (v14) or higher. The following steps can be used to setup your mac to compile and run Freeciv21.

Homebrew

Homebrew is a package manager for macOS and allows us to download and install some libraries and tools we need. Let us start with getting it installed and setting an environment variable.

% /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
% echo '# Freeciv21 macOS variables' >> $HOME/.zshrc
% echo 'eval "$(/usr/local/bin/brew shellenv)"' >> $HOME/.zshrc
% source $HOME/.zshrc

Note

These instructions assume you are using the default z-shell (zsh) as your terminal shell. If you are using the bash shell instead replace the output to $HOME/.bash_profile or $HOME/.bashrc.

With homebrew installed and setup, now install some packages:

% brew install --overwrite \
    autoconf \
    autoconf-archive \
    automake \
    cmake \
    create-dmg \
    libtool \
    llvm@17 \
    ninja \
    pkgconf \
    python@3.13

Note

Every package is required except for create-dmg and llvm@17. The create-dmg package is used to build an app bundle and package to a .dmg installer. The llvm@17 package installs the varying clang tools we use such as clang-tidy v17. We do not override the version of the clang++ compiler that is installed with the XCode CLI tools that homebrew installed earlier.

The Python package offers non-versioned programs (python vs python3). To make accessing them easier, let us adjust the path variable:

% echo 'export PATH="$PATH:/usr/local/opt/python@3.13/libexec/bin"' >> $HOME/.zshrc
% source $HOME/.zshrc

Setup VCPKG

Similar to homebrew, Microsoft® manages a package library called vcpkg. Freeciv21 requires libraries from vcpkg, so we install with these commands:

% mkdir $HOME/GitHub
% cd $HOME/GitHub
% git clone https://github.com/microsoft/vcpkg
% echo 'export VCPKG_ROOT="$HOME/GitHub/vcpkg"' >> $HOME/.zshrc
% source $HOME/.zshrc
% /bin/bash ./vcpkg/bootstrap-vcpkg.sh

Get Freeciv21

Follow these steps to get Freeciv21 from GitHub.

Configure and Build

On macOS, you need to use a preset that is defined in the CMakePresets.json file.

% cmake --preset fullrelease-macos -S .
% cmake --build build
% cmake --build build --target test
% cmake --build build --target install

Note

The first time you run the first command, cmake invokes the vcpkg installation process to download and compile all of the project dependencies listed in the manifest file: vcpkg.json. This will take a very long time. On a fast computer with a good Internet connection it will take at least 3 hours to complete. Everything will be downloaded and compiled into the $HOME/GitHub/vcpkg directory. Binaries for the packages will be copied into the ./build/ directory inside of the main Freeciv21 directory and reused for subsequent builds.

Create DMG Installer

Follow this steps to create the DMG:

% create-dmg \
      --hdiutil-verbose \
      --volname "Freeciv21 Game Installer" \
      --volicon "client.icns" \
      --window-pos 200 120 \
      --window-size 800 400 \
      --icon-size 128 \
      --icon "Freeciv21.app" 200 190 \
      --hide-extension "Freeciv21.app" \
      --app-drop-link 600 185 \
      "Freeciv21-installer.dmg" \
      "Freeciv21.app"