Quick Note: Build PlayTools for PlayCover

Introduction

PlayCover is a tool to help run iOS unlocked .ipa software on macOS. To understand how it is mainly used, you can refer to its official introduction.

With macOS Tahoe 26 update, some main features of PlayCover have been broken due to compatibility issues, like key map editing not showing on menubar. Fortunately, the developers did fix the issues on recent updates. But they are not correctly reflected on GitHub nightly builds, because PlayCover requires an essential dependency, PlayTools. By comparing commit logs, it could be found that every update of PlayCover comes with an update of PlayTools. But the active branch develop seems like to lock the version of PlayTools to v3.1.0 as in Cartfile.resolved, instead of the most recent commit, against the conception of nightly.

This quick note is to help developers to manually conduct the PlayTools upgrade.

Detailed Steps

You must ensure that the minor version of PlayCover and PlayTools is aligned. Otherwise, some compatibility issues would be expected.

In this article, a recommended way is conducted: go to Actions, download the latest artifact .dmg, open it and drag the app into /Applications. In this way you will no longer need to build the app yourself, but you need to de-quarantine before launching the app: run sudo xattr -r -d com.apple.quarantine /Applications/PlayCover.app in Terminal or any other command line tools you like.

Then, use command line to clone the PlayTools repository. cd to your desired workspace directory and run git clone https://github.com/PlayCover/PlayTools.git. After a successful clone, open PlayTools/PlayTools.xcodeproj in Xcode. Wait for a while until the project is completely loaded.

Click (sidebar →) TARGETS → PlayTools → Signing & Capabilities → Signing → Team, and select your team. If there is no team, click Add an Account… and log in with your Apple ID. Do the same thing for TARGETS → AKInterface.

(Optional) Press ⌘ < (command shift ,) to Edit Scheme… In Run → Info → Build Configuration, select Release and Close.

Now it’s time to build! Press ⌘ B (command B) or click menubar → Product → Build. Wait until Xcode says Build Successful. Then click menubar → Product → Show Build Folder in Finder. Double-click the folder Products and click to select Release-iphoneos. Press and hold ⌥ (option) and right-click the folder. Click Copy Release-iphoneos as Pathname.

Then run the following commands as described in official README.

BUILD_PATH=/Users/<USERNAME>/Library/Developer/Xcode/DerivedData/PlayTools-<UUID>/Build/Products/Release-iphoneos # Paste what just copied here.

echo "Converting to maccatalyst"
vtool \
    -set-build-version maccatalyst 11.0 14.0 \
    -replace -output \
    "$BUILD_PATH/PlayTools.framework/PlayTools" \
    "$BUILD_PATH/PlayTools.framework/PlayTools"

echo "Codesigning PlayTools"
codesign -fs- "$BUILD_PATH/PlayTools.framework/PlayTools"

echo "Copying to PlayCover"
rm -r "/Applications/PlayCover.app/Contents/Frameworks/PlayTools.framework"
cp -r "$BUILD_PATH/PlayTools.framework" "/Applications/PlayCover.app/Contents/Frameworks/"

Enjoy! You don’t have to reinstall existing apps because they automatically uses the new PlayTools.

Conclusion

It is a minor bug because it could be easily fixed by running carthage update to renew Cartfile.resolved at PlayCover project root directory, according to Cartfile documentation, if I guess right. So you can wait for an official fix or update.