Flex to mobile substrate guide

This is just copying this reddit post which has since been taken down.

I'm making this guide as a way to show the basics of tweak development, how a tweak works, and how to set up your computer for tweak development. This guide requires no programming experience, as it will make a very simple tweak.


Many of you are familiar with the familiar tweak/app Flex (or Flex 2). It allows you to make and share tweaks on your phone with a nice UI, and it's very easy to use. What some people may not realize, though, is that you are actually making iOS tweaks. You aren't making neat little mods that have been branded "tweaks." Those are real iOS tweaks, just like ones you'd download from Cydia. In this guide, I'll show you how one would go about making a simple tweak, and we'll make one based off of a Flex tweak to walk you through it.

Picking our Flex tweak

First, let's pick a Flex tweak. For this guide, I chose the SpringBoard tweak "Hide Date in Lockscreen" for iOS 7. So, if you have Flex, I recommend you just download it and look at it. If you don't own Flex, don't sweat it, just check out this screenshot. As you can see, the Target Class (the class that we'll be hijacking) is SBLockScreenViewController, the Target Method is -(BOOL) _shouldShowDate, and we want to override that with FALSE. I chose this tweak because it only has one method, and it's a boolean, so it will be very easy to tweak.

Installing Theos

Now, let's set up Theos. This guide is made for Mac, but if you have a Linux computer, you can set up Theos with this guide, and if you're on Windows, check out this.
For Theos to work, we'll need to set up the things it needs. First of, install Xcode from the App Store if you haven't already, and install the command line tools in Preferences>Downloads>Command Line Tools (http://imgur.com/2sFyPdP).

Next, you'll need dpkg (to compile your tweaks to a deb). The easiest way to get dpkg is to install MacPorts, and then running in Terminal (/Applications/Utilities/Terminal.app) sudo port install dpkg

Alright, now let's get Theos installed. start off by opening a fresh Terminal window. Don't close this window throughout the install process. First, run export THEOS=/opt/theos. Now, I would cd to a directory were you want to download things. If you don't know what that means, just run cd ~/Downloads. After the install process is done, you can delete the stuff downloaded to the Downloads folder. Next run git clone git://github.com/DHowett/theos.git $THEOS. After that, run the following commands one after another:

git clone git://git.saurik.com/ldid.git
cd ldid
git submodule update --init
cp -f ./ldid $THEOS/bin/ldid

Alright, Theos is installed! Congratulate yourself!

EDIT: There's another step! We need headers! Headers are like libraries or dependencies, generic pieces of code that a lot of tweaks can all use just by including them in the code. For this particular tweak, we only need substrate.h, but I'm going to load you guys up with lots of headers for the future. Go ahead and download this zip file. Those are a bunch of headers from rpetrich's GitHub, with a few lines commented out, since those lines cause problems when not commented out. Unzip that file, and put all of the files and folders inside of "include" into /opt/theos/include/. Now you have your headers!
Also install libsubstrate.dylib, which you can download from here, and put it in /opt/theos/lib/.

Making a project

Before we make our project, we need to pick where the project gets made. We do this using cd. I want my project to get installed to by Documents folder, so I'll run cd ~/Documents Now, it's time to make our tweak layout. We do this by running /opt/theos/bin/nic.pl in Terminal. It will ask what you want to make. Type 5 and hit enter, because we want a tweak. It will then as for a project name. You can choose whatever you want, but for this project, I'll choose "NoLSDate." Then, it will ask for a package id. Just choose whatever you want. I'll choose "com.jimmyneutron.nolsdate". Then it'll ask for an Author/Maintainer name. Just enter your name. After that, it will ask for the "MobileSubstrate Bundle filter." Type com.apple.springboard, since it's a tweak for SpringBoard (as can be seen in Flex). Finally, it will ask for a list of process to kill on installation. Type SpringBoard backboardd Now it will make a blank project.

Writing the tweak

In Finder, open the folder for your blank project. There should be a file called "Tweak.xm." That's where we write our code. Now, this tweak will be very short, but it will still show you the basics of making a tweak. Now look back at the screen shot of Flex. You can see that the Target Class is SBLockScreenViewController, so we're going to "hook" into that and hijack it's methods (think like a WinterBoard theme, you give the app's bundles id, and then hijack it's files, normally icons). So, the first line of code will be:

%hook SBLockScreenViewController

Now, we need to state which method we'll be overriding. In this case the Target Method is -(BOOL) _shouldShowDate. That's our second line of code:

-(BOOL) _shouldShowDate {

The "{" is to enclose the stuff we're doing to that boolean.
Now, we need to say what we're overriding it with. In this case, you can see in Flex that the Return Value is "FALSE", so our third line of code is:

return FALSE;

The ";" denotes the end of that return value and line. Our fourth line is just going to say that we're done with -(BOOL) _shouldShowDate, so it's simply the closing bracket:


Now, we need to denote the end of our hooking into SBLockScreenViewController, by making our fifth line of code:


You can compare your Tweak.xm to mine on GitHub.
Congrats! You just wrote a tweak!


Now, what we need to do is compile it and test it out. Open another Terminal window, and run the command export THEOS=/opt/theos. Next, we need to run export THEOS_DEVICE_IP= THEOS_DEVICE_PORT=22 but replace "" with your device's IP address for SSH, and "22" with your SSH port (if you never went in and changed it, then it's 22. Now, run cd /path/to/nolsdate/ where /path/to/nolsdate is the path to your project folder. Now comes the moment of truth. Run make package install and theos should compile the tweak, build it into a deb, and install it on your iDevice within about 10 seconds!

Congratulations! You just made and deployed a tweak! To uninstall it, just open Cydia, and the tweak should show up at the top of the Changes tab, where you can uninstall it.
I hope you like this guide! Please leave any questions, comments, or suggestions in the comments. I appreciate the feedback. In the future, I plan to add to this project, making a preference bundle and maybe other types of strings besides booleans.

Edit: For some more simple, beginner project (but more advanced than this tweak) with comments on every line explaining what's going on, check out these projects by /u/Codyd51

Some additional help/some more great guides can be found here and here.

Alright, A lot of you have been asking about Windows, and /u/_spinward has linked me to a guide by coolstar, which can be seen here. Please follow that, and ask for help on IRC, because I don't know much about installing Theos on Windows. (link dead)