readme: updated development instructions

Moved to their own pages.

Documentation/MacDevelopment.md

@@ -0,0 +1,93 @@
+# macOS Development
+
+Because UTM is a sand-boxed Mac app, there are a few extra steps needed for a proper development environment.
+
+## Getting the Source
+
+Make sure you perform a recursive clone to get all the submodules:
+```
+git clone --recursive https://github.com/utmapp/UTM.git
+```
+
+Alternatively, run `git submodule update --init --recursive` after cloning if you did not do a recursive clone.
+
+## Dependencies
+
+The easy way is to get the prebuilt dependences from [Github Actions][1]. Pick the latest release and download all of the `Sysroot-macos-*` artifacts. You need to be logged in to Github to download artifacts. If you only intend to run locally, it is alright to just download the sysroot for your architecture.
+
+### Building Dependencies (Advanced)
+
+If you want to build the dependencies yourself, it is highly recommended that you start with a fresh macOS VM. This is because some of the dependencies attempt to use `/usr/local/lib` even though the architecture does not match. Certain installed packages like `libusb`, `gawk`, and `cmake` will break the build.
+
+1. Install Xcode command line and [Homebrew][1]
+2. Install the following build prerequisites
+    `brew install bison pkg-config gettext glib libgpg-error nasm make meson`
+   Make sure to add `bison` and `gettext` to your `$PATH` environment variable!
+	`export PATH=/usr/local/opt/bison/bin:/usr/local/opt/gettext/bin:$PATH`
+3. Run `./scripts/build_dependencies.sh -p macos -a ARCH` where `ARCH` is either `arm64` or `x86_64`.
+
+If you want to build universal binaries, you need to run `build_dependencies.sh` for both `arm64` and `x86_64` and then run
+
+```
+./scripts/pack_dependencies.sh . macos arm64 x86_64
+```
+
+If you are developing QEMU and wish to pass in a custom path to QEMU, you can use the `-q PATH_TO_QEMU_SOURCE` option to `build_dependencies.sh`. Note that you need to use a UTM compatible fork of QEMU.
+
+## Building UTM
+
+### Command Line
+
+You can build UTM with the script:
+
+```
+./scripts/build_utm.sh -p macos -a ARCH -o /path/to/output/directory
+```
+
+`ARCH` can be `x86_64` or `arm64` or `"arm64 x86_64"` (quotes are required) for a universal binary. The built artifact is an unsigned `.xcarchive` which you can use with the package tool (see below).
+
+### Packaging
+
+Artifacts built with `build_utm.sh` (includes Github Actions artifacts) must be re-signed before it can be used. To properly use all features, you must be a paid Apple Developer with access to a provisioning profile with the Hypervisor entitlements. However, non-registered developers can build "unsigned" packages which lack certain features (such as USB and network bridging support).
+
+#### Unsigned packages
+
+```
+./scripts/package_mac.sh unsigned /path/to/UTM.xcarchive /path/to/output
+```
+
+This builds `UTM.dmg` in `/path/to/output` which can be installed to `/Applications`.
+
+#### Signed packages
+
+```
+./scripts/package_mac.sh developer-id /path/to/UTM.xcarchive /path/to/output TEAM_ID PROFILE_UUID
+```
+
+To build a signed package, you need to be a registered Apple Developer. From the developer portal, create a certificate for "Developer ID Application" (and install it into your Keychain). Also create a provisioning profile with that certificate with Hypervisor entitlements (you need to manually request these entitlements and be approved by Apple). `TEAM_ID` should be the same as in the certificate and `PROFILE_UUID` should be the UUID of the profile installed by Xcode (open the profile in Xcode).
+
+Once properly signed, you can ask Apple to notarize the DMG.
+
+#### Mac App Store
+
+```
+./scripts/package_mac.sh app-store /path/to/UTM.xcarchive /path/to/output TEAM_ID PROFILE_UUID
+```
+
+Similar to the above but builds a `UTM.pkg` for submission to the Mac App Store. You need a certificate for "Apple Distribution" and a certificate for "Mac App Distribution" as well as a provisioning profile with the right entitlements.
+
+### Xcode Development
+
+To build the Xcode project without a registered developer account, you will need to disable USB support.
+
+1. Open `Platform/macOS/macOS.entitlements` and delete the entry for `com.apple.vm.device-access`.
+2. In the project settings, select the "macOS" target and go to the "Signing & Capabilities" tab and check the box for "Disable Library Validation".
+3. Repeat for the "QEMUHelper" target.
+4. Repeat for the "QEMULauncher" target.
+
+You should now be able to run and debug UTM. If you have a registered developer account with access to Hypervisor entitlements, you can (for all three targets) select your Team and "Development" Signing Certificate from the "Signing & Capabilities" tab.
+
+Note that due to a macOS bug, you may get a crash when launching a VM with the debugger attached. The workaround is to start UTM with the debugger detached and attach the debugger with Debug -> Attach to Process after launching a VM. Once you do that, you can start additional VMs without any issues with the debugger.
+
+[1]: https://github.com/utmapp/UTM/actions?query=event%3Arelease+workflow%3ABuild
+[2]: https://brew.sh

Documentation/iOSDevelopment.md

@@ -0,0 +1,82 @@
+# iOS Development
+
+This document describes the steps to build and debug UTM on iOS and simulator devices.
+
+## Getting the Source
+
+Make sure you perform a recursive clone to get all the submodules:
+```
+git clone --recursive https://github.com/utmapp/UTM.git
+```
+
+Alternatively, run `git submodule update --init --recursive` after cloning if you did not do a recursive clone.
+
+## Dependencies
+
+The easy way is to get the prebuilt dependences from [Github Actions][1]. Pick the latest release and download all of the `Sysroot-iOS-*` artifacts. You need to be logged in to Github to download artifacts. If you want to run on a real iOS device, get the `arm64` variant. If you want to run on iOS simulator for Intel Mac, get the `x86_64` variant. At this time, there is no pre-built for iOS simulator for M1 Macs.
+
+### Building Dependencies (Advanced)
+
+If you want to build the dependencies yourself, it is highly recommended that you start with a fresh macOS VM. This is because some of the dependencies attempt to use `/usr/local/lib` even though the architecture does not match. Certain installed packages like `libusb`, `gawk`, and `cmake` will break the build.
+
+1. Install Xcode command line and [Homebrew][1]
+2. Install the following build prerequisites
+    `brew install bison pkg-config gettext glib libgpg-error nasm make meson`
+   Make sure to add `bison` and `gettext` to your `$PATH` environment variable!
+	`export PATH=/usr/local/opt/bison/bin:/usr/local/opt/gettext/bin:$PATH`
+3. Run `./scripts/build_dependencies.sh -p ios -a arm64` for iOS devices.
+4. (Intel Macs only) Run `./scripts/build_dependencies.sh -p ios -a x86_64` for iOS simulator.
+
+## Building UTM
+
+### Command Line
+
+You can build UTM with the script:
+
+```
+./scripts/build_utm.sh -p ios -a arm64 -o /path/to/output/directory
+```
+
+The built artifact is an unsigned `.xcarchive` which you can use with the package tool (see below).
+
+### Packaging
+
+Artifacts built with `build_utm.sh` (includes Github Actions artifacts) must be re-signed before it can be used. For stock iOS devices, you can sign with either a free developer account or a paid developer account. Free accounts have a 7 day expire time and must be re-signed every 7 days. For jailbroken iOS devices, you can generate a DEB which is fake-signed.
+
+#### Stock signed IPA
+
+For a user friendly option, you can use [iOS App Signer][3] to re-sign the `.xcarchive`. Advanced users can use the package.sh script:
+
+```
+./scripts/package.sh signedipa /path/to/UTM.xcarchive /path/to/output TEAM_ID PROFILE_UUID
+```
+
+This builds `UTM.ipa` in `/path/to/output` which can be installed by Xcode, iTunes, or AirDrop. Note that you need a "Development" signing certificate and NOT a "Distribution" certificate. This is because UTM requires a provisioning profile with the `get-task-allow` entitlement which Apple only grants for Development signing.
+
+#### Unsigned IPA
+
+```
+./scripts/package.sh ipa /path/to/UTM.xcarchive /path/to/output
+```
+
+This builds `UTM.ipa` in `/path/to/output` which can be installed by AltStore or a jailbroken device with AppSync Unified installed.
+
+#### DEB Package
+
+```
+./scripts/package.sh deb /path/to/UTM.xcarchive /path/to/output
+```
+
+This builds `UTM.deb` which is a wrapper for an unsigned `UTM.ipa` which can be installed by Cydia or Sileo along with AppSync Unified.
+
+### Xcode Development
+
+To build in Xcode for debugging, you need to change the bundle identifier to a unique value. In the project settings, choose the "iOS" target and go to the "Signing & Capabilities" tab and change the "Bundle Identifier". This can be any value that is not used by anyone else. Then choose a "Team" (free or paid account) and a certificate and profile should be generated automatically.
+
+### Tethered Launch
+
+For JIT to work on the latest version of iOS, it must be launched through the debugger. You can do it from Xcode (and detach the debugger after launching) or you can follow [these instructions](TetheredLaunch.md) for an easier way.
+
+[1]: https://github.com/utmapp/UTM/actions?query=event%3Arelease+workflow%3ABuild
+[2]: https://brew.sh
+[3]: https://dantheman827.github.io/ios-app-signer/

README.md

@@ -5,81 +5,30 @@
 
 -- <cite>Alan Turing, 1936</cite>
 
-UTM is a full featured virtual machine host for iOS. In short, it allows you to run Windows, Android, and more on your iPhone and iPad. More information at https://getutm.app/
+UTM is a full featured system emulator and virtual machine host for iOS and macOS. It is based off of QEMU. In short, it allows you to run Windows, Linux, and more on your Mac, iPhone, and iPad. More information at https://getutm.app/ and https://mac.getutm.app/
 
-![Screenshot of UTM running on iPhone][4]
+![Screenshot of UTM running on iPhone][2]
 
 ## Features
 
 * 30+ processors supported including x86_64, ARM64, and RISC-V thanks to qemu as a backend
 * Fast native graphics through para-virtualization thanks to SPICE
+* Supports attaching USB devices
 * JIT based acceleration using qemu TCG
-* Frontend designed from scratch for iOS11+ using the latest and greatest APIs
+* Frontend designed from scratch for macOS 11 and iOS 11+ using the latest and greatest APIs
 * Create, manage, run VMs directly from your device
-* No jailbreak required for iOS 11-13! (required for iOS 14+)
 
 ## Install
 
-If you just want to use UTM on iOS 11-13 or on jailbroken iOS 14, this is not the right place! Visit https://getutm.app/install/ for directions.
+UTM for iOS (available on stock iOS 11-13 and on jailbroken iOS 14+): https://getutm.app/install/
 
-## Building (iOS)
+UTM is also available for macOS: https://mac.getutm.app/
 
-To run UTM without a jailbreak on iOS 14 (as well as to develop UTM on any iOS version), [you must run with the Xcode debugger attached](Documentation/TetheredLaunch.md).
+## Development
 
-### Easy
+### [macOS Development](Documentation/MacDevelopment.md)
 
-The recommended way to obtain the dependencies is to use the built artifacts from [Github Actions][5]. Look for the latest release build and download the Sysroot artifact from either the arm64 build (for iOS) or x86_64 build (for iOS Simulator). Then unzip the artifact to the root directory of UTM. You can then open `UTM.xcodeproj`, select your signing certificate, and then run UTM from Xcode.
-
-### Advanced
-
-If you want to build the dependencies yourself, it is highly recommended that you start with a fresh macOS VM. This is because some of the dependencies attempt to use `/usr/local/lib` even though the architecture does not match. Certain installed libraries like `libusb` and `gawk` will break the build.
-
-1. Install Xcode command line and the following build prerequisites
-    `brew install bison pkg-config gettext glib libgpg-error nasm make meson`
-   Make sure to add `bison` to your `$PATH` environment!
-2. `git submodule update --init --recursive` if you haven't already
-3. Run `./scripts/build_dependencies.sh` to start the build. If building for the simulator, run `./scripts/build_dependencies.sh -p ios -a x86_64` instead.
-4. Open `UTM.xcodeproj` and select your signing certificate
-5. Select iOS as the target, build and deploy from Xcode
-
-## Building (macOS)
-
-Mostly the same as for iOS but with the following changes:
-
-* For building dependencies on Intel platforms, run `./scripts/build_dependencies.sh -p macos -a x86_64`
-* For building dependencies on Apple Silicon platforms, run `./scripts/build_dependencies.sh -p macos -a arm64`
-
-You may also download the prebuilt dependencies from Github instead.
-
-## Signing (iOS)
-
-### Signing Release
-
-The `ipa` [releases][3] are fake-signed. If you are jailbroken, you should NOT sign it. You can install directly with Filza.
-
-If you want to sign the release for stock devices, there are a variety of ways. The recommended way is with [iOS App Signer][2]. Note there are known issues with many "cloud" signing services such as AppCake and they do not work with UTM. If you get a crash while trying to launch a VM, then your signing certificate was invalid.
-
-In more technical detail, there are two kinds of signing certificates: "development" and "distribution". UTM requires "development" which has the `get-task-allow` entitlement.
-
-### Signing Development Build
-
-If you want to sign an `xcarchive` such as from a [Github Actions][1] built artifact, you can use the following command:
-
-```
-./scripts/package.sh signedipa UTM.xcarchive outputPath PROFILE_NAME TEAM_ID
-```
-
-Where `PROFILE_NAME` is the name of the provisioning profile and `TEAM_ID` is the identifier next to the team name in the provisioning profile. Make sure the signing key is imported into your keychain and the provision profile is installed on your iOS device.
-
-If you have a jailbroken device, you can also fake-sign it (with `ldid` installed):
-
-```
-./scripts/package.sh ipa UTM.xcarchive outputPath
-```
-
-## Why isn't this in the AppStore?
-
-Apple does not permit any apps that have interpreted or generated code therefore it is unlikely that UTM will ever be allowed. However, there are various ways people on the internet have come up to sideload apps without requiring a jailbreak. We do not condone or support any of these methods.
+### [iOS Development](Documentation/iOSDevelopment.md)
 
 ## License
 
@@ -88,7 +37,4 @@ UTM is distributed under the permissive Apache 2.0 license. However, it uses sev
 Some icons made by [Freepik](https://www.freepik.com) from [www.flaticon.com](https://www.flaticon.com/).
 
   [1]: https://github.com/utmapp/UTM/actions?query=event%3Arelease+workflow%3ABuild
-  [2]: https://dantheman827.github.io/ios-app-signer/
-  [3]: https://github.com/utmapp/UTM/releases
-  [4]: screen.png
-  [5]: https://github.com/utmapp/UTM/actions?query=workflow%3ABuild+event%3Arelease+is%3Asuccess
+  [2]: screen.png