@@ -1,3 +1,11 @@
1+# Table of contents
2+- [Installation](#installation)
3+- [Building](#building)
4+- [Deploying](#deploying)
5+- [Mobile](#mobile)
6+ - [iOS](#ios)
7+ - [Android](#android)
8+
19## Installation
2101. Install or update to nix 2.x
3111. Set up nix caches
@@ -109,3 +117,124 @@ cd ~/code/myapp-deploy
109117ob deploy update
110118ob deploy push
111119```
120+
121+## Mobile
122+Until Obelisk offers a `ob deploy` equivalent for mobile apps, you are recommended to do it manually as follows.
123+
124+### iOS
125+
126+#### First time setup
127+Development on iOS requires a computer running macOS and an iOS developer account.
128+
129+##### iPhone
130+1. Connect the iPhone on which you'd like to run builds - this will open up iTunes.
131+1. Click accept to authorize on both the computer and the iPhone.
132+
133+##### Xcode
134+1. Install Xcode 8.2 (contains iOS SDK 10.2).
135+These versions will work out of the box but iOS SDKs prior to 11.3 should also work. You can choose another installed version in `default.nix`
136+More recent Xcodes should also work, as long as one of the SDKs mentioned above has been used.
137+To add another SDK to your current Xcode, [download](https://developer.apple.com/download/more/) the corresponding Xcode, extract it and copy its SDK folder next to the installed one, e.g.
138+```
139+open -W Xcode_9.2.xip
140+sudo cp -R Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS11.2.sdk
141+```
142+1. Open Xcode once so that it runs its post install tool setup.
143+
144+You can verify that you have correct versions by running
145+```
146+xcodebuild -showsdks
147+```
148+
149+##### Certificates
150+Now you need to inform Apple of your development devices and permissions by
151+adding credentials to the correct provisioning profile via the Apple Developer
152+portal.
153+
154+1. Open up XCode and go to Preferences - Accounts. Select the organization
155+Member role, click Manage Certificates, and add an iOS Development
156+certificate.
157+1. Go to [developer portal - devices](https://developer.apple.com/account/ios/device/) and add your device.
158+To find your device's UDID, select it in iTunes and click the serial number.
159+1. Go to [developer portal - development profiles](https://developer.apple.com/account/ios/profile/limited).
160+Create a development profile and add your certificate and device.
161+Click "Generate" and then download and open the profile.
162+
163+#### Building
164+1. In your project's `default.nix` set values for `ios.bundleIdentifier` and `ios.bundleName`.
165+Ensure that `bundleIdentifier` matches the App ID of the development profile, or that you are using a wildcard profile.
166+1. Run `nix-build -A ios.frontend -o result-ios` to build the app. Find it at `result-ios/frontend.app`
167+
168+#### Deploying
169+1. Connect the registered iPhone.
170+1. Find your Apple Team ID in the [developer portal](https://developer.apple.com/account/#/membership).
171+1. Run the deploy command with your Team ID:
172+```
173+ios-result/bin/deploy [TEAM_ID]
174+# or in debug mode via lldb:
175+ios-result/bin/deploy [TEAM_ID] -d
176+```
177+
178+#### Packaging
179+1. Go to [developer portal - distribution profiles](https://developer.apple.com/account/ios/profile/production).
180+Create and download a distribution profile.
181+1. Run the package script with your TEAM ID and your distribution profile to create a `.ipa`:
182+```
183+ios-result/bin/package [TEAM_ID] /path/to/output/.ipa /path/to/profile/file
184+```
185+
186+#### Debugging
187+It's also possible to inspect iOS WkWebView apps once they are installed in the iPhone:
188+1. On the desktop, go to Safari > Preferences > Advanced and enable Develop menu.
189+1. On the iPhone go to Settings > Safari > Advanced and enable Web Inspector.
190+1. Open the app on the iPhone while it is connected to the desktop.
191+1. In the desktop's Safari Develop menu, you should see your iPhone. Select the screen under the name of the app.
192+
193+### Android
194+
195+1. In your project's `default.nix` set a suitable value for `android.applicationId` and `android.displayName`.
196+1. Run `nix-build -A android.frontend -o result-android` to build the Android app.
197+1. A debug version of the app should be generated at `result-android/android-app-debug.apk`
198+
199+Now deploy the built apk file to your Android device:
200+
201+1. Enable *USB debugging* in your Android device ([instructions here](https://developer.android.com/studio/debug/dev-options))
202+1. Connect the device using USB (be sure to confirm any security prompts on the device)
203+1. Run the deploy script: `result-android/bin/deploy`
204+
205+This should copy over and install the application on your device (if you see a "*signatures do not match*" error, simply uninstall the previous app from the device before retrying the deploy). The name of the installed application will be what you have specified for `android.displayName` in the `default.nix`.
206+
207+#### Releasing to Play Store
208+
209+##### Configure signing
210+
211+The previous section would have generated a debug version of the app. In order to build a release version you will need to sign your app. Obelisk can automatically sign the app during build if you provide it with your keystore file in `default.nix`.
212+
213+First, if you do not already have a keystore, create it as follows (for more information, see the [Android documentation](https://developer.android.com/studio/publish/app-signing#signing-manually)):
214+
215+```
216+nix-shell -p androidenv.platformTools --run "keytool -genkey -v -keystore myandroidkey.jks -keyalg RSA -keysize 2048 -validity 10000 -alias myandroidalias"
217+```
218+
219+(Besure to give an appropriate keystore filename and key alias string above.)
220+
221+The `keytool` command will ask you for some details, including a keystore password and a key password (we will use these passwords further below). It will now have created a `myandroidkey.jks` file under the current directory. Move that to somewhere safe, and note down its full path.
222+
223+Now edit your project's `default.nix` and tell Obelisk of your app's keystore file. Your `default.nix` should look like this after the edit:
224+
225+```nix
226+ ...
227+ android.applicationId = "com.example.myapp";
228+ android.displayName = "My App";
229+ android.releaseKey =
230+ { storeFile = /path/to/myandroidkey.jks;
231+ storePassword = "abcd1234";
232+ keyAlias = "myandroidalias";
233+ keyPassword = "abcd1234";
234+ };
235+ ...
236+```
237+
238+##### Build a release version
239+
240+After having configured signing for your app, you may proceed to build a release version of the app. This is no different to how you build the non-release version, so consult the section [Android](#android) further above for exact instructions on building and deploying to your device.