Merge pull request #1002 from warmenhoven/warmenhoven/pr/apple

Update some of the docs for apple platforms
libretro · Nov 22, 2024 · 4e74ba8 · 4e74ba8
2 parents c661800 + e894457
commit 4e74ba8
Show file tree

Hide file tree

Showing 8 changed files with 130 additions and 85 deletions.
diff --git a/docs/development/retroarch/compilation/ios.md b/docs/development/retroarch/compilation/ios.md
@@ -2,32 +2,41 @@
 
 The following is a non-developer guide to install RetroArch on non-jailbroken iOS or tvOS devices.
 
-The minimum version of iOS supported is iOS 6.0. However, older versions have fewer features and worse core support.
+The minimum version of iOS supported is iOS 6.0. However, older versions have fewer features and worse core support. Additionally, building for old versions of iOS requires [old versions of Xcode](https://developer.apple.com/support/xcode/), which require old versions of macOS, all of which may be hard to come by.
 
 !!! note
-    If you just want to sideload from an IPA file, then you can find a working build (version {{ unit.stable }}) [here for tvOS](http://buildbot.libretro.com/stable/{{ unit.stable }}/apple/tvos-arm64/RetroArchTV.ipa) and [here for iOS](http://buildbot.libretro.com/stable/{{ unit.stable }}/apple/ios-arm64/RetroArch.ipa). Instructions for installing the IPA are [here](/guides/install-ios/).
+    If you just want to sideload from an IPA file, then you can find a working build (version {{ unit.stable }}) [here for tvOS](http://buildbot.libretro.com/stable/{{ unit.stable }}/apple/tvos-arm64/RetroArchTV.ipa) and [here for iOS](http://buildbot.libretro.com/stable/{{ unit.stable }}/apple/ios-arm64/RetroArch.ipa). Instructions for installing the IPA are [here](../../..//guides/install-ios.md).
 
 Because iOS requires that all code be signed, iOS does not support installing/updating cores at runtime. Instead, all cores must be built and added to the RetroArch source tree before building RetroArch.
 
 ## Environment configuration
 
-The following software needs to be installed:
+### Xcode
 
-- Xcode (macOS only)
+The only requirement for building is Xcode, which is only available for macOS. You can get Xcode from the App Store. If you have never used Xcode before, you will need to open the Xcode preferences, and in Accounts, log in with your Apple ID.
 
-You can get Xcode from the Mac App Store.
-
-### Sign in with your Apple ID
+#### Sign in with your Apple ID
 
 - Open Xcode Preferences (Xcode -> Preferences)
 - Click the "Accounts" tab
 - Hit the "+" at the bottom left and choose "Apple ID" and sign in with your Apple ID
 - Once you’ve successfully logged in, a new team called "(Your Name) Personal Team" with the role "User" will appear beneath your Apple ID.
 
-### Pair Xcode with your iOS or tvOS Device
+#### Pair Xcode with your iOS or tvOS Device
 
 Connect your iPhone to your computer. For AppleTV, because you cannot connect it directly, follow the [instructions in this Apple support article](https://support.apple.com/en-gb/HT208088) to pair your device in Xcode. When finished, you should see your specific device when you go, in Xcode, to Windows -> Devices & Simulators.
 
+### retroarch-apple-deps (optional but recommended)
+
+RetroArch optionally will automatically link with supporting libraries (including MoltenVK) that are provided by the retroarch-apple-deps repo. By default Xcode will look for these dependencies in `/usr/local/share/retroarch-apple-deps`.
+
+To get retroarch-apple-deps, run:
+
+```shell
+git clone https://github.com/warmenhoven/retroarch-apple-deps.git retroarch-apple-deps
+sudo ln -s $PWD/retroarch-apple-deps /usr/local/share
+```
+
 ## Fetching the code
 
 ### libretro-super
@@ -141,17 +150,31 @@ codesign -fs '[Your Full Developer Certificate Name]' *.dylib
 There are multiple Xcode project files in `pkg/apple`, based on minimum iOS version. The following will use `pkg/apple/RetroArch_iOS13.xcodeproj` (the latest as of this writing) as an example.
 
 1. Open Xcode.
-2. Open the following project file `pkg/apple/RetroArch_iOS13.xcodeproj`
-3. In the Navigator Pane on the left, select the `Retroarch_iOS13` project
-4. In the Project and Targets list on the left side, choose the `RetroArchiOS` (or `RetroArchTV` for tvOS) target. Select the Target (the one with the RetroArch icon), not the project.
-5. In the `Signing & Capabilities` tab, change the "Team" under Signing to be your developer name.
-6. Set the active scheme to `RetroArch iOS Release` (or `RetroArch tvOS Release` for tvOS), and select your connected iOS/tvOS device as the device.
-6. Run (**&#8984;-R**)
-
-![Xcode Steps](/image/guides/ios-install-pic-1.png)
+1. Open the following project file `pkg/apple/RetroArch_iOS13.xcodeproj`
+1. Change the identifiers and signing for the target
+    1. In the Navigator Pane on the left, select the `Retroarch_iOS13` project
+    1. In the Project and Targets list on the left side, choose the `RetroArchiOS` (or `RetroArchTV` for tvOS) target. Select the Target (the one with the RetroArch icon), not the project.
+    1. In the `Signing & Capabilities` tab, change the "Team" under Signing to be your developer name.
+    1. In the `Signing & Capabilities` tab, Change the "Bundle Identifier" to something globally unique (e.g. `your.email.address.RetroArch`).
+1. Change the signing for the extensions
+    1. In the Navigator Pane on the left, select the `Retroarch_iOS13` project
+    1. In the Project and Targets list on the left side, choose the `RetroArchWidgetExtensionExtension` (or `RetroArchTopShelfExtension` for tvOS) target.
+    1. In the `Signing & Capabilities` tab, change the "Team" under Signing to be your developer name.
+    1. In the `Signing & Capabilities` tab, Change the "Bundle Identifier" to the bundle identifier you chose for the target plus a suffix (e.g. `your.email.address.RetroArch.RetroArchWidgetExtension`).
+    1. For tvOS, in order for Top Shelf to work, you additionally need to set up the App Groups properly, described below.
+1. Set the active scheme to `RetroArch iOS Release` (or `RetroArch tvOS Release` for tvOS), and select your connected iOS/tvOS device as the device.
+1. Run (**&#8984;-R**)
+
+![Xcode Steps](../../../image/guides/ios-install-pic-1.png)
 
 Once the application has been built, installed, and run on your device, it can be run again directly from the device without needing Xcode.
 
+## App Store Build
+
+Building for the Mac App Store requires being logged into Xcode with the Apple Developer account associated with the Bundle ID for the app. The app also builds with Push Notification and CloudKit entitlements for the iCloud cloud sync driver (and Top Shelf for tvOS). Once all of the signing and entitlements are set up, creating the build is simply changing the scheme to `RetroArch AppStore`.
+
+There is an automated [fastlane](http://docs.fastlane.tools) script available in pkg/apple/fastlane that will update the build numbers and upload the built prodduct to TestFlight using an [App Store Connect API Key](http://docs.fastlane.tools/app-store-connect-api/).
+
 ## Additional Tips:
 
 ### Cores
@@ -175,7 +198,7 @@ Top Shelf for tvOS will display up to five entries from each of the History and
 
 #### Where do I start?
 
-The RetroArch codebase can be daunting, especially if you're used to iOS development in Objective C or Swift. Objective C is a subset of C so the syntax should look somewhat familiar to you.
+The RetroArch codebase can be daunting, especially if you're used to iOS development in Objective C or Swift. Objective C is a superset of C so the syntax should look somewhat familiar to you.
 
 The first and main entrypoint you should look at is in `core/griffin/griffin.c`. This is where all the code is included, with compiler flags used to bring in code specific to the platform. For iOS, you should pay attention to the compiler flags like `__APPLE__`, `TARGET_OS_IPHONE`, `HAVE_COCOATOUCH`.
 

diff --git a/docs/development/retroarch/compilation/osx.md b/docs/development/retroarch/compilation/osx.md
@@ -2,30 +2,7 @@
 
 This compilation guide will teach you how to build RetroArch for macOS/OSX.
 
-The following versions of the operating system are supported:
-
-- OSX 10.5    (Leopard)
-- OSX 10.6    (Snow Leopard)
-- OSX 10.7    (Lion)
-- OSX 10.8    (Mountain Lion)
-- OSX 10.9    (Mavericks)
-- OSX 10.10   (Yosemite)
-- OSX 10.11   (El Capitan)
-- macOS 10.12 (Sierra)
-- macOS 10.13 (High Sierra)
-- macOS 10.14 (Mojave)
-- macOS 10.15 (Catalina)
-- macOS 11    (Big Sur)
-- macOS 12    (Monterey)
-- macOS 13    (Ventura)
-
-RetroArch can work on:
-
-- 32bit PPC   processor-powered Macs
-- 64bit PPC   processor-powered Macs
-- 32bit Intel processor-powered Macs
-- 64bit Intel processor-powered Macs
-- 64bit ARM   processor-powered Macs
+All versions of the operating system since 10.5 are supported. RetroArch can work on PPC, Intel, and ARM processor-powered Macs.
 
 <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/fPO-9jescmo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
@@ -43,11 +20,20 @@ Be sure to read instructions that are given on this page.
 
 ## Environment configuration
 
-The following software needs to be installed:
+### Xcode
 
-- Xcode (macOS only)
+The only requirement for building is Xcode, which is only available for macOS. You can get Xcode from the App Store. If you have never used Xcode before, you will need to open the Xcode preferences, and in Accounts, log in with your Apple ID.
 
-You can get Xcode from the App Store. If you have never used Xcode before, you will need to open the Xcode preferences, and in Accounts, log in with your Apple ID.
+### retroarch-apple-deps (optional but recommended)
+
+RetroArch optionally will automatically link with supporting libraries (including MoltenVK) that are provided by the retroarch-apple-deps repo. By default Xcode will look for these dependencies in `/usr/local/share/retroarch-apple-deps`.
+
+To get retroarch-apple-deps, run:
+
+```shell
+git clone https://github.com/warmenhoven/retroarch-apple-deps.git retroarch-apple-deps
+sudo ln -s $PWD/retroarch-apple-deps /usr/local/share
+```
 
 ## Fetching the code
 
@@ -109,18 +95,22 @@ There are several Xcode projects and workspaces in the `pkg/apple` directory in
 | Xcode&nbsp;Project/Workspace&nbsp;File&nbsp;Name | OS support | Purpose |
 -----------------------------------------|-|-
 | `RetroArch.xcworkspace`      | 10.13+ | The primary workspace for the latest Metal build. Most active development happens here. |
-| `RetroArch.xcodeproj`        | 10.6+ | The current non-Metal build. |
-| `RetroArch_PPC.xcodeproj`    | 10.5+ | Building for PowerPC processor-powered Macs. |
 | `RetroArch_Metal.xcodeproj`  | 10.13+ | The project for the latest Metal build. You can use this directly but typically it's preferred to use the Workspace. |
+| `RetroArch.xcodeproj`        | 10.6+ | The outdated non-Metal build, only for Intel processor-powered Macs. |
+| `RetroArch_PPC.xcodeproj`    | 10.5+ | Building for PowerPC processor-powered Macs. |
 | `RetroArch_OSX107.xcodeproj` | 10.7+ | An old development line that is no longer in use. |
 
 ### Building RetroArch separately
 
-Open Xcode. Open your chosen project file in the Xcode IDE and build (**&#8984;-B**) and run (**&#8984;-R**) it there.
+Open Xcode. Open your chosen project file in the Xcode IDE and build (**&#8984;-B**) and run (**&#8984;-R**) it there. The default scheme should be `RetroArch` and that is what is used for building the DMG image available on the buildbot.
+
+## Core Compilation (optional)
+
+RetroArch on OSX by default will be configured to download cores from the buildbot; you do not need to build the cores yourself.
 
-## Core Compilation
+### libretro-super (deprecated)
 
-The easiest way to build all the cores is to use libretro-super.
+If you choose to build the cores yourself, the easiest way to build all the cores is to use libretro-super.
 
 To build all cores for OSX, run
 
@@ -135,3 +125,21 @@ In case you only want to build one and/or more cores instead of all, you can spe
 ```
 
 Once finished, you can find the libretro cores inside directory `dist/osx`.
+
+### GitLab CI mimicry
+
+Cores on the buildbot are built using the GitLab CI infrastructure. Each core provides its own `.gitlab-ci.yml` file with instructions for how to build it. Almost all cores reference one of the [CI Templates](https://git.libretro.com/libretro-infrastructure/ci-templates). Between the `.gitlab-ci.yml` file and the templates, you should have complete instructions for how to build each core.
+
+## Store Builds
+
+### Steam Build
+
+Building for Steam differs from the normal app build in two ways: the scheme is `RetroArchSteam`, and it requires bundling [mist](https://git.libretro.com/libretro-steam/mist) and linking against libmist. Simply download the latest artifacts for mist from GitLab, and set the `MIST_PATH` variable in the Xcode project with its location.
+
+Once the Steam app is built, it is no different from the app available in the Steam store, and will communicate with Steam to fetch cores and update presence.
+
+### Mac App Store Build
+
+Building for the Mac App Store requires being logged into Xcode with the Apple Developer account associated with the Bundle ID for the app. The app also builds with Push Notification and CloudKit entitlements for the iCloud cloud sync driver. Once all of the signing and entitlements are set up, creating the build is simply changing the scheme to `RetroArch AppStore`.
+
+There is an automated [fastlane](http://docs.fastlane.tools) script available in pkg/apple/fastlane that will update the build numbers and upload the built prodduct to TestFlight using an [App Store Connect API Key](http://docs.fastlane.tools/app-store-connect-api/).
diff --git a/docs/guides/generating-retroarch-logs.md b/docs/guides/generating-retroarch-logs.md
@@ -16,6 +16,8 @@ The answer to this dilemma involves "logs", which RetroArch and other libretro s
 5. (optional) Adjust "Frontend / Core Logging Level" to get more or less detailed information
 6. (optional) Activate "Timestamp Log Files" if you don't want to overwrite the log at each startup
 
+This will place the logs in the System Events Logs directory, visible in the "Directory" settings.
+
 ### Generating Logs in Lakka
 [Please see the Troubleshooting Lakka doc](http://www.lakka.tv/doc/Troubleshooting-Lakka/).
 
@@ -54,10 +56,11 @@ The answer to this dilemma involves "logs", which RetroArch and other libretro s
 
 ### Generating Logs in OS X
 1. Open a console window with the OS X "Terminal" app.
-2. Navigate to the RetroArch folder using the `cd` command.
-3. Start RetroArch in 'verbose' mode with this command:<br />
- `retroarch -v --log-file ~/retroarch.log` or `retroarch -v >> ~/retroarch.log 2>&1`
-4. Once you exit RetroArch, a file called `retroarch.log` should be stored in your home directory.
+2. Navigate to the RetroArch.app folder using the `cd` command.
+3. Inside the RetroArch.app folder, navigate to the Contents/MacOS filter.
+4. Start RetroArch in 'verbose' mode with this command:<br />
+ `./RetroArch -v --log-file ~/retroarch.log` or `./RetroArch -v >> ~/retroarch.log 2>&1`
+5. Once you exit RetroArch, a file called `retroarch.log` should be stored in your home directory.
 
 ### Generating Logs in Android
 There is a range of variation in the logging systems available to Android device depending on the combination of hardware and operating system in use. There are two general approaches to generating logs in Android: tethering to a PC via a USB cable or using a `logcat` app.
@@ -86,8 +89,11 @@ _Based on Stackexchange posts by Leandros and Nicolas Raoul._
 #### Generating Logs via Android App
 Gathering log files in Android requires a third-party app that can interface with the `logcat` system. Many free apps are available via Android's "Play Store" system. You can still generate RetroArch logs from the menu.
 
-### Generating Logs in iOS
-You can generate RetroArch logs from the menu, and App Store installations can opt to send crash logs to the RetroArch developers for analysis, if desired.
+### Generating Logs in iOS and tvOS
+
+You can generate RetroArch logs from the menu, described above. Logs by default go into the RetroArch/logs directory accessible through the Files app on iOS or the webserver on tvOS.
+
+App Store installations can opt to send crash logs to the RetroArch developers for analysis, if desired. This can be configured through the Settings app in "Privacy & Security" under "Analytics & Improvements" by turning on "Share With App Developers".
 
 ### Generating Logs with Nintendo Switch