Difference between revisions of "How to build VCMI (macOS)"

From VCMI Project Wiki
Jump to: navigation, search
(completely reworked instructions)
Line 1: Line 1:
−
= Installing dependencies =
+
= Requirements =
−
===== Installing Xcode =====
+
# C++ toolchain, either of:
−
App Store -> Xcode
+
#* Xcode Command Line Tools: <code>sudo xcode-select --install</code>
−
Launch it after the installation to agree with it's license terms.
+
#* Xcode IDE: https://developer.apple.com/xcode/
 +
#* (not tested) other C++ compilers, e.g. gcc/clang from [https://brew.sh/ Homebrew]
 +
# CMake: <code>brew install --cask cmake</code> or get from https://cmake.org/download/
 +
# (optional) Ninja: <code>brew install ninja</code> or get from https://github.com/ninja-build/ninja/releases
  
−
Alternatively Xcode can be downloaded from Apple Developers website.
+
= Obtaining source code =
−
Registration is easier and every possible version is available: https://developer.apple.com/download/more/
+
Clone https://github.com/vcmi/vcmi with submodules. Example for command line:
 +
<nowiki>git clone --recurse-submodules https://github.com/vcmi/vcmi.git</nowiki>
  
−
===== Setting Xcode version Xcode =====
+
= Obtaining dependencies =
−
In case you have some weird CMake errors during generation attempts such as
+
There're 2 ways to get dependencies automatically.
−
<pre>
+
 
−
CMake Error: Xcode 1.5 not supported.
+
== Conan package manager ==
−
</pre>
+
That's what our CI uses.
−
You might need to specify installed version of Xcode:
+
 
−
<pre>
+
# [https://docs.conan.io/en/latest/installation.html Install Conan]
−
sudo /usr/bin/xcode-select --switch /Users/admin/Downloads/Xcode.app
+
# Execute in Terminal: <code>conan profile new default --detect</code>
−
</pre>
+
# Download prebuilt libraries from [https://github.com/vcmi/vcmi-deps-macos/releases GitHub Releases]:
−
After that Cmake will be able to generate projects properly!
+
#* if you're on an Intel Mac, download file '''intel.txz''' and unpack it to <code>~/.conan</code> directory.
 +
#* if you're on an ARM Mac, download file '''intel-cross-arm.txz''' and unpack it to <code>~/.conan</code> directory. Then follow [https://github.com/vcmi/vcmi-ios-deps#note-for-arm-macs instructions how to build Qt host tools for ARM], on step 3 copy them to <code>~/.conan/data/qt/5.15.5/_/_/package/SOME_HASH/bin</code>.
 +
# In Terminal <code>cd</code> to the source code directory and run:
 +
<blockquote>USE_CONAN_WITH_ALL_CONFIGS=1 conan install . --install-folder='''conan-generated''' --no-imports --build=never --profile:build=default --profile:host=CI/conan/'''PROFILE'''</blockquote>
 +
where '''conan-generated''' can be any directory you like (Conan helper files will appear there) and '''PROFILE''' must be replaced with:
 +
* if you're on an Intel Mac: <code>macos-intel</code>
 +
* if you're on an ARM Mac: <code>macos-arm</code>
  
−
===== Installing [https://brew.sh/ Homebrew] =====
+
== Homebrew ==
−
<pre>
+
# [https://brew.sh/ Install Homebrew]
−
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+
# Install dependencies: <code>brew install boost ffmpeg@4 luajit minizip sdl2 sdl2_image sdl2_mixer sdl2_ttf tbb</code>
−
</pre>
+
# Install Qt dependency in either of the ways (note that you can skip this if you're not going to build Launcher):
 +
#* <code>brew install qt@5</code> for Qt 5 or <code>brew install qt</code> for Qt 6
 +
#* using [https://www.qt.io/download Qt Online Installer] - choose '''Go open source'''
  
−
===== Installing dependencies using Homebrew =====
+
= Preparing build environment =
−
<pre>
+
This applies only to Xcode-based toolchain. If <code>xcrun -f clang</code> prints errors, then use either of the following ways:
−
brew install git cmake
+
* select an Xcode instance from Xcode application - Preferences - Locations - Command Line Tools
−
</pre>
+
* use <code>xcode-select</code> utility to set Xcode or Xcode Command Line Tools path: for example, <code>sudo xcode-select -s /Library/Developer/CommandLineTools</code>
 +
* set <code>DEVELOPER_DIR</code> environment variable pointing to Xcode or Xcode Command Line Tools path: for example, <code>export DEVELOPER_DIR=/Applications/Xcode.app</code>
  
−
= Building VCMI in command line with Makefiles =
+
= Configuring project for building =
−
===== Getting and configuring VCMI =====
+
Note that if you wish to use Qt Creator IDE, you should skip this step and configure respective variables inside the IDE.
−
<pre>
 
−
# You can choose any directory
 
−
mkdir ~/DEV && cd ~/DEV
 
−
# Clone VCMI with all submodules
 
−
git clone --recursive  https://github.com/vcmi/vcmi.git
 
−
# Installing dependencies
 
−
sh ./vcmi/CI/mac/before_install.sh
 
−
# You might need to add QT to your PATH. Currently it can be done like that (see the end of before_install.sh, it does the same for CI)
 
−
# echo 'export PATH="/usr/local/opt/qt5:$PATH"' >> ~/.bash_profile
 
−
# Creating directory for building
 
−
mkdir cmake && cd cmake
 
−
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -Wno-devc
 
−
</pre>
 
−
You can as well build VCMI without Qt5 or launcher by disabling it:
 
−
<pre>
 
−
# But please don't do that unless you know what you're doing
 
−
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DENABLE_LAUNCHER=0 -Wno-devc
 
−
</pre>
 
  
−
===== Building and packaging VCMI =====
+
# In Terminal <code>cd</code> to the source code directory
−
<pre>
+
# Start assembling CMake invocation: type <code>cmake -S . -B BUILD_DIR</code> where ''BUILD_DIR'' can be any path, don't press Return
−
cd ~/DEV/cmake
+
# Decide which CMake generator you want to use:
−
# Start build using cmake
+
#* Makefiles: no extra option needed or pass <code>-G 'Unix Makefiles'</code>
−
cmake --build . -- -j 4
+
#* Ninja (if you have installed it): pass <code>-G Ninja</code>
−
# Or you can as well use simple
+
#* Xcode IDE (if you have installed it): pass <code>-G Xcode</code>
−
# make -j 4
+
# If you picked Makefiles or Ninja, pick desired ''build type'' - either of Debug / RelWithDebInfo / Release / MinSizeRel - and pass it in <code>CMAKE_BUILD_TYPE</code> option, for example: <code>-D CMAKE_BUILD_TYPE=Release</code>. If you don't pass this option, <code>RelWithDebInfo</code> will be used.
 +
# If you don't want to run tests, pass <code>-D ENABLE_TEST=OFF</code>
 +
# If you don't want to build Launcher, pass <code>-D ENABLE_LAUNCHER=OFF</code>
 +
# You can also pass <code>-Wno-dev</code> if you're not interested in CMake developer warnings
 +
# Next step depends on the dependency manager you have picked:
 +
#* Conan: pass <code>-D CMAKE_TOOLCHAIN_FILE=conan-generated/conan_toolchain.cmake</code> where '''conan-generated''' must be replaced with your name choice at step 4 of [[#Conan package manager]]
 +
#* Homebrew: pass <code>-D "CMAKE_PREFIX_PATH=$(brew --prefix ffmpeg@4)"</code>
 +
#** if you installed Qt 5 from Homebrew, '''append''' to the above option but '''before the closing quote''': <code>;$(brew --prefix qt@5)</code>
 +
#** if you installed Qt from Online Installer, '''append''' to the above option but '''before the closing quote''' your path to Qt directory, for example: <code>;/Users/kambala/dev/Qt-libs/5.15.2/Clang64</code>
 +
#** example of what you should pass in the first case: <code>-D "CMAKE_PREFIX_PATH=$(brew --prefix ffmpeg@4);$(brew --prefix qt@5)"</code>
 +
# If you're on an ARM Mac and using Conan, also pass: <code>-D ENABLE_ERM=OFF -D ENABLE_LUA=OFF</code>
 +
# now press Return
  
−
# When build is completed you can trigger packaging into DMG
+
= Building project =
−
cpack
 
−
# After file named such as "vcmi-0.99.dmg" will be created
 
−
</pre>
 
  
−
= Building VCMI with Xcode =
+
You must also install game files to be able to run the built version, see [[Installation on macOS]].
−
===== Getting and configuring VCMI =====
 
−
<pre>
 
−
# You can choose any directory
 
−
mkdir ~/DEV && cd ~/DEV
 
−
# Clone VCMI with all submodules
 
−
git clone --recursive  https://github.com/vcmi/vcmi.git
 
−
# Installing dependencies
 
−
sh ./vcmi/CI/mac/before_install.sh
 
−
# You might need to add QT to your PATH. Currently it can be done like that (see the end of before_install.sh, it does the same for CI)
 
−
# echo 'export PATH="/usr/local/opt/qt5:$PATH"' >> ~/.bash_profile
 
−
# Creating directory for building
 
−
mkdir cmake && cd cmake
 
−
# Xcode is multi-configuration project so specifying CMAKE_BUILD_TYPE makes no sense
 
−
cmake ../vcmi -G "Xcode"
 
  
−
# You can as well open project in Xcode using:
+
== From Xcode IDE ==
−
open VCMI.xcodeproj
+
Open <code>VCMI.xcodeproj</code> from the build directory, select <code>vcmiclient</code> scheme and hit Run (Cmd+R). To build Launcher, select <code>vcmilauncher</code> scheme instead.
−
</pre>
 
  
−
===== Building and packaging VCMI =====
+
== From command line ==
−
<pre>
+
<code>cmake --build <path to build directory> --target vcmiclient</code>
−
cd ~/DEV/xcode
 
−
# Start build. Xcode built using multiple processes by default so you don't need to specify it
 
−
# Since it's multi-configuration project you need to specify if you want Debug build since Release is default
 
−
cmake --build . --config Debug
 
  
−
# You have to specify build configuration for CPack. Otherwise it's will expect Release as default
+
* If using Makefiles generator, you'd want to utilize all your CPU cores by appending <code>-- -j$(sysctl -n hw.ncpu)</code> to the above
−
cpack -C Debug
+
* If using Xcode generator, you can also choose which configuration to build by appending <code>--config <configuration name></code> to the above, for example: <code>--config Debug</code>
−
</pre>
 
  
−
= Building VCMI with Qt Creator =
+
= Packaging project into DMG file =
−
First you need to clone repository and install dependencies
+
After building, run <code>cpack</code> from the build directory. If using Xcode generator, also pass <code>-C <configuration name></code> with the same configuration that you used to build the project.
−
<pre>
 
−
# You can choose any directory
 
−
mkdir ~/DEV && cd ~/DEV
 
−
# Clone VCMI with all submodules
 
−
git clone --recursive  https://github.com/vcmi/vcmi.git
 
−
# Installing dependencies
 
−
sh ./vcmi/CI/mac/before_install.sh
 
−
# You might need to add QT to your PATH. Currently it can be done like that (see the end of before_install.sh, it does the same for CI)
 
−
# echo 'export PATH="/usr/local/opt/qt5:$PATH"' >> ~/.bash_profile
 
−
</pre>
 
−
When opening project with Qt Creator installed using online installer you might have a problem with CMake unable to find Qt even if you added it into the $PATH environment variable. In that case try to open it from command line:
 
−
<pre>
 
−
open ~/Qt/Qt\ Creator.app
 
−
</pre>
 
  
 
= Running VCMI =
 
= Running VCMI =
Line 115: Line 84:
 
Alternatively you can run binaries directly from "bin" directory:
 
Alternatively you can run binaries directly from "bin" directory:
 
<pre>
 
<pre>
−
~/DEV/cmake/bin/vcmilauncher
+
BUILD_DIR/bin/vcmilauncher
−
~/DEV/cmake/bin/vcmiclient
+
BUILD_DIR/bin/vcmiclient
−
~/DEV/cmake/bin/vcmiserver
+
BUILD_DIR/bin/vcmiserver
 
</pre>
 
</pre>
 
CMake include commands to copy all needed assets from source directory into "bin" on each build. They'll work when you build from Xcode too.
 
CMake include commands to copy all needed assets from source directory into "bin" on each build. They'll work when you build from Xcode too.
  
−
'''Be aware you still need directories "Data", "Mp3" and "Maps" from Heroes 3 game assets in VCMI app data directory:'''
+
= Some useful debugging tips =
−
<pre>
 
−
~/Library/Application\ Support/vcmi/
 
−
</pre>
 
−
 
 
−
===== Some useful debugging tips =====
 
 
Anyone who might want to debug builds, but new to macOS could find following commands useful:
 
Anyone who might want to debug builds, but new to macOS could find following commands useful:
 
<pre>
 
<pre>
 
# To attach DMG file from command line use
 
# To attach DMG file from command line use
−
hdiutil attach vcmi-0.99.dmg
+
hdiutil attach vcmi-1.0.dmg
 
# Detach volume:
 
# Detach volume:
−
hdiutil detach /Volumes/vcmi-0.99
+
hdiutil detach /Volumes/vcmi-1.0
 
# To view dependency paths
 
# To view dependency paths
−
otool -L /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient
+
otool -L /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient
 
# To display load commands such as LC_RPATH  
 
# To display load commands such as LC_RPATH  
−
otool -l /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient
+
otool -l /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient
 
</pre>
 
</pre>
  
 
= Troubleshooting =
 
= Troubleshooting =
 
In case of troubles you can always consult our CI build scripts or contact the dev team via slack
 
In case of troubles you can always consult our CI build scripts or contact the dev team via slack
−
# While building '''FuzzyLite''' you may get the following error with the most recent clang: ([https://forum.vcmi.eu/t/cant-build-on-macos-sierra-10-12-6/4315/2 credit to SXX's answer on the forum])
 
−
<syntaxhighlight lang="bash">
 
−
/tmp/fuzzylite/fuzzylite/./fl/Operation.h:1044:24: error: passing an object that undergoes default argument promotion to 'va_start' has undefined behavior [-Werror,-Wvarargs]
 
−
va_start(args, first);
 
−
^
 
−
</syntaxhighlight>
 
−
 
−
For the time being, you could bypass it using older version of Xcode like 8.2.1 or adding <code>-Wno-varargs</code> compile option to '''AI/FuzzyLite/fuzzylite/CMakeLists.txt:'''
 
−
 
−
<syntaxhighlight lang="cmake">
 
−
if(NOT MSVC)
 
−
#TODO: Remove -Werror before release.
 
−
#Add Unix compilation flags
 
−
    set(CMAKE_CXX_FLAGS "-pedantic -Wall -Wextra -Werror -Wno-varargs ${CMAKE_CXX_FLAGS}")
 
−
</syntaxhighlight>
 

Revision as of 15:12, 15 September 2022

Requirements

  1. C++ toolchain, either of:
  2. CMake: brew install --cask cmake or get from https://cmake.org/download/
  3. (optional) Ninja: brew install ninja or get from https://github.com/ninja-build/ninja/releases

Obtaining source code

Clone https://github.com/vcmi/vcmi with submodules. Example for command line: 

git clone --recurse-submodules https://github.com/vcmi/vcmi.git

Obtaining dependencies

There're 2 ways to get dependencies automatically.

Conan package manager

That's what our CI uses.

  1. Install Conan
  2. Execute in Terminal: conan profile new default --detect
  3. Download prebuilt libraries from GitHub Releases:
    • if you're on an Intel Mac, download file intel.txz and unpack it to ~/.conan directory.
    • if you're on an ARM Mac, download file intel-cross-arm.txz and unpack it to ~/.conan directory. Then follow instructions how to build Qt host tools for ARM, on step 3 copy them to ~/.conan/data/qt/5.15.5/_/_/package/SOME_HASH/bin.
  4. In Terminal cd to the source code directory and run:
USE_CONAN_WITH_ALL_CONFIGS=1 conan install . --install-folder=conan-generated --no-imports --build=never --profile:build=default --profile:host=CI/conan/PROFILE

where conan-generated can be any directory you like (Conan helper files will appear there) and PROFILE must be replaced with:

  • if you're on an Intel Mac: macos-intel
  • if you're on an ARM Mac: macos-arm

Homebrew

  1. Install Homebrew
  2. Install dependencies: brew install boost ffmpeg@4 luajit minizip sdl2 sdl2_image sdl2_mixer sdl2_ttf tbb
  3. Install Qt dependency in either of the ways (note that you can skip this if you're not going to build Launcher):
    • brew install qt@5 for Qt 5 or brew install qt for Qt 6
    • using Qt Online Installer - choose Go open source

Preparing build environment

This applies only to Xcode-based toolchain. If xcrun -f clang prints errors, then use either of the following ways:

  • select an Xcode instance from Xcode application - Preferences - Locations - Command Line Tools
  • use xcode-select utility to set Xcode or Xcode Command Line Tools path: for example, sudo xcode-select -s /Library/Developer/CommandLineTools
  • set DEVELOPER_DIR environment variable pointing to Xcode or Xcode Command Line Tools path: for example, export DEVELOPER_DIR=/Applications/Xcode.app

Configuring project for building

Note that if you wish to use Qt Creator IDE, you should skip this step and configure respective variables inside the IDE.

  1. In Terminal cd to the source code directory
  2. Start assembling CMake invocation: type cmake -S . -B BUILD_DIR where BUILD_DIR can be any path, don't press Return
  3. Decide which CMake generator you want to use:
    • Makefiles: no extra option needed or pass -G 'Unix Makefiles'
    • Ninja (if you have installed it): pass -G Ninja
    • Xcode IDE (if you have installed it): pass -G Xcode
  4. If you picked Makefiles or Ninja, pick desired build type - either of Debug / RelWithDebInfo / Release / MinSizeRel - and pass it in CMAKE_BUILD_TYPE option, for example: -D CMAKE_BUILD_TYPE=Release. If you don't pass this option, RelWithDebInfo will be used.
  5. If you don't want to run tests, pass -D ENABLE_TEST=OFF
  6. If you don't want to build Launcher, pass -D ENABLE_LAUNCHER=OFF
  7. You can also pass -Wno-dev if you're not interested in CMake developer warnings
  8. Next step depends on the dependency manager you have picked:
    • Conan: pass -D CMAKE_TOOLCHAIN_FILE=conan-generated/conan_toolchain.cmake where conan-generated must be replaced with your name choice at step 4 of #Conan package manager
    • Homebrew: pass -D "CMAKE_PREFIX_PATH=$(brew --prefix ffmpeg@4)"
      • if you installed Qt 5 from Homebrew, append to the above option but before the closing quote: ;$(brew --prefix qt@5)
      • if you installed Qt from Online Installer, append to the above option but before the closing quote your path to Qt directory, for example: ;/Users/kambala/dev/Qt-libs/5.15.2/Clang64
      • example of what you should pass in the first case: -D "CMAKE_PREFIX_PATH=$(brew --prefix ffmpeg@4);$(brew --prefix qt@5)"
  9. If you're on an ARM Mac and using Conan, also pass: -D ENABLE_ERM=OFF -D ENABLE_LUA=OFF
  10. now press Return

Building project

You must also install game files to be able to run the built version, see Installation on macOS.

From Xcode IDE

Open VCMI.xcodeproj from the build directory, select vcmiclient scheme and hit Run (Cmd+R). To build Launcher, select vcmilauncher scheme instead.

From command line

cmake --build <path to build directory> --target vcmiclient

  • If using Makefiles generator, you'd want to utilize all your CPU cores by appending -- -j$(sysctl -n hw.ncpu) to the above
  • If using Xcode generator, you can also choose which configuration to build by appending --config <configuration name> to the above, for example: --config Debug

Packaging project into DMG file

After building, run cpack from the build directory. If using Xcode generator, also pass -C <configuration name> with the same configuration that you used to build the project.

Running VCMI

You can run VCMI from DMG, but it's will also work from your IDE be it Xcode or Qt Creator.

Alternatively you can run binaries directly from "bin" directory: 

BUILD_DIR/bin/vcmilauncher
BUILD_DIR/bin/vcmiclient
BUILD_DIR/bin/vcmiserver

CMake include commands to copy all needed assets from source directory into "bin" on each build. They'll work when you build from Xcode too.

Some useful debugging tips

Anyone who might want to debug builds, but new to macOS could find following commands useful: 

# To attach DMG file from command line use
hdiutil attach vcmi-1.0.dmg
# Detach volume:
hdiutil detach /Volumes/vcmi-1.0
# To view dependency paths
otool -L /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient
# To display load commands such as LC_RPATH 
otool -l /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient

Troubleshooting

In case of troubles you can always consult our CI build scripts or contact the dev team via slack

Retrieved from "https://wiki.vcmi.eu/index.php?title=How_to_build_VCMI_(macOS)&oldid=3431"