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

From VCMI Project Wiki
Jump to: navigation, search
(Created page with "placeholder")
 
Line 1: Line 1:
placeholder
+
== Requirements ==
 +
# '''macOS'''
 +
# Xcode: https://developer.apple.com/xcode/
 +
# CMake 3.21+: <code>brew install --cask cmake</code> or get from https://cmake.org/download/
 +
 
 +
== Obtaining dependencies ==
 +
Follow instructions at https://github.com/kambala-decapitator/vcmi-ios-depends
 +
 
 +
== Configuring project ==
 +
Only Xcode generator is supported!
 +
 
 +
As a minimum, you must pass the following variables to CMake:
 +
 
 +
* <code>BUNDLE_IDENTIFIER_PREFIX</code>: unique bundle identifier prefix, something like <code>com.MY-NAME</code>
 +
* <code>CMAKE_PREFIX_PATH</code>: path to the downloaded dependencies, e.g. <code>~/Downloads/vcmi-ios-depends/build/iphoneos</code>
 +
 
 +
There're two [https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html CMake presets]: for device and for simulator, named <code>ios-device</code> and <code>ios-simulator</code> respectively. You can also create your local "user preset" to avoid typing variables each time, see example [https://gist.github.com/kambala-decapitator/59438030c34b53aed7d3895aaa48b718 here].
 +
 
 +
Open terminal and <code>cd</code> to the directory with source code. Configuration example for device:
 +
<nowiki>cmake --preset ios-device \
 +
  -D BUNDLE_IDENTIFIER_PREFIX=com.MY-NAME \
 +
  -D CMAKE_PREFIX_PATH=~/Downloads/vcmi-ios-depends/build/iphoneos</nowiki>
 +
 
 +
By default build directory containing Xcode project will appear at <code>../build-ios-device</code>, but you can change it with <code>-B</code> option.
 +
 
 +
=== 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 <code>VCMI</code> with blue icon on the very top in the left panel with files), select <code>vcmiclient</code> target, open <code>Signing & Capabilities</code> tab and select yout team. Now you can copy the value from <code>Build Settings</code> tab - <code>DEVELOPMENT_TEAM</code> variable (paste it in the Filter field on the right) - click the greenish value - Other... - copy. Now you can pass it in <code>CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM</code> 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 <code>CMAKE_XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY</code> and <code>CMAKE_XCODE_ATTRIBUTE_PROVISIONING_PROFILE_SPECIFIER</code> variables instead. In this case you must also pass
 +
 
 +
<code>-D CMAKE_XCODE_ATTRIBUTE_CODE_SIGN_STYLE=Manual</code>.
 +
 
 +
== Building project ==
 +
 
 +
=== From Xcode IDE ===
 +
Open <code>VCMI.xcodeproj</code> from the build directory, select <code>vcmiclient</code> 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]].
 +
 
 +
=== From command line ===
 +
<code>cmake --build <path to build directory> --target vcmiclient -- -quiet</code>
 +
 
 +
You can pass additional xcodebuild options after the <code>--</code>. Here <code>-quiet</code> is passed to reduce amount of output.
 +
 
 +
Alternatively, you can invoke <code>xcodebuild</code> directly.
 +
 
 +
There's also <code>ios-release</code> configure and build preset that is used to create release build on CI.
 +
 
 +
== Creating ipa file for distribution ==
 +
Invoke <code>cpack</code> after building:
 +
 
 +
<code>cpack -C Release</code>
 +
 
 +
This will generate zip file, you need to change its extension to <code>ipa</code> manually or use [https://github.com/vcmi/vcmi/blob/develop/ios/zip2ipa.sh simple script] that we have in the repository at <code>ios/zip2ipa.sh</code>.

Revision as of 11:22, 17 August 2022

Requirements

  1. macOS
  2. Xcode: https://developer.apple.com/xcode/
  3. CMake 3.21+: brew install --cask cmake or get from https://cmake.org/download/

Obtaining dependencies

Follow instructions at https://github.com/kambala-decapitator/vcmi-ios-depends

Configuring project

Only Xcode generator is supported!

As a minimum, you must pass the following variables to CMake:

  • BUNDLE_IDENTIFIER_PREFIX: unique bundle identifier prefix, something like com.MY-NAME
  • CMAKE_PREFIX_PATH: path to the downloaded dependencies, e.g. ~/Downloads/vcmi-ios-depends/build/iphoneos

There're two CMake presets: for device and for simulator, named ios-device and 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:

cmake --preset ios-device \
  -D BUNDLE_IDENTIFIER_PREFIX=com.MY-NAME \
  -D CMAKE_PREFIX_PATH=~/Downloads/vcmi-ios-depends/build/iphoneos

By default build directory containing Xcode project will appear at ../build-ios-device, but you can change it with -B option.

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_CODE_SIGN_IDENTITY and CMAKE_XCODE_ATTRIBUTE_PROVISIONING_PROFILE_SPECIFIER variables instead. In this case you must also pass

-D CMAKE_XCODE_ATTRIBUTE_CODE_SIGN_STYLE=Manual.

Building project

From Xcode IDE

Open 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.

From command line

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

You can pass additional xcodebuild options after the --. Here -quiet is passed to reduce amount of output.

Alternatively, you can invoke xcodebuild directly.

There's also ios-release configure and build preset that is used to create release build on CI.

Creating ipa file for distribution

Invoke 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 ios/zip2ipa.sh.