Add documentation for building iOS apps
This commit is contained in:
Sander van der Burg
parent
676d07af3f
commit
56e112e874
2 changed files with 220 additions and 0 deletions
|
|
@ -17,6 +17,7 @@
|
|||
<xi:include href="go.xml" />
|
||||
<xi:include href="haskell.section.xml" />
|
||||
<xi:include href="idris.section.xml" />
|
||||
<xi:include href="ios.section.xml" />
|
||||
<xi:include href="java.xml" />
|
||||
<xi:include href="lua.xml" />
|
||||
<xi:include href="node.section.xml" />
|
||||
|
|
|
|||
219
doc/languages-frameworks/ios.section.md
Normal file
219
doc/languages-frameworks/ios.section.md
Normal file
|
|
@ -0,0 +1,219 @@
|
|||
---
|
||||
title: iOS
|
||||
author: Sander van der Burg
|
||||
date: 2018-11-18
|
||||
---
|
||||
# iOS
|
||||
|
||||
This component is basically a wrapper/workaround that makes it possible to
|
||||
expose an Xcode installation as a Nix package by means of symlinking to the
|
||||
relevant executables on the host system.
|
||||
|
||||
Since Xcode can't be packaged with Nix, nor we can publish it as a Nix package
|
||||
(because of its license) this is basically the only integration strategy
|
||||
making it possible to do iOS application builds that integrate with other
|
||||
components of the Nix ecosystem
|
||||
|
||||
The primary objective of this project is to use the Nix expression language to
|
||||
specify how iOS apps can be built from source code, and to automatically spawn
|
||||
iOS simulator instances for testing.
|
||||
|
||||
This component also makes it possible to use [Hydra](http://nixos.org/hydra),
|
||||
the Nix-based continuous integration server to regularly build iOS apps and to
|
||||
do wireless ad-hoc installations of enterprise IPAs on iOS devices through
|
||||
Hydra.
|
||||
|
||||
The Xcode build environment implements a number of features.
|
||||
|
||||
Deploying a proxy component wrapper exposing Xcode
|
||||
--------------------------------------------------
|
||||
The first use case is deploying a Nix package that provides symlinks to the Xcode
|
||||
installation on the host system. This package can be used as a build input to
|
||||
any build function implemented in the Nix expression language that requires
|
||||
Xcode.
|
||||
|
||||
```nix
|
||||
let
|
||||
pkgs = import <nixpkgs> {};
|
||||
|
||||
xcodeenv = import ./xcodeenv {
|
||||
inherit (pkgs) stdenv;
|
||||
};
|
||||
in
|
||||
xcodeenv.composeXcodeWrapper {
|
||||
version = "9.2";
|
||||
xcodeBaseDir = "/Applications/Xcode.app";
|
||||
}
|
||||
```
|
||||
|
||||
By deploying the above expression with `nix-build` and inspecting its content
|
||||
you will notice that several Xcode-related executables are exposed as a Nix
|
||||
package:
|
||||
|
||||
```bash
|
||||
$ ls result/bin
|
||||
lrwxr-xr-x 1 sander staff 94 1 jan 1970 Simulator -> /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/Contents/MacOS/Simulator
|
||||
lrwxr-xr-x 1 sander staff 17 1 jan 1970 codesign -> /usr/bin/codesign
|
||||
lrwxr-xr-x 1 sander staff 17 1 jan 1970 security -> /usr/bin/security
|
||||
lrwxr-xr-x 1 sander staff 21 1 jan 1970 xcode-select -> /usr/bin/xcode-select
|
||||
lrwxr-xr-x 1 sander staff 61 1 jan 1970 xcodebuild -> /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild
|
||||
lrwxr-xr-x 1 sander staff 14 1 jan 1970 xcrun -> /usr/bin/xcrun
|
||||
```
|
||||
|
||||
Building an iOS application
|
||||
---------------------------
|
||||
We can build an iOS app executable for the simulator, or an IPA/xcarchive file
|
||||
for release purposes, e.g. ad-hoc, enterprise or store installations, by
|
||||
executing the `xcodeenv.buildApp {}` function:
|
||||
|
||||
```nix
|
||||
let
|
||||
pkgs = import <nixpkgs> {};
|
||||
|
||||
xcodeenv = import ./xcodeenv {
|
||||
inherit (pkgs) stdenv;
|
||||
};
|
||||
in
|
||||
xcodeenv.buildApp {
|
||||
name = "MyApp";
|
||||
src = ./myappsources;
|
||||
sdkVersion = "11.2";
|
||||
|
||||
target = null; # Corresponds to the name of the app by default
|
||||
configuration = null; # Release for release builds, Debug for debug builds
|
||||
scheme = null; # -scheme will correspond to the app name by default
|
||||
sdk = null; # null will set it to 'iphonesimulator` for simulator builds or `iphoneos` to real builds
|
||||
xcodeFlags = "";
|
||||
|
||||
release = true;
|
||||
certificateFile = ./mycertificate.p12;
|
||||
certificatePassword = "secret";
|
||||
provisioningProfile = ./myprovisioning.profile;
|
||||
signMethod = "ad-hoc"; # 'enterprise' or 'store'
|
||||
generateIPA = true;
|
||||
generateXCArchive = false;
|
||||
|
||||
enableWirelessDistribution = true;
|
||||
installURL = "/installipa.php";
|
||||
bundleId = "mycompany.myapp";
|
||||
appVersion = "1.0";
|
||||
|
||||
# Supports all xcodewrapper parameters as well
|
||||
xcodeBaseDir = "/Applications/Xcode.app";
|
||||
}
|
||||
```
|
||||
|
||||
The above function takes a variety of parameters:
|
||||
* The `name` and `src` parameters are mandatory and specify the name of the app
|
||||
and the location where the source code resides
|
||||
* `sdkVersion` specifies which version of the iOS SDK to use.
|
||||
|
||||
It also possile to adjust the `xcodebuild` parameters. This is only needed in
|
||||
rare circumstances. In most cases the default values should suffice:
|
||||
|
||||
* Specifies which `xcodebuild` target to build. By default it takes the target
|
||||
that has the same name as the app.
|
||||
* The `configuration` parameter can be overridden if desired. By default, it
|
||||
will do a debug build for the simulator and a release build for real devices.
|
||||
* The `scheme` parameter specifies which `-scheme` parameter to propagate to
|
||||
`xcodebuild`. By default, it corresponds to the app name.
|
||||
* The `sdk` parameter specifies which SDK to use. By default, it picks
|
||||
`iphonesimulator` for simulator builds and `iphoneos` for release builds.
|
||||
* The `xcodeFlags` parameter specifies arbitrary command line parameters that
|
||||
should be propagated to `xcodebuild`.
|
||||
|
||||
By default, builds are carried out for the iOS simulator. To do release builds
|
||||
(builds for real iOS devices), you must set the `release` parameter to `true`.
|
||||
In addition, you need to set the following parameters:
|
||||
|
||||
* `certificateFile` refers to a P12 certificate file.
|
||||
* `certificatePassword` specifies the password of the P12 certificate.
|
||||
* `provisioningProfile` refers to the provision profile needed to sign the app
|
||||
* `signMethod` should refer to `ad-hoc` for signing the app with an ad-hoc
|
||||
certificate, `enterprise` for enterprise certificates and `app-store` for App
|
||||
store certificates.
|
||||
* `generateIPA` specifies that we want to produce an IPA file (this is probably
|
||||
what you want)
|
||||
* `generateXCArchive` specifies thet we want to produce an xcarchive file.
|
||||
|
||||
When building IPA files on Hydra and when it is desired to allow iOS devices to
|
||||
install IPAs by browsing to the Hydra build products page, you can enable the
|
||||
`enableWirelessDistribution` parameter.
|
||||
|
||||
When enabled, you need to configure the following options:
|
||||
|
||||
* The `installURL` parameter refers to the URL of a PHP script that composes the
|
||||
`itms-services://` URL allowing iOS devices to install the IPA file.
|
||||
* `bundleId` refers to the bundle ID value of the app
|
||||
* `appVersion` refers to the app's version number
|
||||
|
||||
To use wireless adhoc distributions, you must also install the corresponding
|
||||
PHP script on a web server (see section: 'Installing the PHP script for wireless
|
||||
ad hoc installations from Hydra' for more information).
|
||||
|
||||
In addition to the build parameters, you can also specify any parameters that
|
||||
the `xcodeenv.composeXcodeWrapper {}` function takes. For example, the
|
||||
`xcodeBaseDir` parameter can be overridden to refer to a different Xcode
|
||||
version.
|
||||
|
||||
Spawning simulator instances
|
||||
----------------------------
|
||||
In addition to building iOS apps, we can also automatically spawn simulator
|
||||
instances:
|
||||
|
||||
```nix
|
||||
let
|
||||
pkgs = import <nixpkgs> {};
|
||||
|
||||
xcodeenv = import ./xcodeenv {
|
||||
inherit (pkgs) stdenv;
|
||||
};
|
||||
in
|
||||
xcode.simulateApp {
|
||||
name = "simulate";
|
||||
|
||||
# Supports all xcodewrapper parameters as well
|
||||
xcodeBaseDir = "/Applications/Xcode.app";
|
||||
}
|
||||
```
|
||||
|
||||
The above expression produces a script that starts the simulator from the
|
||||
provided Xcode installation. The script can be started as follows:
|
||||
|
||||
```bash
|
||||
./result/bin/run-test-simulator
|
||||
```
|
||||
|
||||
By default, the script will show an overview of UDID for all available simulator
|
||||
instances and asks you to pick one. You can also provide a UDID as a
|
||||
command-line parameter to launch an instance automatically:
|
||||
|
||||
```bash
|
||||
./result/bin/run-test-simulator 5C93129D-CF39-4B1A-955F-15180C3BD4B8
|
||||
```
|
||||
|
||||
You can also extend the simulator script to automatically deploy and launch an
|
||||
app in the requested simulator instance:
|
||||
|
||||
```nix
|
||||
let
|
||||
pkgs = import <nixpkgs> {};
|
||||
|
||||
xcodeenv = import ./xcodeenv {
|
||||
inherit (pkgs) stdenv;
|
||||
};
|
||||
in
|
||||
xcode.simulateApp {
|
||||
name = "simulate";
|
||||
bundleId = "mycompany.myapp";
|
||||
app = xcode.buildApp {
|
||||
# ...
|
||||
};
|
||||
|
||||
# Supports all xcodewrapper parameters as well
|
||||
xcodeBaseDir = "/Applications/Xcode.app";
|
||||
}
|
||||
```
|
||||
|
||||
By providing the result of an `xcode.buildApp {}` function and configuring the
|
||||
app bundle id, the app gets deployed automatically and started.
|
||||
Loading…
Reference in a new issue