This page is for those who intend to modify Tangram ES itself, not just use it in another application.
When building and running the demo application on an iOS device, you will need to set the "App ID" and "Development Team" values in the Xcode project in order to sign the application package. Apple mandates that an App ID can only be used by one Development Team. This is a good security practice, but it means that the demo application cannot include one App ID for everyone to use. When the Developer Team and App ID are set from the Xcode UI they become included in the project file. This can be disruptive to a git workflow because git will show the Xcode project file as modified.
To allow you build the demo with a clean source tree, the demo application project is configured to read local settings like your App ID and Development Team from a xcconfig file located at platforms/ios/demo/Local.xcconfig. The .gitignore in this folder configures git to ignore this file, so you can add your personal code signing settings here while keeping your git status clean. The CMake script for the iOS target initializes a template for this file, if it does not already exist. Set the DEVELOPMENT_TEAM value to your Development Team (which should look something like AB1CDE2F3G) and set the PRODUCT_BUNDLE_IDENTIFIER to your App ID (some unique identifier, usually of the form com.my.namespace.TangramDemo).
You can find your personal Development Team in the Keychain Access app. Find your iOS code signing identity in the "Certificates" category, right-click it and select "Get Info". Your Development Team is the value in the "Organizational Unit" field.
The Xcode workspace that contains both the demo app project and the framework project uses specific build location settings to ensure that build products for both the framework and demo app are placed in the right locations and are able to build together successfully. If you try to open the demo project separately and build it, the build will probably fail or link against a "stale" version of the framework.
We use an Xcode workspace to group the framework and demo projects together so that the framework can be built and debugged along with the demo app as a dependency. The framework project is most convenient to generate through CMake, since it is comprised mostly of the cross-platform C++ core library and its dependencies. The demo app project could also be generated through CMake, but configuring an iOS application with an embedded, code-signed binary framework is complex and fragile with CMake. Furthermore, unlike the core library the demo app has no need for a platform-agnostic build configuration. Therefore it is simplest to use a "hand made" Xcode project to build the demo app. The Xcode workspace allows the demo project to reference the CMake-generated framework project as a dependency. This makes running and debugging both projects together very easy!
Building a project through an Xcode workspace behaves a little differently from building the project on its own (see Apple's documentation for a thorough explanation). By default, a workspace overrides the build output locations of the individual projects in it, placing the output for all projects into a separate, shared build folder instead. This causes build errors for projects generated by CMake. CMake hard-codes the absolute paths of build products like library dependencies into the Xcode project. Link flags in the project have those same paths hard-coded as well, so if build outputs are relocated by an Xcode workspace the link commands will fail to find the libraries at the paths in the project.
To overcome this, we use a workspace setting that keeps build products in the locations specified by their original projects. This can be set in Xcode by opening a workspace, then navigating to File > Workspace Settings in the menu bar, then clicking Advanced..., then choosing the Legacy option.
This setting is stored per-user in the workspace data, located in Tangram.xcworkspace/xcuserdata/$USER.xcuserdatad/WorkspaceSettings.xcsettings where $USER is the current user name. Since this path is different for every user, we cannot track this file in git. Instead, we keep a file that stores these settings in platforms/ios/WorkspaceSettings.xcsettings and we copy this file into the appropriate location for each user as a step in the make cmake-ios rule in our Makefile.
We use CMake to specify build configurations in Tangram ES because of its portability across platforms. However when setting up builds targeting iOS, we can take advantage of the fact that we will only use CMake to generate Xcode projects. CMake configures the build settings on a target in a generated XCode project from the target PROPERTIES in CMake. These settings are string-based key-value pairs. In an open Xcode project, you can use the Quick Help Inspector on the right-side panel to determine the key name for any build setting. This key is used in the text-file representation of the Xcode project data (a pbxproj file).
In CMake you can set the value of these build settings by setting a property on a library or executable target with the name XCODE_ATTRIBUTE_<BUILD_SETTING_NAME> (this pattern is documented in the CMake manual here). For example, to set the build setting from the image above that is declared as IPHONEOS_DEPLOYMENT_TARGET for a target named myIosTarget, your CMake file should contain:
set_target_properties(myIosTarget PROPERTIES XCODE_ATTRIBUTE_IPHONEOS_DEPLOYMENT_TARGET "9.3")Some build configurations are more easily applied through Xcode settings, and some are only relevant when Xcode is the target IDE.