diff --git a/src/cordova/apple/README.md b/src/cordova/apple/README.md index fac531741c..fdf095a03e 100644 --- a/src/cordova/apple/README.md +++ b/src/cordova/apple/README.md @@ -1,28 +1,66 @@ # Apple Development Instructions -This document describes how to develop and debug for macOS (formerly known as OS X) and iOS. You will need: +This document describes how to develop and debug for macOS (formerly known as OS X) and iOS. + +## Install requirements + +You will need: - An Apple Developer Account. You will need to be invited to your developer team as well. - XCode 13.2+ ([download](https://developer.apple.com/xcode/)) - XCode command line tools: `xcode-select --install` -> NOTE: Should you encounter issues with your build, there may be apple-specific dependencies that are out of date. Run `npm run clean` and try again! +> NOTE: Should you encounter issues with your build, there may be apple-specific dependencies that are out of date. Run `npm run reset` and try again! + + -## iOS +## Set up XCode project -To build for iOS, run: +The XCode project is created by Cordova. To create the project and open it on XCode, use `npm run action cordova/setup $PLATFORM`, then open the `.xcworkspace` file. + +For the **iOS** client: ```sh - npm run action cordova/build ios +npm run action cordova/build ios && open ./src/cordova/apple/ios.xcworkspace ``` -To open the iOS project on XCode: +For the **macOS** client on an **Intel** computer: ```sh - open ./src/cordova/apple/ios.xcworkspace +npm run action cordova/build macos && open ./src/cordova/apple/macos.xcworkspace ``` -### Adding support for your device in XCode +For the **macOS** client on an **Apple Silicon** (arm64) computer: + +```sh +SENTRY_DSN=https://public@sentry.example.com/1 npm run action cordova/setup macos -- --buildMode=release --versionName=0.0.0-dev && open ./src/cordova/apple/macos.xcworkspace +``` + +> **Note**: On Apple Silicon the macOS web UI is broken in debug mode, so we need to build it in release mode. We are specifying a fake `SENTRY_DSN`, you should specify your own in your releases. + +## Set up signing + +1. Make sure you are logged into your Apple Developer account. Go to *Preferences > Accounts* and make sure your account is set. +1. Select "Outline" in the left navigation bar. +1. Under the "Signing & Capabilities" tab, select the "Jigsaw Operations LLC" for "Team". + +## Run the App + +### Specify the Destination + +For the **macOS** client, you can run it directly on your macOS computer: *Product > Destination > My Mac*. + +For the **iOS** client, you have a few options: +- Run on your macOS computer: *Product > Destination > My Mac (designed for iPad)* + - This is a great option for development, but only available on Apple Silicon computers. +- Run on a physical iOS device + - This is a great option to evaluate how it performs on a real device. You will need to enable development mode and register your device. +- Run on a simulator + - This is helpful to test the UI, but the VPN doesn't work on simulators, so this option is not recommended. + +See [Devices and Simulator](https://developer.apple.com/documentation/xcode/devices-and-simulator) for details on running on a physical iOS device or the simulator. + +#### Adding support for your iOS device in XCode You may find that your iOS version is _too modern_ for XCode. You'll need to do the following: @@ -33,63 +71,119 @@ You may find that your iOS version is _too modern_ for XCode. You'll need to do Applications >> Xcode >> Right Click >> Show Package Contents >> Contents >> Developer >> Platforms >> iPhoneOS.platform >> DeviceSupport ``` -3. Restart XCode! +3. Restart XCode. + + +### Build and Start the App + +To run the app, first **clean the build** (*Product > Clean Build Folder…*), then **run** (*Product > Run*), via the menu or the play button: +image -## macOS +> **Warning** +> +> If you don't clean the build first, it will fail with `Command CodeSign failed with a nonzero exit code`. -To build for macOS (OS X), run: + +## Development + +Most of the Apple-specific development can happen directly on XCode. However, if you edit files in the generated `platforms/ios` or `platforms/osx`, you will need to copy your changes to the appropriate version-controlled location at [`src/cordova/apple/xcode`](./xcode) or [`src/cordova/plugin/apple`](../plugin/apple). + +Changes to the [OutlineAppleLib](./OutlineAppleLib) package don't need to be copied, since the package is linked by the XCode workspace and the changes happen in the original location. + +## Inspect Logs + +The easiest way to inspect logs is to use the `log` command. To see the client app logs in real time, you can use `log stream` with a `--predicate` flag to select the messages sent by the Outline code: ```sh - npm run action cordova/build macos +log stream --info --predicate 'senderImagePath endswith "Outline" or senderImagePath endswith "VpnExtension"' ``` -To open the macOS project on XCode: +In the Console app, that filter is equivalent to "Library Path" "contains" "Outline.app": +image + +Tip: you can **save searches** in the Console app. + +For forther debugging, you can include relevant messages from the Network Extension subsystem: ```sh - open ./src/cordova/apple/macos.xcworkspace +log stream --info --predicate 'senderImagePath contains "Outline.app" or (processImagePath contains "Outline.app" and subsystem contains "com.apple.networkextension")' ``` -### MacOS Development in XCode +To see past logs use `log show` and the `--last` flag. -We recommend that you develop OS X specific functionality in the `platforms/osx` directory. However this is not version-controlled. Once you have made your changes in the `platforms/osx` directory, be sure to copy it to the version-controlled source code in `cordova-plugin-outline/apple/` +For details on Apple logging, see [Your Friend the System Log](https://developer.apple.com/forums/thread/705868/) and [Mac Logging and the log Command: A Guide for Apple Admins](https://blog.kandji.io/mac-logging-and-the-log-command-a-guide-for-apple-admins#:~:text=The%20log%20command%20is%20built,(Press%20q%20to%20exit.)). -To run the project in XCode: -* open `./src/cordova/apple/macos.xcworkspace` -* Make sure you are logged into your Apple Developer account. Go to Preferences → Accounts, make sure your account is set. -* Click "Outline" in the left navigation bar: - * Under "Signing" select "Jigsaw Operations LLC" - * Click Register Device - needed the first time running the app on a new device. -* Press Cmd+R to run +## Debugging the Vpn Extension +The VpnExtension runs in a separate process and its output is not logged to the Xcode console. To view its log statements see the "Inspect Logs" section. -The main entry point for Apple specific code is `Outline/Plugins/OutlinePlugin.swift` +To attach the debugger to the `VpnExtension`, in XCode, select Debug > Attach to Process > VpnExtension + * This can only be done once the VPN Extension is running (after you are connected). + * You won't see the log messages in the Xcode console. To see the messagges, refer to the "Inspect Logs" instructions. + * See [Debug, Profile, and Test Your App Extension](https://developer.apple.com/library/content/documentation/General/Conceptual/ExtensibilityPG/ExtensionCreation.html#//apple_ref/doc/uid/TP40014214-CH5-SW8). -### To debug the MacOS VpnExtension process +### Troubleshoot `VpnStartFailure` -* VpnExtension runs in a separate process and its output is not logged to the Xcode console. To view its log statements, open the Console.app and filter messages that contain "Outline" or “VpnExtension”. -* In XCode, click top Debug menu → Attach to Process → VpnExtension - * This can only be done once the VPN Extension is running (after you are connected). - * [Detailed instructions](https://developer.apple.com/library/content/documentation/General/Conceptual/ExtensibilityPG/ExtensionCreation.html#//apple_ref/doc/uid/TP40014214-CH5-SW8). +Sometimes the app will refuse to connect, with a `VpnStartFailure` error: -### Debugging the MacOS UI +image -To debug the macOS webview: +If that happens, there are some things you can try. -* In your terminal, run `defaults write org.outline.osx.client WebKitDeveloperExtras -bool true`. This is only needed once, to make the Outline webview debuggable. You may need to re-run the whole Outline app (use Cmd+R). -* Once this is done, right click → Inspect Context in the Outline client app. This will open the safari debugger -* To reload the UI without re-running the application, right-click → Reload. -### Fixing the MacOS VpnExtension configuration: +#### Kill any leftover processes + +You can check running processes with the [`pgrep` command](https://man7.org/linux/man-pages/man1/pgrep.1.html): +```sh +pgrep Outline VpnExtension +``` + +You can kill them with the [`pkill` command](https://man7.org/linux/man-pages/man1/pgrep.1.html): +```sh +pkill -9 Outline VpnExtension +``` + +Sometimes the processes will not die, even with `-9`. For the Outline process, you may need to kill its parent process, usually `debugserver`. + +#### Ensure the extension is being loaded The VpnExtension is an [application extension](https://developer.apple.com/library/content/documentation/General/Conceptual/ExtensibilityPG/) that handles the device’s traffic when the VPN is enabled. The system must be aware of the extension in order to invoke it. Normally, running the app is enough to trigger the registration of the VpnExtension. However, the system can get confused in a development environment, failing to register the plugin automatically. -If you cannot connect to a server due to a VPN error: +In your terminal, use the `pluginkit` command to inspect the registered plugins: +```sh +pluginkit -m -v | grep outline +``` + +You should see an for the VpnExtension in your Xcode project, where the version and binary location match. This should output something similar to: + +`org.outline.macos.client.VpnExtension(0.0.0-dev) 508D6616-9FCB-4302-B00F-22121C236AAC 2023-07-14 00:05:34 +0000 /Users/$USER/Library/Developer/Xcode/DerivedData/macos-bnidlwvulcdazjfxleynwzkychqi/Build/Products/Debug/Outline.app/Contents/PlugIns/VpnExtension.appex` + +Note how `VpnExtension.appex` is inside `Outline.app/`. + +If the VpnExtension is not listed, manually add it to the plugin list: +1. Determine the VpnExtension path + 1. In XCode, go to *Product > Show Build Folder in Finder*. That will open the `Build/` folder. + 1. The VpnExtension will be at `Build/Products/Debug/Outline.app/Contents/PlugIns/VpnExtension.appex` +1. Run `run pluginkit -a `, e.g. `pluginkit -a /Users/$USER/Library/Developer/Xcode/DerivedData/macos-bnidlwvulcdazjfxleynwzkychqi/Build/Products/Debug/Outline.app/Contents/PlugIns/VpnExtension.appex` + +#### Delete the existing VPN configuration + +You may want to also delete the VPN configurations: +1. Open the System Settings +1. Go to *VPN* +1. Press the Info button for the Outline service +1. Press *Remove Configuration…* and confirm + + +#### Restart + +If all fails, restart your device. That usually takes care of the issue. + +## Debug the web UI + +To debug the webview: + +1. In your terminal, run `defaults write org.outline.osx.client WebKitDeveloperExtras -bool true`. This is only needed once, to make the Outline webview debuggable. You may need to re-run the whole Outline app (use Cmd+R). +1. In the Outline Client app, right click → Inspect Context. This will open the Safari debugger -* In your terminal, run `pluginkit -m -v | grep outline` to search for the VpnExtension plugin - you should see one for your new Xcode project, where the version and binary location match. This should output something similar to: - * `org.outline.osx.client.VpnExtension(0.1.2) 970A0E28-06F0-4658-A194-EE755155644C 2018-01-26 21:51:06 +0000 /Users/$USER/Library/Developer/Xcode/DerivedData/Outline-buohazzevizjuxclukgvoyyvsonu/Build/Products/Debug/Outline.app/Contents/PlugIns/VpnExtension.appex` -* To learn the path of your VpnExtension: - * In XCode, click on the Folder Icon (top left), then navigate to the Products folder - * Drag the "Outline.app" item to the terminal - this will tell you the path of the app, something like `/Users/$USER/Library/Developer/Xcode/DerivedData/Outline-buohazzevizjuxclukgvoyyvsonu/Build/Products/Debug/Outline.app/` - * In that directory, look for `Contents/PlugIns/VpnExtension.appex/`, e.g. `/Users/$USER/Library/Developer/Xcode/DerivedData/Outline-buohazzevizjuxclukgvoyyvsonu/Build/Products/Debug/Outline.app/Contents/PlugIns/VpnExtension.appex/` -* In the terminal, run pluginkit -a , e.g. `pluginkit -a /Users/$USER/Library/Developer/Xcode/DerivedData/Outline-buohazzevizjuxclukgvoyyvsonu/Build/Products/Debug/Outline.app/Contents/PlugIns/VpnExtension.appex/` -* Open Mac Settings → Network, then delete the Outline network +To reload the UI without re-running the application, right-click → Reload. \ No newline at end of file