New in 10.2.3: CMake Support for iOS and Android

by Mar 19, 2018

We've introduced some great new features for C++Builder in 10.2.3.  Last week, I wrote about CMake support for our compilers. That post covered what CMake is, and how to use it for Windows, both Win32 and Win64.  If you haven't read it, please do; it's worth reading before this post.

Today I'd like to cover using CMake for mobile, iOS and Android.  This is both how to invoke CMake, and how to write mobile-specific information in a CMakeLists.txt file.

CMake for iOS and Android

When building with CMake and targeting Windows, you specify that you want to use our Win32 or Win64 C and C++ compilers. Once CMake knows what compiler you want to use, it takes it from there:

.
-- Win32:
cmake -DCMAKE_C_COMPILER=bcc32x.exe -DCMAKE_CXX_COMPILER=bcc32x.exe -G Ninja

-- Win64:
cmake -DCMAKE_C_COMPILER=bcc64.exe -DCMAKE_CXX_COMPILER=bcc64.exe -G Ninja

This is because you are building and targeting the same platform.  You are building on Windows, and targeting Windows.  But for iOS32, iOS64, and Android, you are building on a different platform than you are targeting: that is, you are cross-compiling.

To cross-compile, instead of specifying the compiler you use, you specify a toolchain.  This is a cmake file that tells CMake how to use the compilers and for our mobile platforms, contains full cross-compilation information.  These toolchain files also set up extra deployment options – things like the splash screen images – that are specific to each platform.

Our cross-compile toolchain files share the same name as the compiler they use, eg bccaarm (our compiler) is bccaarm.cmake.  Here are the command lines to use:

iOS32:

.
cmake -DCMAKE_TOOLCHAIN_FILE="<BDS>cmakebccios32.cmake" -G Ninja

iOS64:

.
cmake -DCMAKE_TOOLCHAIN_FILE="<BDS>cmakebccios64.cmake" -G Ninja

Android:

.
cmake -DCMAKE_TOOLCHAIN_FILE="<BDS>cmakebccaarm.cmake" -G Ninja

That's even less to type than you use for Windows!

Don't forget, this assumes that you're invoking CMake from the folder where you CMakeLists.txt file is located.  If it's somewhere else, you can specify the path at the end of the command line, eg "… -G Ninja .." or "… -G Ninja c:mypath".

Mobile-specific info in a CMakeLists.txt

Mobile targets are unlike Windows in that you can deploy your project to a mobile device, and that includes deploying a number of files that end up in the app bundle or package.  You do this through paserver as normal, so make sure paserver is installed and you can deploy through the IDE before you try on the command line.

We have a number of macros and variables you can use to tell CMake mobile-specific things, which include:

iOS:

  • Macros: The device family, eg iPhone and/or iPad; supported device orientations; background mode; and additional files that need to be deployed.  These are all the equivalents of settings in your Project Options.
  • Variables: The app name, SDK, certificate, provisioning profile, a large number of items that go into the info.plist file such as the bundle name, camera usage, etc etc; arbitrary info.plist options; and the icon and image files.  

Android:

  • Macros: jar files to add to classes.dex; permissions; and additional files to deploy.
  • Variables: project location, KeyStore info (password, alias, etc); services; manifest information such as the label, version, install location, etc etc; splash images; style; icon and image files; are more. 

Our documentation has a full list.  You can use all the macros and variables; some variables have preset fixed values which you can read in order to make target-specific configuration inside your CMakeLists.txt file.

Configuring CMakeLists.txt based on target

A CMakeLists.txt file is a generic project description, but you will want to have info in it that specifies, say, the Android manifest information that is used when targeting Android.  How do you do this?

The answer is to add an if statement based on the value of the EMBT_TARGET variable.  This is set for the platform, so for Android you would check

.
if(EMBT_TARGET STREQUAL Android)
  // ... Android-specific CMake config here
endif()

EMBT_TARGET can be:

  • "Android"
  • "iOS32"
  • "iOS64"
  • "Windows"

And you can use this to add info for each platform to your config.

Summary

That's it!  The core points are:

  • Specify the toolchain file to use when building for iOS or Android
  • In your CMakeLists.txt file, check EMBT_TARGET and use that to gate target-specific configuration, such as deployment or manifest/info.plist info

Next up in this series on CMake: using Ninja!