Tutorial: Let's create your first tweak: PopupOnStart

In this tutorial, I will teach you to install Theos on macOS and you will create your first tweak.

Part 1: Installing Xcode and Homebrew on your Mac - provides the required dependencies for Theos to run

1) Click on the App Store Icon

2) Search for Xcode

3) Click Get and click on Install

4) Click on Launchpad

5) Click on Xcode to launch it for the first time

6) Launch your favorite Terminal application (iTerm here)

7) Run the following command: xcode-select --install

8) Xcode install window will appear asking if you would like to install the tools now

9) Click on Install

10) Click Agree when the License Agreement window appears

11) The Xcode command line tools will install

12) Click Done when the software is finished installing

13) Navigate to the following website: http://brew.sh/

14) Under ‘Install Homebrew’ copy the following command:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

15) Launch your favorite Terminal application (iTerm here)

16) Paste the following command (The script will automatically install Homebrew):
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" And Press the enter/return key

17) Now run the following command to install ldid and fakeroot: brew install ldid fakeroot

18) Now run the following command: brew install --from-bottle https://raw.githubusercontent.com/Homebrew/homebrew-core/7a4dabfc1a2acd9f01a1670fde4f0094c4fb6ffa/Formula/dpkg.rb

19) Then run: brew pin dpkg. 

You can take a break, the first part is done!

If you have an iOS 9 device or lower, follow the part 2 and skip the part 3. If you are on iOS 10, skip the 2 and follow the part 4. (iOS 9 and lower users can follow the part 4 as well, but iOS 10 users can't follow the part 2)

Part 2: Configuring SSH over Wifi (iOS 9 or lower)

Note: Don't follow these steps if you are on iOS 10, dropbear (the Yalu's SSH client) doesn't accept SSH connections over Wifi (unless you modified a plist file before sideloading Yalu on your device)

1) We will edit the bash_profile file in order to set global variables. Open your favorite terminal application and run the following command: sudo nano ~/.bash_profile

2) Enter your root password (your password will not be visible)

3) Inside nano, input (or copy paste) the following lines:

export THEOS=/var/theos
export PATH=$THEOS/bin:$PATH
export THEOS_DEVICE_IP=yourDeviceIP THEOS_DEVICE_PORT=22

4) Replace ‘yourDeviceIP” with your iPhone or iPad’s IP address (if you are connected to wifi, click on
settings, WiFi, and the informational ‘i’ to the right of the connected network. Under DHCP is IP Address
- this is your device’s IP).

5) Save and exit nano by pressing the following keys: ctrl+ x, -> Y -> Enter/Return

Congratulations! You just finished the part 2! Now, we will install Open SSH on your device.

Part 3: Install OpenSSH and change your root password (On your device)

Note: Don't follow this part if you skipped the part 2. If you already have OpenSSH installed on your device, skip this part.

1) In order to test/install tweaks on your jailbroken iPhone from the Mac, you will need to have OpenSSH installed. To keep your privacy and device safe, I will provide the steps to changing the root password (as the default password is the same for everyone).

2) Launch Cydia


3) Click on the search icon

4) Input OpenSSH and tap on it

5) Tap Install and on Confirm

6) On your Mac, open your favorite Terminal application

7) Run the following command: ssh root@yourDeviceIP (REMEMBER: yourDeviceIP is the IP address of your phone gathered in Part 2, Step 4)

8) If you see the following message “Authenticity of host cannot be established. Are you sure you want to continue connecting, yes/no, type Yes and press Enter/Return.

9) You will be prompted to enter the root SSH password. Type the following password: alpine and press Enter/Return.

10) Now, you should see ‘XXX:~ root#’

11) Run the following command to change the default root password: passwd

12) You will be prompted to input your new root password

13) You will be prompted to re-input your new root password

14) Once root password is changed, you will be back at ‘XXX:~ root#’

15) Input exit and press Enter/return to close the SSH connection between your Mac and iPhone

If you don't want to connect your device over USB SSH, skip the part 4 and follow the part 5.

Part 4: Configuring SSH over USB and change your root password (mainly for iOS 10)

1) We will edit the bash_profile file in order to set global variables. Open your favorite terminal application and run the following command: sudo nano ~/.bash_profile

2) Enter your root password (your password will not be visible)

3) Inside nano, input (or copy paste) the following lines:

export THEOS=/var/theos
export PATH=$THEOS/bin:$PATH
export THEOS_DEVICE_IP=localhost THEOS_DEVICE_PORT=2222

4) Save and exit nano by pressing the following keys: ctrl+ x, -> Y -> Enter/Return

5) Run the following command: brew install libimobiledevice


6) Run the following command: nano ~/Library/LaunchAgents/com.usbmux.iproxy.plist


7) Inside nano, input (or copy paste) the following lines

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>com.usbmux.iproxy</string>
	<key>ProgramArguments</key>
	<array>
		<string>/usr/local/bin/iproxy</string>
		<string>2222</string>
		<string>22</string>
	</array>
	<key>RunAtLoad</key>
	<true/>
	<key>KeepAlive</key>
	<true/>
</dict>
</plist>

8) Save and exit nano by pressing the following keys: ctrl+ x, -> Y -> Enter/Return

9) Run the following command: launchctl load ~/Library/LaunchAgents/com.usbmux.iproxy.plist

10) On your Mac, open your favorite Terminal application

11) Connect your device to your Mac over USB

12) Run the following command: ssh root@localhost -p 2222

13) If you see the following message “Authenticity of host cannot be established. Are you sure you want to continue connecting, yes/no, type Yes and press Enter/Return.

14) You will be prompted to enter the root SSH password. Type the following password: alpine and press Enter/Return.

15) Now, you should see ‘XXX:~ root#’

16) Run the following command to change the default root password: passwd

17) You will be prompted to input your new root password

18) You will be prompted to re-input your new root password

19) Once root password is changed, you will be back at ‘XXX:~ root#’

20) Input exit and press Enter/return to close the SSH connection between your Mac and iPhone

Yay! The part 4 is done! Configuring SSH is done. Now let's install Theos!

Part 5: Install Theos on your Mac

1) Run the following command to get to the var directory: cd /var

2) Run the following: sudo git clone —recursive https://github.com/theos/theos.git

3) Enter your root password (your password will not be visible)

4) To confirm that Theos is installed, run the following command: ls (you should see Theos in the populated list)

Done! That was easy right? :p

Part 5: Create a folder for your tweaks (on your Mac)

1) Click on Finder

2) Under Favorites click on Documents

3) Create a new folder called Tweaks

4) Exit out of Finder

Note: This was an exemple. You choose the path of your tweaks folder and you choose the name of your tweaks folder.

Part 6: Creating a tweak (on your Mac)

You are are ready to create your first tweak. Excited? :) Your first tweak will be called PopupOnStart and will simply show a popup on startup.

1) Within the Terminal, we need to navigate to the ‘Tweaks’ folder created in Part 5 Step 3

2) Run the following command: cd Documents/Tweaks

3) Now that you are in the Tweaks folder directory run the following command: $THEOS/bin/nic.pl

4) The New Instance Creator (NIC) 2.0 appears with 11 options

5) Input 11 for iphone/tweak then press Enter/Return

6) Input a name for the following field: Package Name (required)

7) Input a name for the following field: Package Name [com.yourcompany.test]

8) Input a name for the following field: Author/Maintainer Name [XXX] (Press enter without anything to select the default value, the one between brackets)


9) Leave the following field blank and press Enter/Return: [iphone/tweak] MobileSubstrate Bundle filter [com.apple.springboard]

10) Leave the following field blank and press Enter/Return: [iphone/tweak] List of applications to terminate upon installation (space-separated, ‘-‘ for none) [SpringBoard]:

11) We created a package for the tweak

12) Navigate to the package directory by running the following command: cd popuponstart (If you called your tweak PopupOnstart. If not, put the name you choose)

The project is now created. In the next part, we will code the tweak

Part 7: Code the tweak (on your Mac)

1) First, I recommend downloading and installing a text editor. A couple good ones are Sublime Text and Atom. I personally use Atom; however, neither choice is right or wrong. Both text editors are great.

2) Once you have installed your text editor of choice, click on Finder

3) Under Favorites click on Documents

4) Double click on the Tweaks folder

5) Double click on the popuponstart folder (this is the package name entered in Part 5, Step 6. The name I used is PopupOnStart)

6) Secondary or Right click on the Tweak.xm file, hover over Open with and select Other… from the drop down menu

7) The Choose Application window appears

8) Select the text editor or in the top right search field and type in the name, ex., Atom

9) When the text editor opens, delete the 34 lines of code

10) Copy and Paste the following code into the text editor (Note: UIAlertView is today deprecated. Hence the pragma lines)


%hook SpringBoard

-(void)applicationDidFinishLaunching:(id)application {
	%orig;

	#pragma clang diagnostic push
	#pragma clang diagnostic ignored "-Wdeprecated-declarations"
	
	UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Hello World!"
	message:@"This is my first tweak and I'm happy!"
	delegate:nil
	cancelButtonTitle:@"Youhou!"
	otherButtonTitles:nil];
	[alert show];
	[alert release];
	
	#pragma clang diagnostic pop
}

%end

11) Then click on File and Save

12) Exit the text editor

Part 8: Installing the Tweak (from your Mac to your device)

Here we are. This is the last part of this tutorial. At the end of this part, your first tweak will be installed on your device. 

1) Now that we created the package and input code for the tweak, we need to install in on our device to test it.

2) While still in the tweak package directory, run the following command: make do (if you closed the terminal window or no longer in the package directory, follow Section 6, Step 2 and 12)

3) You will be promoted to enter your root password twice. Press Enter/Return each time

4) Your device will respring immediately after the second password entry

5) After the respring, you will see the the popup you made: Hello World!

Congratulations! You have successful installed Theos, created a tweak, and installed/tested the tweak on your device! I wish you all the best luck in developing future tweaks to help improve the community!

Good luck future tweak developers! :D

This tutorial was originally written by /u/Phily83 to who I have learnt how to install Theos on his Mac

Newsletter

If you like this blog, don't forget to subscribe to my newsletter! You'll receive a mail when a new article is posted.