ios

README

Go on iOS
=========

For details on developing Go for iOS on macOS, see the documentation in the mobile
subrepository:

    https://github.com/golang/mobile

It is necessary to set up the environment before running tests or programs directly on a
device.

First make sure you have a valid developer certificate and have setup your device properly
to run apps signed by your developer certificate. Then install the libimobiledevice and
ideviceinstaller tools from https://www.libimobiledevice.org/. Use the HEAD versions from
source; the stable versions have bugs that prevents the Go exec wrapper to install and run
apps.

Second, the Go exec wrapper must be told the developer account signing identity, the team
id and a provisioned bundle id to use. They're specified with the environment variables
GOIOS_DEV_ID, GOIOS_TEAM_ID and GOIOS_APP_ID. The detect.go program in this directory will
attempt to auto-detect suitable values. Run it as

	go run detect.go

which will output something similar to

	export GOIOS_DEV_ID="iPhone Developer: xxx@yyy.zzz (XXXXXXXX)"
	export GOIOS_APP_ID=YYYYYYYY.some.bundle.id
	export GOIOS_TEAM_ID=ZZZZZZZZ

If you have multiple devices connected, specify the device UDID with the GOIOS_DEVICE_ID
variable. Use `idevice_id -l` to list all available UDIDs.

Finally, to run the standard library tests, run iostest.bash with GOARCH set. For example,

	GOARCH=arm64 ./iostest.bash

To use the go tool directly to run programs and tests, put $GOROOT/bin into PATH to ensure
the go_darwin_$GOARCH_exec wrapper is found. For example, to run the archive/tar tests

	export PATH=$GOROOT/bin:$PATH
	GOARCH=arm64 go test archive/tar

Note that the go_darwin_$GOARCH_exec wrapper uninstalls any existing app identified by
the bundle id before installing a new app. If the uninstalled app is the last app by
the developer identity, the device might also remove the permission to run apps from
that developer, and the exec wrapper will fail to install the new app. To avoid that,
install another app with the same developer identity but with a different bundle id.
That way, the permission to install apps is held on to while the primary app is
uninstalled.

Documentation

Overview

This program can be used as go_darwin_arm_exec by the Go tool. It executes binaries on an iOS device using the XCode toolchain and the ios-deploy program: https://github.com/phonegap/ios-deploy

This script supports an extra flag, -lldb, that pauses execution just before the main program begins and allows the user to control the remote lldb session. This flag is appended to the end of the script's arguments and is not passed through to the underlying binary.

This script requires that three environment variables be set:

GOIOS_DEV_ID: The codesigning developer id or certificate identifier
GOIOS_APP_ID: The provisioning app id prefix. Must support wildcard app ids.
GOIOS_TEAM_ID: The team id that owns the app id prefix.

$GOROOT/misc/ios contains a script, detect.go, that attempts to autodetect these.