From iPhone Development Wiki
Revision as of 20:13, 8 September 2014 by Mringwal (talk | contribs) (Creating a Project)
Jump to: navigation, search

This page contains instructions for installing Theos and preparing a new project.


$THEOS is the directory where Theos is installed on your machine. It is platform dependent.


  • A modern operating system (Mac OS X, iOS [jailbroken], Windows [using Cygwin], and most variants of Linux should work) with the following set of utilities:
    • curl
    • git
    • make
    • openssh
    • perl
    • rsync
    • python (if on Windows)
  • Some form of a toolchain or official SDK
  • Access to a terminal emulator and some knowledge of how to use it
  • Objective-C knowledge

More detailed explanations of these requirements are given in the next section, and are dependent on the environment you use.

Setting Up Dependencies

For Mac OS X

Mac OS X comes with most of the necessary tools (subversion, curl, and perl) by default. You will still need compilation tools and the iOS SDK, and the easiest way to obtain both of these is by installing Xcode from the App Store. Consider installing Command Line tools for Xcode as well, as it contains numerous tools that complement Xcode.

For Linux

Like OS X, most distributions come pre-packaged with the aforementioned tools. On Debian-based distros, APT can be used to install the tools like so:

sudo apt-get install git perl curl

If your distro uses RPM, the process is very similar.

For iOS


Theos as a package depends on bash, grep, dpkg, coreutils, ldid, rsync and make, so the utilities mentioned in the requirements are automatically installed.

Install a Toolchain:

See On-device toolchains for details.

Also for Linux and iOS (and other operating systems other than Mac OS X): Retrieving SDKs

If you aren't using OS X, you must download an iOS SDK. See Retrieving SDKs for details on this.

Take the SDK and put it in $THEOS/sdks (if it does not exist, create it), with a folder name like iPhone7.0.sdk. As of version 0.9.523, Theos accepts multiple SDKs in that folder.

Each SDK folder should have these folders: Developer, System, usr; and these files: ResourceRules.plist, Entitlements.plist, SDKSettings.plist.

Note that if no SDKs are provided, the following error will be displayed (also noted in the "Troubleshooting" section below):

".../theos/makefiles/targets/darwin-arm/ *** first argument to 'word' function must be greater than 0. stop."

Installing Theos

On Mac OS X or Linux

  1. Open a terminal window.
  2. Choose a location for Theos to be installed. If you are unsure, a good choice is /opt/theos.
    export THEOS=/opt/theos
    • If you chose a location outside of your user's home directory, you will probably need to run some or all of the following commands with root permissions.
  3. Download the latest version of Theos:
    • Using git:
      git clone git:// $THEOS
    • Alternatively, you can use svn, if you prefer:
      svn co $THEOS
  4. Download ldid to $THEOS/bin:
    git clone git://
    cd ldid
    git submodule update --init
    cp -f ./ldid $THEOS/bin/ldid
  5. Add Theos environment variables to your ~/.bash_profile (or the equivalent for your shell). Open ~/.bash_profile (create it if it does not exist) in your favorite editor and add this on the last line, replacing the device name with your own device's name (replacing spaces with dashes) or its IP address:
    export THEOS=/opt/theos
    export THEOS_DEVICE_IP=example.local THEOS_DEVICE_PORT=22
    (To get your device's IP address, go to settings, Wi-Fi, then press the i on the network you are currently connected on, and then see where it says IP Address. This is what you type in, if you don't want to use a device name.)
    Load this into the shell with . ~/.bash_profile, or close the terminal window and launch a new one.
  6. As the substrate library does not come installed on these platforms nor bundled with Theos, copy /Library/Frameworks/CydiaSubstrate.framework/CydiaSubstrate from the device to your local $THEOS/lib folder and rename it to libsubstrate.dylib. (If you don't do this step, or if you use an old version of Substrate, or if something else goes wrong, you may get one of these error messages.)

On iOS

(On your iOS device:)

  1. Create a file at /etc/apt/sources.list.d/ containing the following line:
    deb iphone main
  2. Create a file at /etc/apt/sources.list.d/ containing the following line:
    deb ./
  3. Make sure APT 0.6 Transitional Package is installed before doing this step. As root, issue these commands (using either SSH or MobileTerminal):
    apt-get update
    apt-get install perl net.howett.theos

Creating a Project

Theos lets you create new projects based on templates using the New Instance Creator (NIC). You do not need to be root to do this step, nor should you be. Start the NIC wizard using the following command:


NIC will prompt you for all the necessary information before creating a project. Please make sure that the path to your current directory doesn't have spaces in it.

(If you get an error message saying "Illegal instruction: 4", see this troubleshooting advice.)

NIC Example

Here is an example of what you will see when using the NIC to create a project (with user input shown in bold):

$ $THEOS/bin/
NIC 1.0 - New Instance Creator
  [1.] iphone/application
  [2.] iphone/library
  [3.] iphone/preference_bundle
  [4.] iphone/tool
  [5.] iphone/tweak
Choose a Template (required): 1
Project Name (required): iPhoneDevWiki
Package Name [com.yourcompany.iphonedevwiki]: net.howett.iphonedevwiki
Authour/Maintainer Name [Dustin L. Howett]:              
Instantiating iphone/application in iphonedevwiki/...

The above will create a folder ./iphonedevwiki in the current working directory - make sure you have permissions to create a folder.

Making your Project

When you have finished developing your tweak/app, you may want to distribute it, either to your own device, or to an external source.

When you are making the project, type this in the terminal, in your project folder:

$ make package 

This will generate a .deb file, which you can distribute to people or to repositories.

If you want to install the latest package, type:

$ make install

It will then ask for your root password and install the .deb onto your device. If you haven't changed your root password, the default password is alpine. Make sure you change your root password, which you can do with passwd (see "Root Password How-To" on the Cydia homepage for detailed instructions).

Further Reading

You can learn how to do Makefiles with theos on Start over there.

For general advice on beginning development for jailbroken iOS, see Getting Started.

Getting Help

If you need further assistance, or if you have other questions about Theos itself, feel free to connect to #theos on using your preferred IRC client. If you don't already have a preferred IRC client, you can learn more here: IRC.


Missing SDK

If you get this message:

".../theos/makefiles/targets/darwin-arm/ *** first argument to 'word' function must be greater than 0. stop."

It means that you don't have SDKs in $THEOS/sdks. See this section.

Missing substrate library

If you get either of these messages:

Bootstrapping CydiaSubstrate...
Compiling iPhoneOS CydiaSubstrate stub... default target? failed, what?
cp: cannot stat ‘_out/*’: No such file or directory
cp: cannot stat ‘libsubstrate.dylib’: No such file or directory


ld: warning: ignoring file .../theos/lib/libsubstrate.dylib, file was built for armXXX which is not the architecture being linked (armYYY): .../theos/lib/libsubstrate.dylib

It means that you are missing the substrate library to link with or you have an old version of it. Either way, get an up to date version from the device at /Library/Frameworks/CydiaSubstrate.framework/CydiaSubstrate, copy it to your local $THEOS/lib folder and rename it to libsubstrate.dylib.

Architecture (partial) incompatibility

If you get this error while attempting to run the Theos New Instance Creator (NIC):

Illegal instruction: 4

It probably means you are using versions of tools that work on older devices but not on new ones. Read more on the issue here.

It usually affects perl and rsync (installed from the default sources), so to fix this, run these commands as root on the device using SSH or MobileTerminal:

sed -i'' 's/\x00\x30\x93\xe4/\x00\x30\x93\xe5/g;s/\x00\x30\xd3\xe4/\x00\x30\xd3\xe5/g;' /usr/bin/perl; ldid -s /usr/bin/perl
sed -i'' 's/\x00\x30\x93\xe4/\x00\x30\x93\xe5/g;s/\x00\x30\xd3\xe4/\x00\x30\xd3\xe5/g;' /usr/bin/rsync; ldid -s /usr/bin/rsync