| The Go mobile subrepository adds support for mobile platforms (Android and iOS) and provides tools to build mobile applications. |
| |
| There are two strategies you can follow to include Go into your mobile stack: |
| |
| - Writing all-Go native mobile applications. |
| - Writing SDK applications by generating bindings from a Go package and invoke them from Java (on Android) and Objective-C (on iOS). |
| |
| This article will contain step-by-step guides to explain how to achieve |
| these strategies. |
| |
| - [Tools](#tools) |
| - [Native applications](#native-applications) |
| - [Building and deploying to Android](#building-and-deploying-to-android) |
| - [Building and deploying to iOS](#building-and-deploying-to-ios) |
| - [SDK applications](#sdk-applications-and-generating-bindings) |
| - [Building and deploying to Android](#building-and-deploying-to-android-1) |
| - [Building and deploying to iOS](#building-and-deploying-to-ios-1) |
| - [iOS Simulator](#ios-simulator) |
| |
| ## Tools |
| |
| Note: You need to have [Go 1.5 or above](https://golang.org/dl/) to install mobile tools. (Or at least Go 1.7.4 if using macOS Sierra) |
| |
| Go Mobile introduces a new tool, [gomobile](https://golang.org/x/mobile/cmd/gomobile), |
| to help you with the build and the binding process. |
| |
| On OS X, you will need to have |
| [Xcode Command Line Tools](https://developer.apple.com/downloads/) |
| installed. |
| |
| ``` |
| $ go get golang.org/x/mobile/cmd/gomobile |
| ``` |
| |
| (The following sections will help you how to use the gomobile tool.) |
| |
| ## Native applications |
| |
| The native category includes applications entirely written in Go. Currently, the |
| [golang.org/x/mobile](https://godoc.org/golang.org/x/mobile) |
| contains only a small set of packages that focus on: |
| |
| * App control and configuration |
| * OpenGL ES 2 bindings |
| * Asset management |
| * Event management |
| * Experimental packages include OpenAL bindings, audio, font, sprite and motion sensors |
| |
| There are various example native applications under [golang.org/x/mobile/example](https://golang.org/x/mobile/example). We will build and deploy the basic example both to an Android and iOS device. |
| |
| Grab the application. |
| |
| ``` |
| $ go get -d golang.org/x/mobile/example/basic |
| ``` |
| |
| ### Building and deploying to Android |
| |
| Run `gomobile build` to build an Android APK. |
| |
| ``` |
| $ gomobile build -target=android golang.org/x/mobile/example/basic |
| ``` |
| |
| Build command will build an APK named basic.apk. |
| |
| If an AndroidManifest.xml is defined in the package directory, it is added to the APK output. Otherwise, a default manifest is generated. |
| |
| If you have the [adb](http://developer.android.com/tools/help/adb.html) command installed on your machine, you can use `gomobile install` to build and push the APK to your mobile device. |
| |
| ``` |
| $ gomobile install golang.org/x/mobile/example/basic |
| ``` |
| |
| ### Building and deploying to iOS |
| Run `gomobile build` to build the package as an iOS application. |
| |
| Note: target=ios requires the host machine running OS X. You need to obtain a [signing identity and download provisioning profiles](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingCertificates/MaintainingCertificates.html) in order to continue. |
| |
| ``` |
| $ gomobile build -target=ios golang.org/x/mobile/example/basic |
| ``` |
| |
| The build command will build an application bundle, named `basic.app`. |
| |
| You can deploy .app files by dragging and dropping them to the device. |
| |
| * In Xcode, open Window > Devices. |
| * Select the physical device from the left pane. |
| * Drag and drop the .app file to "Installed Apps" section. |
| * Check the "Copy items if needed" option |
| |
|  |
| |
| Alternatively, you can deploy application bundles to your iOS device by using the [ios-deploy](https://github.com/phonegap/ios-deploy) utility command line tool. Use ios-deploy to push the application to your device. |
| |
| ``` |
| $ ios-deploy -b basic.app |
| ``` |
| |
| ## SDK applications and generating bindings |
| |
| In this category, we will show you how you can use a Go package in |
| your existing Android or iOS application. |
| |
| The advantages to following this strategy: |
| |
| * You can reuse a Go package from a mobile app without making significant changes to your existing application. |
| * In cases where you want to share a common code base between your Android and iOS application, you can write the common functionality once in Go and glue them to the platform-specific code by invoking the Go package through bindings. |
| |
| Current limitations are listed below. |
| |
| * Only a [subset of Go types](https://godoc.org/golang.org/x/mobile/cmd/gobind) are currently supported. |
| * Language bindings have a performance overhead. |
| * There are a few limitations on how the exported APIs should look due to the limitations of the target language. |
| |
| We will use the example package under [golang.org/x/mobile/example/bind/hello](https://golang.org/x/mobile/example/bind/hello) to generate bindings and invoke Greetings function from Java and Objective-C. |
| |
| Grab the example by running the command below. |
| |
| ``` |
| $ go get -d golang.org/x/mobile/example/bind/... |
| ``` |
| |
| ### Building and deploying to Android |
| |
| Note: Go Mobile runs on the same architectures as Go, which currently means ARM, ARM64, 386 and amd64 devices and emulators. Notably, Android on MIPS devices is not yet supported. |
| |
| * Launch Android Studio. |
| * File > Import Project... to import the reference project from $GOPATH/src/golang.org/x/mobile/example/bind/android. |
| |
|  |
| |
| * Run the following command to generate the [aar](https://developer.android.com/studio/projects/android-library.html) file that is suitable for importing into Android projects: |
| |
| ``` |
| $ gomobile bind -o app/hello.aar -target=android golang.org/x/mobile/example/bind/hello |
| ``` |
| |
| * Build and deploy the application to the device. |
| |
| The app module contains the main application that invokes the `hello.Greetings`. When the application is launched the text view is updated with the string returned value. |
| |
| If you are not using Android Studio, in order to work with bindings for Android, you need to have [Android SDK](https://developer.android.com/sdk/index.html#Other) installed and ANDROID_HOME environment variable set to the SDK path. You also need the [NDK](https://developer.android.com/ndk/) installed; the easiest way is to run the SDK command `sdkmanager ndk-bundle`. |
| |
| Alternatively, if you are not familiar with android development, and you do not wish to set up all the required environment (Android SDK, Gradle, etc), you can use this [Dockerfile](https://github.com/mpl/go4droid/blob/master/Dockerfile) to build the application in [docker](https://www.docker.com/) instead. |
| |
| ### Building and deploying to iOS |
| |
| Note: target=ios requires the host machine to be running OS X. |
| |
| ``` |
| $ cd $GOPATH/src/golang.org/x/mobile/example/bind |
| $ gomobile bind -target=ios golang.org/x/mobile/example/bind/hello |
| ``` |
| |
| Gomobile bind will generate a framework bundle called `Hello.framework`. Open the sample XCode project by running the command below. |
| |
| ``` |
| $ open ios/bind.xcodeproj |
| ``` |
| Drag and drop the `Hello.framework` bundle to the Xcode project. Check "Copy items if needed" if you need a different copy of the framework bundle within the Xcode otherwise. Otherwise, modifying the Go package source code and rerunning `gomobile bind` will update the hello.framework. |
| |
| |
| |
|  |
| |
| Your project layout should look like what's shown below. |
| |
|  |
| |
| Build and run it on the simulator or an actual device (Cmd+R). When the application launches, the label on the main view will be modified with the string returned from `GoHelloGreetings` which invokes the `hello.Greetings` function. |
| |
| Note that you can also invoke `GoHelloGreetings` from Swift by importing Hello. |
| |
| ```swift |
| @import Hello |
| // ... |
| let msg = Hello.GoHelloGreetings("gopher") |
| ``` |
| |
| #### iOS Simulator |
| |
| As of Go 1.5, only darwin/amd64 works on the iOS simulator. To use the simulator, you need to configure Xcode to only try to run 64-bit binaries. |
| |
| Xcode matches the bit width of the ARM binaries when running on the X86 simulator. That is, if you configure Xcode to build both 32-bit and 64-bit ARM binaries (the default), it will attempt to run 32-bit X86 binaries on the simulator, which will not work with Go today. Modify the Xcode build settings to only build 64-bit ARM binaries, and the simulator will run the amd64 binary. |
