Skip to content

Usage

Jump to bottom
Kabir Oberai edited this page Dec 22, 2018 · 14 revisions

General usage

Make sure that you have installed Theos Jailed before following this guide.

  1. Extract and decrypt your target app. Save as a .ipa
  2. Change to the base directory for your tweak (eg. cd ~/Desktop)
  3. Run nic.pl and choose the jailed template (or run nic.pl -t iphone/jailed to choose it automatically)
  4. Enter a name and bundle ID for your tweak
  5. Enter an absolute or relative path to your decrypted .ipa file
  6. Change into your new tweak directory (eg. cd ~/Desktop/mytweak)
  7. Edit Tweak.xm as necessary
  8. Run make info and follow the instructions to create a Provisioning Profile
  9. Run make package install [PROFILE=<your.bundle.id | file.mobileprovision>]. Omit PROFILE=… to use Xcode's Wildcard App ID

Note: Unless specified otherwise, the rest of this page requires that you cd into your tweak's root directory before running any commands.

Using .app files

As input

Simply pass in a .app file as the value of the IPA variable

As output

Set OUTPUT_NAME = <name>.app at the top of your Makefile

Adding Resources

If you want to add custom resources to your project, you can create a Resources folder, and add any files to it. If you add an Info.plist file to Resources, its keys will be merged with the app's Info.plist. However, since the most common use of merging an Info.plist is setting a custom display name and bundle ID, you can also do that using the DISPLAY_NAME and BUNDLE_ID variables.

Since Theos Jailed merges the Resources folder with the app's root directory, it will override any existing files with a clashing name. Due to this, it is highly recommended that you create a <tweak name>.bundle folder in Resources to add custom files. To access your tweak's bundle, add the following to the top of Tweak.xm:

NSBundle* const kTweakBundle = [NSBundle bundleWithPath: [[NSBundle mainBundle] pathForResource: @"tweak name" ofType: @"bundle"]];

And to access files inside the bundle, use:

[kTweakBundle pathForResource: @"name" ofType: @"extension"]

Distributing your tweak

When you're happy with what you've made and want to distribute the ipa, run make package FINALPACKAGE=1. This will increase compression and remove any debug-specific addons such as Cycript (note that you can explicitly re-enable this using TWEAK_NAME_USE_CYCRIPT=1).

Using builtin addons

The following variables can be set either in Makefile or when running the make command (make [...] VARIABLE=value). Replace TWEAK_NAME with your tweak's name, spelled exactly the way it is in Makefile. Run grep TWEAK_NAME Makefile to see the tweak name.

Cycript

Set TWEAK_NAME_USE_CYCRIPT=1 to be able to remotely attach to Cycript using cycript -r hostname:31337.

Fishhook

Set TWEAK_NAME_USE_FISHHOOK=1 to use fishhook. Remember to #import <fishhook.h> as well.

FLEX

Set TWEAK_NAME_USE_FLEX=1 to use FLEX.

UIDebuggingInformationOverlay

Set TWEAK_NAME_USE_OVERLAY=1 to use UIDebuggingInformationOverlay. If you dismiss the overlay window, you can enable it again by tapping the status bar with two fingers.

Extensify Exo

Set PACKAGE_FORMAT=exo to package your project as an Extensify Exo instead of a .ipa.

Note: The FLEX and Cycript addons are themselves Theos Jailed tweaks that are automatically triggered. If you want to modify them, you may do so by editing the respective tweak in the addons directory in the root of this repository, and then running make.

Injecting a Cydia tweak

  1. Download the tweak as a .deb file. To find a website that lets you do this, search Google for something like "Cydia Updates"
  2. Unpack the .deb file, using the command dpkg-deb -x file.deb destination
  3. Extract and decrypt the app targeted by the Cydia tweak. Save as a .ipa
  4. Create a new Theos project with the jailed template, using the decrypted .ipa
  5. Copy the unpacked tweak at destination/Library/MobileSubstrate/DynamicLibraries/tweak-name.dylib to the root folder of your project, replacing tweak-name with the name of the tweak you downloaded
  6. Add TWEAK_NAME_INJECT_DYLIBS = tweak-name.dylib to the top of Makefile. Doing this still compiles Tweak.xm, so you can add your own changes too
  7. Follow step 9 and 10 of General usage

Changing the install path of the the dylib

You may want to change the install location of tweak-name.dylib in the app directory (eg. Foo.app/MyFrameworks instead of Foo.app/Frameworks). To do this, set the COPY_PATH variable to the path you want in your Makefile. The default value for this is Frameworks. If you do this, you will also need to update any dependency's location respectively. In this example, you'd need to replace Frameworks with MyFrameworks in steps 3 and 4 of Adding dependencies.

Adding dependencies

Many tweaks require external dependencies. To use one, you must first fix the install name of the dependency and the libraries it links against.

  1. Download and extract the dependency .deb, similar to how you downloaded the tweak
  2. Create a Resources directory inside your project's root directory
  3. Create a Frameworks directory inside the Resources directory, and add the dependency to that
  4. Run install_name_tool -id @rpath/dependency.dylib Resources/Frameworks/dependency.dylib
  5. Run otool -L tweak-name.dylib to see the current linked path to the dependency
  6. Run install_name_tool -change /linked/path/to/dependency.dylib @rpath/dependency.dylib tweak-name.dylib

Note: Some dependencies (such as rocketbootstrap and uasharedtools) do not work on jailed devices, and thus tweaks that require them will not work. If you want to inject a ++ tweak, your best option is using ppsideloader, which is specifically made for that purpose.

Using frameworks

External frameworks may be of two types: static and dynamic. To find out which your framework is, run the following command:

file Foo.framework/Foo | grep -q "Mach-O dynamically linked shared library" && echo "Dynamic" || echo "Static"

Static frameworks

  1. Copy the .framework into your project's root directory
  2. Open Makefile in your favourite text editor
  3. Add TWEAK_NAME_FRAMEWORKS = Foo, replacing Foo with the name of your framework. If any additional frameworks are required, add them here too
  4. Add any required libraries to TWEAK_NAME_LIBRARIES below the FRAMEWORKS line. For example, if I wanted to add libxyz.tbd to my project, I would add the line TWEAK_NAME_LIBRARIES = xyz
  5. Import your framework in Tweak.xm using #import <Foo/Foo.h>

Dynamic frameworks

  1. Dynamic frameworks are only supported in iOS 8 and above. Add TARGET_IPHONEOS_DEPLOYMENT_VERSION = 8.0 to the beginning of your makefile
  2. Follow all the steps in Static frameworks, but replace TWEAK_NAME_FRAMEWORKS with TWEAK_NAME_EMBED_FRAMEWORKS in step 3, and use the framework's path instead of its name (Foo.framework instead of Foo)

Dylib files

  1. Follow steps 1 to 4 of Static frameworks, but replace TWEAK_NAME_FRAMEWORKS with TWEAK_NAME_EMBED_LIBRARIES in step 3, and use the dylib's path instead of its name (libfoo.dylib)
  2. Import your framework in Tweak.xm, using #import <foo.h>

Note: To add a framework to a subdirectory inside your project folder, you must add -Fpath/to/subdirectory to TWEAK_NAME_CFLAGS and TWEAK_NAME_LDFLAGS, and for a dylib add -Lpath/to/subdirectory to TWEAK_NAME_LDFLAGS. You need not do this if you place the framework/dylib in the project's root directory because that is already added by default.

Clone this wiki locally