diff --git a/Mobile.md b/Mobile.md new file mode 100644 index 00000000..02ec3594 --- /dev/null +++ b/Mobile.md @@ -0,0 +1,186 @@ +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 + +![Deploying app bundle](http://i.imgur.com/fRbQ0EQ.png) + +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. + +![Android Studio](http://i.imgur.com/RhNCnnH.png) + +* 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. + + + +![Drag and drop Hello.framework](http://i.imgur.com/u88CxN9.png) + +Your project layout should look like what's shown below. + +![Xcode project layout with Hello.framework](http://i.imgur.com/JhcSKwC.png) + +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.