The iOS module contains special build rules to create a C/C++/Objective C/Objective C++ iOS application from start to finish.

The ios module will automatically detect the appropriate compilers and set up some architecture-specific items.

Next, some combination of the following rule calls (and any others described below) are needed to build a full iOS .ipa for installation and distribution.

C.ActiveTarget sdltest ;
ios.BundleInfo : displayname : sdltest ;
ios.BundleInfo : bundleversion : 1.0 ;
ios.BundleInfo : uistatusbarhidden : true ;
 
C.Inherits : sdl2 ;
C.Application : sdltest.c ;
 
ios.ProvisionFile : test.mobileprovision ;
ios.CodeSign : "iPhone Developer" : "ios_development.cer:AppleIncRootCertificate.cer:AppleWWDRCA.cer:my_key.key:" ;
ios.Bundle ;
 
local bundlePath = [ ios.GetBundlePath ] ;
ios.Archive : $(bundlePath)/../package : : install webserver ;

An iOS build is initiated with a C.TOOLCHAIN of ios/CONFIG. This will build the application bundle, but it will not build the .ipa.

>jam C.TOOLCHAIN=ios/release

To bundle up an .ipa, build the archive:TARGET target.

>jam C.TOOLCHAIN=ios/release archive:TARGET

To install the .ipa, build the install:TARGET target. Be sure to have the ideviceinstaller.exe binaries in bin/PLATFORM/libimobiledevice/.

>jam C.TOOLCHAIN=ios/release install:TARGET

List of Rules

Rules

rule C.ios.FrameworkDirectories TARGET : DIRECTORIES

For the given project TARGET, assign the framework search DIRECTORIES to the current toolchain.

Parameters

TARGET	The target to assign the link `DIRECTORIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the framework search directories are made available globally.
DIRECTORIES	The list of framework search directories to apply. Absolute paths are used directly. Relative paths are local to . That is, they are relative to the subdirectory specified via SubDir.

C.ios.FrameworkDirectories MyGame : $(SUBDIR)/ExtraFrameworks ;

rule C.ios.LinkFrameworks TARGET : FRAMEWORKS

Links TARGET against the FRAMEWORKS specified. No dependencies are set, so changes to the framework will not be relinked.

Parameters

TARGET	The target to link `LIBRARIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
FRAMEWORKS	The list of frameworks to link. The frameworks are specified without an extension.

C.ios.LinkFrameworks MyGame : CoreFoundation ;

rule C.ios.WeakLinkFrameworks TARGET : FRAMEWORKS

Weak links TARGET against the FRAMEWORKS specified. No dependencies are set, so changes to the framework will not be relinked.

Parameters

TARGET	The target to link `LIBRARIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
FRAMEWORKS	The list of frameworks to link. The frameworks are specified without an extension.

C.ios.WeakLinkFrameworks MyGame : CoreMotion iAd AVFoundation ;

rule ios.Archive TARGET : OUTPUT_PATH : ITUNES_ARTWORK : OPTIONS

In order to output a final .ipa to be installed on an iOS device, ios.Archive must be called for the TARGET.

Parameters

TARGET	The target to convert to an `.ipa`. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
OUTPUT_PATH	The final resting place of the `.ipa`.
ITUNES_ARTWORK	The path to a `.jpg` to be used as the icon within iTunes.
OPTIONS	The list of options applied when building the `.ipa`.

install - Installs the .ipa on the USB-connected iOS device. Requires libimobiledevice installed installed within the jamplus/bin/libimobiledevice directory.

run - Installs and runs the application on the USB-connected iOS device. Requires libimobiledevice installed within the jamplus/bin/libimobiledevice directory.

ios.Archive : c:/ios-packages ;

rule ios.AssetCatalog TARGET : ASSET_CATALOG_PATH ;

Takes a provided asset catalog and builds it into its individual components. ios.AssetCatalog currently handles .appiconset, .imageset, and .launchimage directories.

Parameters

TARGET	The target to build the asset catalog for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
ASSET_CATALOG_PATH	The path to the `.xcassets` directory containing the asset catalog components.
DESTINATION_PATH	(optional) The output directory for the generated assets. Defaults to the bundle path.

ios.AssetCatalog : Unity-iPhone/Images.xcassets ;

rule ios.Bundle TARGET [ : TOOLCHAINS ]

In order to output an application bundle, the ios.Bundle rule must be called. If TOOLCHAINS is specified, those requested toolchain link targets are run through C.ios.Lipo, and all necessary components are bundled together.

ios.Bundle should be the last rule called in a sequence of rule calls describing the build of an iOS application.

Parameters

TARGET	The target to build. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
TOOLCHAINS	(optional) The list of toolchains used to build multiple architectures for the bundle. The default toolchain is used if none are specified.

# Build a bundle for the current target using the active toolchain.
ios.Bundle ;
 
# Build a bundle for the target MyGame using the active toolchain.
ios.Bundle MyGame ;

rule ios.BundleInfoArrayBegin TARGET : KEY

For the given bundle TARGET, begin an array entry within the Info.plist. Call rule ios.BundleInfoArrayEnd TARGET to complete the array entry.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEY	The key name of the array entry within the `Info.plist`.

ios.BundleInfoArrayBegin : UISupportedInterfaceOrientations ;
    ios.BundleInfoArrayString : UIInterfaceOrientationPortrait ;
    ios.BundleInfoArrayString : UIInterfaceOrientationPortraitUpsideDown ;
    ios.BundleInfoArrayString : UIInterfaceOrientationLandscapeRight ;
    ios.BundleInfoArrayString : UIInterfaceOrientationLandscapeLeft ;
ios.BundleInfoArrayEnd ;

rule ios.BundleInfoArrayBoolean TARGET : KEY : VALUE : NO_OVERRIDE

For the given bundle TARGET, assign KEY=VALUE as an array of booleans to the bundle's Info.plist.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEY	The key portion of the key/value pair to set within the `Info.plist`.
VALUE	The boolean array value portion of the key/value pair to set within the `Info.plist`.
NO_OVERRIDE	Pass `1` or `true` to not affect an already existing entry.

ios.BundleInfoArrayBoolean : MyBooleanArray : false true true false ;

rule ios.BundleInfoArrayDictBegin TARGET

For the given bundle TARGET, begin a array dict entry within the Info.plist. Call rule C.ios.BundleInfoArrayDictEnd TARGET to complete the dict entry.

Parameters

TARGET The bundle target to affect the Info.plist for. TARGET is optional if rule ActiveTarget TARGET has been specified.

ios.BundleInfoArrayDictBegin ;
    ios.BundleInfoString : UILaunchImageMinimumOSVersion : 7.0 ;
    ios.BundleInfoString : UILaunchImageName : LaunchImage-700 ;
    ios.BundleInfoString : UILaunchImageOrientation : Portrait ;
    ios.BundleInfoString : UILaunchImageSize : "{320, 480}" ;
ios.BundleInfoArrayDictEnd ;

rule C.ios.BundleInfoArrayDictEnd TARGET

For the given bundle TARGET, end the current array entry begun with rule ios.BundleInfoArrayDictBegin TARGET within the Info.plist.

Parameters

TARGET The bundle target to affect the Info.plist for. TARGET is optional if rule ActiveTarget TARGET has been specified.

ios.BundleInfoArrayDictBegin ;
    ios.BundleInfoString : UILaunchImageMinimumOSVersion : 7.0 ;
    ios.BundleInfoString : UILaunchImageName : LaunchImage-700 ;
    ios.BundleInfoString : UILaunchImageOrientation : Portrait ;
    ios.BundleInfoString : UILaunchImageSize : "{320, 480}" ;
ios.BundleInfoArrayDictEnd ;

rule ios.BundleInfoArrayEnd TARGET

For the given bundle TARGET, end the current array entry begun with rule ios.BundleInfoArrayBegin TARGET : KEY within the Info.plist.

Parameters

TARGET The bundle target to affect the Info.plist for. TARGET is optional if rule ActiveTarget TARGET has been specified.

ios.BundleInfoArrayBegin : UISupportedInterfaceOrientations ;
    ios.BundleInfoArrayString : UIInterfaceOrientationPortrait ;
    ios.BundleInfoArrayString : UIInterfaceOrientationPortraitUpsideDown ;
    ios.BundleInfoArrayString : UIInterfaceOrientationLandscapeRight ;
    ios.BundleInfoArrayString : UIInterfaceOrientationLandscapeLeft ;
ios.BundleInfoArrayEnd ;

rule ios.BundleInfoArrayInteger TARGET : KEY : VALUE : NO_OVERRIDE

For the given bundle TARGET, assign KEY=VALUE as an array of integers to the bundle's Info.plist.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEY	The key portion of the key/value pair to set within the `Info.plist`.
VALUE	The integer array value portion of the key/value pair to set within the `Info.plist`.
NO_OVERRIDE	Pass `1` or `true` to not affect an already existing entry.

ios.BundleInfoArrayInteger : MyIntegerArray : 0 1 2 3 4 5 ;

rule ios.BundleInfoArrayString TARGET : KEY : VALUE : NO_OVERRIDE

For the given bundle TARGET, assign KEY=VALUE as an array of strings to the bundle's Info.plist.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEY	The key portion of the key/value pair to set within the `Info.plist`.
VALUE	The string array value portion of the key/value pair to set within the `Info.plist`.
NO_OVERRIDE	Pass `1` or `true` to not affect an already existing entry.

ios.BundleInfoArrayString : UIRequiredDeviceCapabilities : armv7 armv8 ;

rule ios.BundleInfoBoolean TARGET : KEY : VALUE : NO_OVERRIDE

For the given bundle TARGET, assign KEY=VALUE as a boolean type to the bundle's Info.plist.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEY	The key portion of the key/value pair to set within the `Info.plist`.
VALUE	The value portion of the key/value pair to set within the `Info.plist`.
NO_OVERRIDE	Pass `1` or `true` to not affect an already existing entry.

ios.BundleInfoBoolean : LSRequiresIPhoneOS : true ;

rule ios.BundleInfoDictBegin TARGET : KEY

For the given bundle TARGET, begin a dict entry within the Info.plist. Call rule ios.BundleInfoDictEnd TARGET to complete the dict entry.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEY	The key name of the dict entry within the `Info.plist`.

ios.BundleInfoDictBegin : NSAppTransportSecurity ;
    ios.BundleInfoBoolean : NSAllowsArbitraryLoads : true ;
ios.BundleInfoDictEnd ;

rule ios.BundleInfoDictEnd TARGET

For the given bundle TARGET, end the current dict entry begun with rule ios.BundleInfoDictBegin TARGET : KEY within the Info.plist.

Parameters

TARGET The bundle target to affect the Info.plist for. TARGET is optional if rule ActiveTarget TARGET has been specified.

ios.BundleInfoDictBegin : NSAppTransportSecurity ;
    ios.BundleInfoBoolean : NSAllowsArbitraryLoads : true ;
ios.BundleInfoDictEnd ;

rule ios.BundleInfoInteger TARGET : KEY : VALUE : NO_OVERRIDE

For the given bundle TARGET, assign KEY=VALUE as an integer type to the bundle's Info.plist.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEY	The key portion of the key/value pair to set within the `Info.plist`.
VALUE	The value portion of the key/value pair to set within the `Info.plist`.
NO_OVERRIDE	Pass `1` or `true` to not affect an already existing entry.

ios.BundleInfoInteger : Unity_LoadingActivityIndicatorStyle : -1 ;

rule ios.BundleInfoString TARGET : KEY : VALUE : NO_OVERRIDE

For the given bundle TARGET, assign KEY=VALUE as string type to the bundle's Info.plist.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEY	The key portion of the key/value pair to set within the `Info.plist`.
VALUE	The value portion of the key/value pair to set within the `Info.plist`.
NO_OVERRIDE	Pass `1` or `true` to not affect an already existing entry.

ios.BundleInfoString : CFBundleName : simple ;

rule ios.BundleInfo TARGET : KEY : VALUE : NO_OVERRIDE

For the given bundle TARGET, assign KEY=VALUE as an array of strings to the bundle's Info.plist.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEY	The key portion of the key/value pair to set within the `Info.plist`.
VALUE	The value portion of the key/value pair to set within the `Info.plist`.
NO_OVERRIDE	Pass `1` or `true` to not affect an already existing entry.

info - Runs: ios.BundleInfoString : CFBundleGetInfoString : ;

iconfile - Runs: ios.BundleInfoString : CFBundleIconFile : ;

iconfiles - Runs: ios.BundleInfoArrayString : CFBundleIconFiles : ;

longversion - Runs: ios.BundleInfoString : CFBundleLongVersionString : ;

bundlename - Runs: ios.BundleInfoString : CFBundleName : ;

displayname - Runs: ios.BundleInfoString : CFBundleDisplayName : ;

executable - Runs: ios.BundleInfoString : CFBundleExecutable : ;

identifier - Runs: ios.BundleInfoString : CFBundleIdentifier : ;

shortversion - Runs: ios.BundleInfoString : CFShortVersionString : ;

bundleversion - Runs: ios.BundleInfoString : CFBundleVersion : ;

copyright - Runs: ios.BundleInfoString : NSHumanReadableCopyright : ;

mainnibfile - Runs: ios.BundleInfoString : NSMainNibFile : ;

supportedplatforms - Runs: ios.BundleInfoArrayString : CFBundleSupportedPlatforms : ;

minimumosversion - Runs: ios.BundleInfoString : MinimumOSVersion : ;

uidevicefamily - VALUE may be ipad or iphone. Runs: ios.BundleInfoArrayInteger : UIDeviceFamily : ;

uiprerenderedicon - Runs: ios.BundleInfoBoolean : UIPrerenderedIcon : ;

uistatusbarhidden - Runs: ios.BundleInfoBoolean : UIStatusBarHidden : ;

uiviewcontrollerbasedstatusbarappearance - Runs: ios.BundleInfoBoolean : UIViewControllerBasedStatusBarAppearance : ;

uiinterfaceorientation - VALUE may be portrait, portraitupsidedown, landscapeleft, landscaperight. Runs: ios.BundleInfoString : UIInterfaceOrientation : ;

uisupportedinterfaceorientations - VALUE may be portrait, portraitupsidedown, landscapeleft, landscaperight. Runs: ios.BundleInfoString : UISupportedInterfaceOrientations : ;

ios.BundleInfo : displayname : simple ;
ios.BundleInfo : bundlename : simple ;
ios.BundleInfo : bundleversion : 1.0 ;
ios.BundleInfo : uistatusbarhidden : true ;

rule ios.BundlePath TARGET : BUNDLE_PATH

For the given bundle TARGET, set the output location for the bundle via BUNDLE_PATH.

Parameters

TARGET	The target to set the bundle path against. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
BUNDLE_PATH	The output path for the bundle. If the path is absolute, it is used as is. If it is relative, the path will be rooted against `$(SUBDIR)`.

# Output the bundle to $(SUBDIR)/package.

ios.BundlePath : package ;

rule ios.CodeSign TARGET : SIGNING_IDENTITY : CERTIFICATE_CHAIN

For TARGET, use the provided SIGNING_IDENTITY and CERTIFICATE_CHAIN to sign the application bundle.

Parameters

TARGET	The target to code sign. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SIGNING_IDENTITY	The name on the certificate.
CERTIFICATE_CHAIN	This is only used with the iOS Build Environment for Windows. Generally, it is best to just use: `"ios_development.cer:AppleIncRootCertificate.cer:AppleWWDRCA.cer:my_key.key:"`

# This works on Mac and Windows.

ios.CodeSign : "iPhone Developer" : "ios_development.cer:AppleIncRootCertificate.cer:AppleWWDRCA.cer:my_key.key:" ;

rule ios.GetBundlePath TARGET

For the given bundle TARGET, return the output location for the bundle.

Parameters

TARGET The target to retrieve the bundle path for. TARGET is optional if rule ActiveTarget TARGET has been specified.

Returns: Returns the path the bundle will be output to.

Echo Bundle path - [ ios.GetBundlePath ] ;

rule ios.GetBundleTarget TARGET

For the given bundle TARGET, return the actual dependency graph target name of the bundle.

Parameters

TARGET The bundle target to affect the Info.plist for. TARGET is optional if rule ActiveTarget TARGET has been specified.

Returns: Returns the dependency graph target name representing the bundle's build.

Echo Bundle target - [ ios.GetBundleTarget ] ;

rule ios.InfoPListFile TARGET : SOURCE

For the given bundle TARGET, use the Info.plist file found at SOURCE. Run it through the rule C.ConfigureFile TARGET : DESTINATION : SOURCE : OPTIONS rule to expand any variables. Use the result in the TARGET bundle.

Parameters

TARGET	The bundle target to configure the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCE	The source `Info.plist` file.

local PRODUCT_NAME = "MyProductName" ;

ios.InfoPListFile : DefaultInfo.plist ;

rule C.ios.Lipo TARGET : LINK_TARGETS : OUTPUT_PATH

For the given TARGET, take the LINK_TARGETS, run lipo, and output the end result at OUTPUT_PATH.

This rule does not need to be called if using rule ios.Bundle TARGET [ : TOOLCHAINS ].

Parameters

TARGET	The target to perform the Lipo operation on. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
LINK_TARGETS	A list of link targets returned from rule C.Application TARGET : SOURCES [ : OPTIONS ], rule C.Library TARGET : SOURCES [ : OPTIONS ], or rule C.GetLinkTargets TARGET : TOOLCHAIN_SPEC.
OUTPUT_PATH	The output location for the Lipo'ed target.

local linkTargets ;
local toolchain ;
for toolchain in $(TOOLCHAINS) {
    linkTargets += [ C.GetLinkTargets $(TARGET) : $(toolchain) ] ;
}
C.ios.Lipo $(TARGET) : $(linkTargets) : $(bundlePath) ;

rule ios.MergeInfoPList TARGET : SOURCE

For the given bundle TARGET, merge the Info.plist-style file found at SOURCE into the main Info.plist.

Parameters

TARGET	The bundle target to affect the `Info.plist` for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCE	The source file to merge into the current generated `Info.plist`.

# Merge in DefaultInfo.plist the disk first and then assign some overrides.
ios.MergeInfoPList : DefaultInfo.plist ;
ios.BundleInfo : displayname : simple ;
ios.BundleInfo : bundlename : simple ;
ios.BundleInfo : bundleversion : 1.0 ;
ios.BundleInfo : uistatusbarhidden : true ;

rule ios.MinimumOSVersion TARGET : SDK_VERSION_MIN

Sets the minimum iOS version for the TARGET.

Parameters

TARGET	The target to assign a minimum OS version to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SDK_VERSION_MIN	The minimum OS version allowable in the format `major.minor`.

ios.MinimumOSVersion MyGame : 7.0 ;

rule ios.ProvisionFile TARGET : FILENAME

For TARGET, uses the specified .mobileprovision file at FILENAME as the bundle's embedded.mobileprovision.

Parameters

TARGET	The target to use the `.mobileprovision` file for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
FILENAME	The filename of the `.mobileprovision` file. If the filename is a relative path, it becomes rooted against `$(SUBDIR)`.

ios.ProvisionFile : test.mobileprovision ;

rule ios.Provision TARGET : PROFILE_ID

For TARGET, uses the specified PROFILE_ID to look up a matching .mobileprovision file from $(HOME)/Library/MobileDevice/Provisioning Profiles on the Mac. This rule does not work on Windows.

In general, store your application's .mobileprovision file with the application and use rule ios.ProvisionFile TARGET : FILENAME instead.

Parameters

TARGET	The target to assign the found `.mobileprovision` file. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
PROFILE_ID	The profile name.

# No example at this time.

rule ios.SDK SDK_VERSION

Sets the iOS SDK_VERSION for the toolchain. Call this before any other ios.* rules.

Parameters

SDK_VERSION Defaults to 9.3.

ios.SDK 9.3 ;

rule ios.Storyboards TARGET : LANGUAGE_DIRECTORY [ : STORYBOARD_FILES ]

Compiles a directory of storyboards.

Parameters

TARGET	The target to build the storyboards for. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
LANGUAGE_DIRECTORY	The path to the (generally) `Base.lproj` directory containing the `.storyboard` files.
STORYBOARD_FILES	(optional) The names of the launch image storyboard and the main storyboard, generally `LaunchImage` and `Main`. Automatically adds them to the `Info.plist`.

ios.Storyboards : $(SUBDIR)/Base.lproj : LaunchImage Main ;

rule ios.WebServer TARGET

After ios.Archive, launch a secure webserver for TARGET to install the .ipa onto the device.

Parameters

TARGET The target to launch a webserver for. TARGET is optional if rule ActiveTarget TARGET has been specified.

ios.WebServer ;