Simple install guide and one-step install.sh

- README rewritten as a step-by-step guide for non-developers
- install.sh: build, install and copy data with plain error messages
- build_native.py: bundle identifier from the user's provisioning
  profile (Xcode project named factorio), version check on every
  build, friendly errors

docs/building.md

@@ -32,28 +32,33 @@ The default game location is
 ## Signing
 
 The app is signed with your **Apple Development** certificate and a development provisioning
-profile. The build script picks them automatically:
+profile from `~/Library/Developer/Xcode/UserData/Provisioning Profiles`. The build chooses:
 
-- it looks in `~/Library/Developer/Xcode/UserData/Provisioning Profiles` for a profile whose
-  App ID is exactly the app's bundle identifier, or a wildcard (`TEAMID.*`) profile;
-- it signs with the keychain identity whose certificate is embedded in that profile;
-- the team ID comes from the profile (override with `--team` / `FX_TEAM`).
+1. with `--bundle-id` (or `FX_BUNDLE_ID`): a profile for exactly that App ID, else a wildcard
+   (`TEAMID.*`) profile;
+2. otherwise: the newest profile whose App ID contains `factorio`, and that App ID becomes the
+   app's bundle identifier;
+3. otherwise: a wildcard profile, with bundle identifier `local.factorio.native`.
 
-If you have no suitable profile yet, let Xcode create one: create any new iOS App project, set
-its bundle identifier to `local.factorio.native` (or your own identifier, then pass the same one
-to `--bundle-id`), choose your team under *Signing & Capabilities* with automatic signing, select
-your iPhone and build it once. Xcode then downloads a profile that the script can use.
+It signs with the keychain identity whose certificate is embedded in the chosen profile; the team
+comes from the profile (override with `--team` / `FX_TEAM`). Expired profiles are ignored.
 
-Free Apple accounts can sign apps for their own devices, but the installed app expires after
-seven days and has to be reinstalled. This has only been tested with a paid account.
+The README's step 4 creates a suitable profile: an empty Xcode iOS App project named `factorio`,
+with automatic signing for your team, run once on the iPhone. Its App ID
+(`com.<you>.factorio`) is unique to you, which Apple requires for explicit App IDs.
+
+Free Apple accounts work the same way, but the installed app expires after seven days and has to
+be reinstalled with `./install.sh` (saves are kept). This has been tested with a paid account
+only.
 
 ## 3. Build and install
 
 ```sh
-python3 tools/build_native.py --install --push-data
+./install.sh            # same as: python3 tools/build_native.py --install --push-data
 ```
 
-What happens:
+`install.sh` runs the steps below with short progress messages and writes the full output to
+`build/install.log`. What happens:
 
 1. **Inputs.** The ARM64 slice of the game executable is extracted with `lipo` into
    `build/factorio.arm64`. The Wuffs PNG decoder source (v0.3.4) is downloaded into
@@ -90,7 +95,7 @@ installing takes the longest; the main menu normally appears after about 16 seco
 | --- | --- | --- |
 | `--game PATH` | `FX_GAME` | Steam location (see above) |
 | `--team ID` | `FX_TEAM` | Taken from the provisioning profile |
-| `--bundle-id ID` | `FX_BUNDLE_ID` | `local.factorio.native` |
+| `--bundle-id ID` | `FX_BUNDLE_ID` | From the provisioning profile (see [Signing](#signing)) |
 | `--device ID` | `FX_DEVICE` | First paired device |
 | `--no-build` | | Install/launch the existing bundle |
 
@@ -110,7 +115,7 @@ files under the phone → Files → Factorio. A save from the Mac can be copied
 
 ```sh
 xcrun devicectl device copy to --device <id> --domain-type appDataContainer \
-  --domain-identifier local.factorio.native \
+  --domain-identifier <bundle identifier> \
   --source ~/Library/Application\ Support/factorio/saves/my-save.zip \
   --destination Documents/factorio/write/saves/my-save.zip
 ```
@@ -119,8 +124,8 @@ xcrun devicectl device copy to --device <id> --domain-type appDataContainer \
 
 | Symptom | Cause and fix |
 | --- | --- |
-| `unexpected input …; only the inspected 2.0.77 ARM64 slice is supported` | The installed game is a different version. Install 2.0.77, or delete `build/factorio.arm64` if it was extracted from another install. |
-| `no provisioning profile covers …` | See [Signing](#signing). |
+| `wrong Factorio version` | The installed game is not 2.0.77. Select that version in Steam (game Properties → Betas) or pass `--game` to a 2.0.77 install. |
+| `no provisioning profile found` | See [Signing](#signing). |
 | `Unable to launch … because the device was not, or could not be, unlocked` | Unlock the phone and run the launch again. |
 | App shows "Game data missing" | Run `python3 tools/build_native.py --no-build --push-data`. |
 | App closes during play | Run with `--launch`, then `python3 tools/symbolize_native.py` to turn the `[fx-crash]` lines in `build/native/console.log` into function names. If there is no crash report, iOS may have stopped it for memory; check Settings → Privacy & Security → Analytics & Improvements → Analytics Data for a `JetsamEvent` report. |