pyrox.dev
1# iOS {#ios}
2
3This component is basically a wrapper/workaround that makes it possible to
4expose an Xcode installation as a Nix package by means of symlinking to the
5relevant executables on the host system.
6
7Since Xcode can't be packaged with Nix, nor we can publish it as a Nix package
8(because of its license) this is basically the only integration strategy
9making it possible to do iOS application builds that integrate with other
10components of the Nix ecosystem
11
12The primary objective of this project is to use the Nix expression language to
13specify how iOS apps can be built from source code, and to automatically spawn
14iOS simulator instances for testing.
15
16This component also makes it possible to use [Hydra](https://nixos.org/hydra),
17the Nix-based continuous integration server to regularly build iOS apps and to
18do wireless ad-hoc installations of enterprise IPAs on iOS devices through
19Hydra.
20
21The Xcode build environment implements a number of features.
22
23Deploying a proxy component wrapper exposing Xcode
24--------------------------------------------------
25The first use case is deploying a Nix package that provides symlinks to the Xcode
26installation on the host system. This package can be used as a build input to
27any build function implemented in the Nix expression language that requires
28Xcode.
29
30```nix
31let
32 pkgs = import <nixpkgs> {};
33
34 xcodeenv = import ./xcodeenv {
35 inherit (pkgs) stdenv;
36 };
37in
38xcodeenv.composeXcodeWrapper {
39 version = "9.2";
40 xcodeBaseDir = "/Applications/Xcode.app";
41}
42```
43
44By deploying the above expression with `nix-build` and inspecting its content
45you will notice that several Xcode-related executables are exposed as a Nix
46package:
47
48```bash
49$ ls result/bin
50lrwxr-xr-x 1 sander staff 94 1 jan 1970 Simulator -> /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/Contents/MacOS/Simulator
51lrwxr-xr-x 1 sander staff 17 1 jan 1970 codesign -> /usr/bin/codesign
52lrwxr-xr-x 1 sander staff 17 1 jan 1970 security -> /usr/bin/security
53lrwxr-xr-x 1 sander staff 21 1 jan 1970 xcode-select -> /usr/bin/xcode-select
54lrwxr-xr-x 1 sander staff 61 1 jan 1970 xcodebuild -> /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild
55lrwxr-xr-x 1 sander staff 14 1 jan 1970 xcrun -> /usr/bin/xcrun
56```
57
58Building an iOS application
59---------------------------
60We can build an iOS app executable for the simulator, or an IPA/xcarchive file
61for release purposes, e.g. ad-hoc, enterprise or store installations, by
62executing the `xcodeenv.buildApp {}` function:
63
64```nix
65let
66 pkgs = import <nixpkgs> {};
67
68 xcodeenv = import ./xcodeenv {
69 inherit (pkgs) stdenv;
70 };
71in
72xcodeenv.buildApp {
73 name = "MyApp";
74 src = ./myappsources;
75 sdkVersion = "11.2";
76
77 target = null; # Corresponds to the name of the app by default
78 configuration = null; # Release for release builds, Debug for debug builds
79 scheme = null; # -scheme will correspond to the app name by default
80 sdk = null; # null will set it to 'iphonesimulator` for simulator builds or `iphoneos` to real builds
81 xcodeFlags = "";
82
83 release = true;
84 certificateFile = ./mycertificate.p12;
85 certificatePassword = "secret";
86 provisioningProfile = ./myprovisioning.profile;
87 signMethod = "ad-hoc"; # 'enterprise' or 'store'
88 generateIPA = true;
89 generateXCArchive = false;
90
91 enableWirelessDistribution = true;
92 installURL = "/installipa.php";
93 bundleId = "mycompany.myapp";
94 appVersion = "1.0";
95
96 # Supports all xcodewrapper parameters as well
97 xcodeBaseDir = "/Applications/Xcode.app";
98}
99```
100
101The above function takes a variety of parameters:
102* The `name` and `src` parameters are mandatory and specify the name of the app
103 and the location where the source code resides
104* `sdkVersion` specifies which version of the iOS SDK to use.
105
106It also possile to adjust the `xcodebuild` parameters. This is only needed in
107rare circumstances. In most cases the default values should suffice:
108
109* Specifies which `xcodebuild` target to build. By default it takes the target
110 that has the same name as the app.
111* The `configuration` parameter can be overridden if desired. By default, it
112 will do a debug build for the simulator and a release build for real devices.
113* The `scheme` parameter specifies which `-scheme` parameter to propagate to
114 `xcodebuild`. By default, it corresponds to the app name.
115* The `sdk` parameter specifies which SDK to use. By default, it picks
116 `iphonesimulator` for simulator builds and `iphoneos` for release builds.
117* The `xcodeFlags` parameter specifies arbitrary command line parameters that
118 should be propagated to `xcodebuild`.
119
120By default, builds are carried out for the iOS simulator. To do release builds
121(builds for real iOS devices), you must set the `release` parameter to `true`.
122In addition, you need to set the following parameters:
123
124* `certificateFile` refers to a P12 certificate file.
125* `certificatePassword` specifies the password of the P12 certificate.
126* `provisioningProfile` refers to the provision profile needed to sign the app
127* `signMethod` should refer to `ad-hoc` for signing the app with an ad-hoc
128 certificate, `enterprise` for enterprise certificates and `app-store` for App
129 store certificates.
130* `generateIPA` specifies that we want to produce an IPA file (this is probably
131 what you want)
132* `generateXCArchive` specifies thet we want to produce an xcarchive file.
133
134When building IPA files on Hydra and when it is desired to allow iOS devices to
135install IPAs by browsing to the Hydra build products page, you can enable the
136`enableWirelessDistribution` parameter.
137
138When enabled, you need to configure the following options:
139
140* The `installURL` parameter refers to the URL of a PHP script that composes the
141 `itms-services://` URL allowing iOS devices to install the IPA file.
142* `bundleId` refers to the bundle ID value of the app
143* `appVersion` refers to the app's version number
144
145To use wireless adhoc distributions, you must also install the corresponding
146PHP script on a web server (see section: 'Installing the PHP script for wireless
147ad hoc installations from Hydra' for more information).
148
149In addition to the build parameters, you can also specify any parameters that
150the `xcodeenv.composeXcodeWrapper {}` function takes. For example, the
151`xcodeBaseDir` parameter can be overridden to refer to a different Xcode
152version.
153
154Spawning simulator instances
155----------------------------
156In addition to building iOS apps, we can also automatically spawn simulator
157instances:
158
159```nix
160let
161 pkgs = import <nixpkgs> {};
162
163 xcodeenv = import ./xcodeenv {
164 inherit (pkgs) stdenv;
165 };
166in
167xcode.simulateApp {
168 name = "simulate";
169
170 # Supports all xcodewrapper parameters as well
171 xcodeBaseDir = "/Applications/Xcode.app";
172}
173```
174
175The above expression produces a script that starts the simulator from the
176provided Xcode installation. The script can be started as follows:
177
178```bash
179./result/bin/run-test-simulator
180```
181
182By default, the script will show an overview of UDID for all available simulator
183instances and asks you to pick one. You can also provide a UDID as a
184command-line parameter to launch an instance automatically:
185
186```bash
187./result/bin/run-test-simulator 5C93129D-CF39-4B1A-955F-15180C3BD4B8
188```
189
190You can also extend the simulator script to automatically deploy and launch an
191app in the requested simulator instance:
192
193```nix
194let
195 pkgs = import <nixpkgs> {};
196
197 xcodeenv = import ./xcodeenv {
198 inherit (pkgs) stdenv;
199 };
200in
201xcode.simulateApp {
202 name = "simulate";
203 bundleId = "mycompany.myapp";
204 app = xcode.buildApp {
205 # ...
206 };
207
208 # Supports all xcodewrapper parameters as well
209 xcodeBaseDir = "/Applications/Xcode.app";
210}
211```
212
213By providing the result of an `xcode.buildApp {}` function and configuring the
214app bundle id, the app gets deployed automatically and started.
215
216Troubleshooting
217---------------
218In some rare cases, it may happen that after a failure, changes are not picked
219up. Most likely, this is caused by a derived data cache that Xcode maintains.
220To wipe it you can run:
221
222```bash
223$ rm -rf ~/Library/Developer/Xcode/DerivedData
224```