How to build VCMI (iOS)
- Xcode: https://developer.apple.com/xcode/
- CMake 3.21+:
brew install --cask cmakeor get from https://cmake.org/download/
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
There're 2 ways to get prebuilt dependencies:
- Conan package manager - recommended. Note that the link points to the cutting-edge state in
developbranch, for the latest release check the same document in the master branch.
- legacy manually built libraries - can be used if you have Xcode 11/12 or to build for simulator / armv7 device
Only Xcode generator (
-G Xcode) is supported!
As a minimum, you must pass the following variables to CMake:
BUNDLE_IDENTIFIER_PREFIX: unique bundle identifier prefix, something like
- (if using legacy dependencies)
CMAKE_PREFIX_PATH: path to the downloaded dependencies, e.g.
There're a few CMake presets: for device (Conan and legacy dependencies) and for simulator, named
ios-simulator respectively. You can also create your local "user preset" to avoid typing variables each time, see example here.
Open terminal and
cd to the directory with source code. Configuration example for device with Conan:
cmake --preset ios-device-conan \ -D BUNDLE_IDENTIFIER_PREFIX=com.MY-NAME
By default build directory containing Xcode project will appear at
../build-ios-device-conan, but you can change it with
Building for device
To be able to build for iOS device, you must also specify codesigning settings. If you don't know your development team ID, open the generated Xcode project, open project settings (click VCMI with blue icon on the very top in the left panel with files), select vcmiclient target, open Signing & Capabilities tab and select yout team. Now you can copy the value from Build Settings tab -
DEVELOPMENT_TEAM variable (paste it in the Filter field on the right) - click the greenish value - Other... - copy. Now you can pass it in
CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM variable when configuring the project to avoid selecting the team manually every time CMake re-generates the project.
Advanced users who know exact private key and provisioning profile to sign with, can use
CMAKE_XCODE_ATTRIBUTE_PROVISIONING_PROFILE_SPECIFIER variables instead. In this case you must also pass
From Xcode IDE
VCMI.xcodeproj from the build directory, select
vcmiclient scheme (the only one with nice icon) with your destination device/simulator and hit Run (Cmd+R).
You must also install game files, see Installation on iOS. But this is not necessary if you are going to run on simulator, as it is able to use game data from your Mac located at
From command line
cmake --build <path to build directory> --target vcmiclient -- -quiet
You can pass additional xcodebuild options after the
-quiet is passed to reduce amount of output.
Alternatively, you can invoke
ios-release-conan configure and build preset that is used to create release build on CI.
Creating ipa file for distribution
cpack after building:
cpack -C Release
This will generate zip file, you need to change its extension to
ipa manually or use simple script that we have in the repository at