Developer Documentation

Create tweaks and extensions for roothide Bootstrap

Introduction

Both rootful and rootless tweaks aren't out-of-the-box compatible with roothide. To develop tweaks for roothide Bootstrap, you need to create them specifically with roothide support in mind.

This guide will help you get started with developing roothide-compatible tweaks using Theos with roothide support.

Prerequisites

Required Tools

  • Theos with roothide support: Modified version of Theos that supports roothide development
  • macOS: For building tweaks (or use GitHub Actions)
  • Xcode: Full Xcode app from the App Store
  • Git: For version control and cloning repositories

Installing Theos with roothide Support

Install or update Theos with roothide support using the official installer:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/roothide/theos/master/bin/install-theos)"

Important: If you encounter errors from a previous Theos installation, completely remove Theos before reinstalling.

Key Differences from Traditional Tweaks

Developing for roothide requires understanding several key differences:

1. File Paths

roothide uses different file paths compared to traditional jailbreaks. Your tweak needs to use roothide-specific paths for resources, preferences, and data storage.

2. Injection Method

roothide uses a different injection mechanism. Tweaks are injected into applications on-demand, not system-wide by default.

3. No SpringBoard Injection

Injection into SpringBoard (com.apple.springboard) or system daemons is not supported. Your tweaks should target specific applications instead.

4. Preference Bundles

Preference bundles need to be configured differently for roothide. Ensure your preference bundles use roothide-compatible paths.

Creating Your First Tweak

Step 1: Create a New Tweak Project

Use Theos to create a new tweak project:

theos new tweak MyTweak

Follow the prompts to configure your tweak project.

Step 2: Configure Makefile

Your Makefile should include roothide-specific configurations. Here's a basic example:

ARCHS = arm64 arm64e
TARGET = iphone:clang:15.0:15.0

include $(THEOS)/makefiles/common.mk

TWEAK_NAME = MyTweak

MyTweak_FILES = Tweak.x
MyTweak_CFLAGS = -fobjc-arc

include $(THEOS)/makefiles/tweak.mk

Step 3: Write Your Tweak Code

Write your tweak logic in the Tweak.x file (or Tweak.m for Objective-C). Use roothide-compatible APIs and paths.

%hook SomeClass
- (void)someMethod {
    %orig;
    // Your tweak code here
}
%end

Step 4: Build Your Tweak

Build your tweak using Theos:

make package

The built .deb package will be in the packages directory.

roothide-Specific Considerations

File System Paths

Use roothide-specific paths in your tweak:

  • Bootstrap path: /var/jb (similar to rootless, but roothide-specific)
  • Preferences: Use roothide-compatible preference paths
  • Resources: Store resources in roothide-accessible locations

Application Targeting

Since SpringBoard injection isn't supported, design your tweaks to work within specific applications. Use the App List feature to enable injection for target applications.

Preference Bundles

Create preference bundles that work with roothide Bootstrap. Ensure your preference bundle's Info.plist and code use roothide-compatible paths.

Converting Existing Tweaks

If you have existing tweaks (rootful or rootless), you can convert them to roothide using roothide Patcher.

Using roothide Patcher

  1. Clone the roothide Patcher repository
  2. Run the patcher on your existing tweak's .deb file
  3. The patcher will modify paths and code to be roothide-compatible
  4. Test the converted tweak with roothide Bootstrap

Note that automatic conversion may not work for all tweaks. Some tweaks may require manual modifications.

Testing Your Tweaks

Installation

  1. Build your tweak into a .deb package
  2. Transfer the .deb to your iOS device
  3. Install using a package manager (Sileo or Zebra) or manually with dpkg
  4. Enable tweak injection for your target application in roothide Bootstrap
  5. Launch the target application to test

Debugging

Use standard iOS debugging tools:

  • Console logs for debugging
  • Xcode's debugging tools (if available)
  • Device logs via Console.app on macOS

Best Practices

  • Test Thoroughly: Test your tweaks on multiple iOS versions and devices
  • Handle Errors Gracefully: Ensure your tweak doesn't crash if roothide isn't available
  • Use roothide APIs: Use roothide-specific APIs and paths when available
  • Document Your Tweak: Provide clear documentation for users
  • Follow Theos Conventions: Follow standard Theos project structure and conventions
  • Consider Compatibility: Design your tweak to work with both roothide and potentially other frameworks if possible

Resources & Documentation

Official Resources

Community Resources

Example Projects

Check out existing roothide-compatible tweaks on GitHub for examples and best practices. Look for tweaks in the roothide ecosystem to see how others have implemented roothide support.

Getting Help

If you need help developing tweaks for roothide:

  • Join our Discord server for developer discussions
  • Check existing GitHub Issues for similar problems
  • Review the FAQ for common development questions
  • Study the roothide Bootstrap source code for implementation examples

Related Pages

Learn more about roothide Bootstrap: