How to compile theos tweak
Compiling tweaks using Theos libraries can pose a challenge for newcomers, often leading to numerous errors and eventual compilation failures. Searching for solutions online in such scenarios may not yield satisfactory results. This tutorial aims to navigate you through the compilation process of tweaks for both rootless and rootful environments, resulting in the creation of ready-to-install DEB packages.
A significant portion of the jailbreak community depends on open-source jailbreak tweaks. These tweaks serve not only as inspiring demonstrations of iOS system modifications but also as extensive knowledge bases for aspiring tweak developers. Many of these tweaks need to be compiled using Theos, a cross-platform build system for creating iOS tweaks.
The Theos libraries are easily installable on multiple platforms, such as iOS devices, macOS, Linux, and Windows PCs. This flexibility allows developers to compile jailbreak tweaks effortlessly across a variety of operating systems. In this guide, we will provide a step-by-step walkthrough for compiling a tweak with Theos and distributing DEB packages for installation.
In this tutorial on compiling a tweak with Theos, we'll be utilizing the source code of the Sushi tweak. Sushi is crafted to elevate your media control experience on jailbroken devices. It introduces a customizable banner, inspired by Dynamic Island, that smoothly transitions into a media control view through animations whenever the currently playing song changes.
Sushi tweak can be compiled with Theos for both rootless and rootful jailbreaks running from iOS 13 up to iOS 16. Dopamine 2 and Palera1n are also supported.
How to compile a tweak with theos for iOS
To compile a tweak with Theos, it's recommended to utilize the latest version of the library compatible with Sonoma 14.3.1. If you intend to ensure compatibility with iOS versions predating 14.0, a downgrade to Xcode 11.7 is necessary. Nonetheless, for our present task, we'll be using Xcode 14.3.1. It's worth noting that Xcode 15 restricts the compilation of most jailbreak tweaks.
Therefore, this newer toolchain does not support building for the old ABI. If you want to maintain support for earlier versions, you can grab the toolchain from an earlier Xcode release and switch between it and the newer toolchain as desired by setting the Xcode command line tools version.
To compile a jailbreak tweak with theos, follow the steps:
Step 1. Install theos on your PC, Mac, or iOS device following our guide.
Step 2. Install iPhoneOS16.4.sdk by downloading Xcode 14.3.1 or Xcode 11.7 directly from Apple servers. You will need to authenticate with your Apple ID to download.
Step 3. Open the terminal app and extract Xcode_14.3.1.xip with the following command. After extraction, rename the app to not conflict with your primary installation of Xcode.
xip -x Xcode_14.3.1.xip
Step 4. Move Xcode_14.3.1.app to the Applications folder.
Step 5. Change your selected Xcode command line tools version. The following command will temporarily change your command line tools version for just this terminal session.
export DEVELOPER_DIR=/Applications/Xcode_14.3.1.app/Contents/Developer
or permanent
sudo xcode-select -switch /Applications/Xcode_14.3.1.app/Contents/Developer
If you need to use the latest Xcode toolchain from the command line, use --reset:
sudo xcode-select --reset
Step 6. Clone the Sushi tweak repository from GitHub to your computer.
git clone https://github.com/Skittyblock/Sushi
Step 7. Sushi tweak uses some additional classes for use in preference bundles. Clone SkittyPrefs from GitHub to the "prefs" folder inside the "Sushi" folder.
cd Sushi && cd prefs && git clone https://github.com/Skittyblock/SkittyPrefs
Step 8. Return to the main "Sushi" folder in terminal app.
cd ..
Step 9. Create SPM config by executing this command.
make spm
Step 10. Remove object and executable files. Please be aware that you must run the "make clean" command when switching between rootful and rootless builds.
make clean
Step 11. Compile Sushi tweak and generate a rootless DEB package for Dopamine or Palera1n jailbreaks. For rootful build remove this option "THEOS_PACKAGE_SCHEME=rootless".
make do THEOS_PACKAGE_SCHEME=rootless
Step 12. Once the compilation process is complete, you'll find the DEB packages (arm, arm64) of the tweak created with Theos inside the "packages" folder located in "Sushi" folder.
Common theos compilation errors
The primary challenge encountered while compiling tweaks with Theos often stems from using an incompatible version of Xcode. For instance, Xcode 15 typically comes with the latest release of the iPhone OS SDK, such as iPhoneOS17.2.sdk. However, tweaks commonly need to be compatible not just with iOS 16 but also with earlier versions like iOS 13, iOS 14, and iOS 15. In such cases, installation of older release of Xcode 11.7 becomes a necessity.
The following errors may appear when running wrong Xcode version:
- ld: warning: -multiply_defined is obsolete
- ld: warning: ignoring duplicate libraries: '-lc++'
- ld: framework 'MediaRemote' not found
- clang: error: linker command failed with exit code 1 (use -v to see invocation)
- make[4]: *** [/Users/.../theos/makefiles/instance/library.mk:52: /Users/.../.../.theos/obj/debug/arm64e/....dylib] Error 1
- error: 'groupTableViewBackgroundColor' is deprecated: first deprecated in ios 13.0 [-Werror,-Wdeprecated-declarations] return [UIColor groupTableViewBackgroundColor];
- .../SDKs/iPhone017.2.sdk/ System/Library/Frameworks/ UIKit.framework/Headers/UIInterface.h:247:48: n
