Theos/Setup: Difference between revisions

From iPhone Development Wiki
m (→‎On iOS: Fix on-device setup link)
(Undo revision 5753 by Kritanta (talk))
Tags: Replaced Undo
(35 intermediate revisions by 11 users not shown)
Line 1: Line 1:
This page contains instructions for installing [[Theos]] and preparing a new project.
{{soft redirect|}}

== Definitions ==
This article is obsolete, and has been replaced by the [ website].

<code>$THEOS</code> is the directory where Theos is installed on your machine. It is platform dependent:
If you need historical installation instructions, you can find the last version of this article [ here].
* <tt>/opt/theos</tt> on Mac OS or Linux
* <tt>/var/theos</tt> on iOS
== Requirements ==
* 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
** dpkg (port or homebrew install on Mac OS X)
** python (if on Windows)
* Some form of a toolchain or official SDK
* Cydia [ mobilesubstrate]
* 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.
(If you've never used a command line before, it may be helpful to practice using it so that you have a better understanding of the commands you're about to run. [ This tutorial may be useful]; it's targeted toward Linux, but almost all of the information is the same for the command line on OS X and iOS.)
== 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. An alternate way to install them is via <code>xcode-select --install</code>.
Install dpkg via either <code>port install dkpg</code> or <code>brew install dpkg</code>.
If you don't already have it installed, download Cydia Substrate:
mkdir substrate
dpkg-deb -x mobilesubstrate_0.9.5101_iphoneos-arm.deb substrate
sudo mv substrate/Library/Frameworks/CydiaSubstrate.framework /Library/Frameworks/CydiaSubstrate.framework
sudo mv substrate/Library/MobileSubstrate /Library/MobileSubstrate
sudo mv substrate/usr/lib/* /usr/lib/</pre>
=== 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:
<pre>sudo apt-get install git perl curl</pre>
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.
=== For Windows ===
''To do: cygwin, perl, python. Use [ this].''
== Installing Theos ==
=== On Mac OS X or Linux ===
# Open a terminal window.
# Choose a location for Theos to be installed. If you are unsure, a good choice is <tt>/opt/theos</tt>.<pre>export THEOS=/opt/theos</pre>
#* 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.
# Download the latest version of Theos:
#* Using git: <pre>git clone git:// $THEOS</pre>
#* Alternatively, you can use svn, if you prefer: <pre>svn co $THEOS</pre>
# Download <tt>[[ldid]]</tt> to <tt>$THEOS/bin</tt>: <pre>git clone git://;cd ldid&#10;git submodule update --init&#10;./;cp -f ./ldid $THEOS/bin/ldid</pre>Or download from one of these sources:
# Add Theos environment variables to your <code>~/.bash_profile</code> (or the equivalent for your shell). Open <code>~/.bash_profile</code> (create it if it does not exist) in your favorite editor and add this on the last line, replacing "example" with your device's name (replacing spaces with dashes). If you prefer, you can also use your devices IP address. To find you IP, open settings, select wifi, then press the "i" on the network you are currently connected to. From here you should be able to see your devices IP address: <!-- this bit of text is borrowed from with permission, thanks kirb! --><br><pre>export THEOS=/opt/theos&#10;export PATH=$THEOS/bin:$PATH&#10;export THEOS_DEVICE_IP=example.local THEOS_DEVICE_PORT=22</pre>Load this into the shell with <code>. ~/.bash_profile</code>, or close the terminal window and launch a new one.
# As the Substrate library does not come installed on these platforms nor bundled with Theos, copy <code>/Library/Frameworks/CydiaSubstrate.framework/CydiaSubstrate</code> from the device to your local <code>$THEOS/lib</code> folder and rename it to <code>libsubstrate.dylib</code>. (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 [[Theos/Setup#Missing_Substrate_library|one of these error messages]]). Similarly, copy <code>/Library/Frameworks/CydiaSubstrate.framework/Headers/CydiaSubstrate.h</code> to your local <code>$THEOS/include</code> folder and rename it to <code>substrate.h</code>.
=== On iOS ===
Follow the instructions [[Theos/Setup/iOS | here]].
=== On Windows ===
''To do. Use [ this].''
=== 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 <code>$THEOS/sdks</code> (if it does not exist, create it), with a folder name like iPhoneOS7.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 ([[Theos/Setup#Troubleshooting|also noted in the "Troubleshooting" section below]]): <pre>".../theos/makefiles/targets/darwin-arm/ *** first argument to 'word' function must be greater than 0. stop."</pre>
== 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", [[Theos/Setup#Architecture_.28partial.29_incompatibility|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 <tt>./iphonedevwiki</tt> 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).
Some wifi spots firewall client devices from each other.  That will result in your computer being unable to install onto your iDevice.  If this is a problem your computer and your device won't be able to ping each other.  It may work for you to set up ad-hoc network.  On Mac OS X, under the WiFi menu, this is done with the "Create Network" item.  You will need to use static IP addressing.
If you are developing an application, you need to respring your device for your app's icon to show up on SpringBoard. You can always use <code>killall SpringBoard</code>, but since Saurik added '''UIKit Tools''', it's much nicer to use
$ uicache
== 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]].
== Troubleshooting ==
Before jumping to popular forums (StackOverflow, Reddit, IRC channels) to ask your questions, first give your error a good read, try looking for generic errors that might cover the one you are experiencing problems with. Use said forums but to find if your question has been asked before; chances are, it was! If you have exhausted your options, looked beyond the tenth page of a specific google query, think your question twice and ask it to yourself; would you understand what it is you are asking? If so, ask away.
Consider reading these articles too: [ What have you tried?] and [ Solving your skillset problems].
=== Empty $THEOS or corrupt symlink ===
<pre>Makefile:N: theos/makefiles/ Not a directory
Makefile:N: / No such file or directory</pre>
''N is a linenumber.''
Either <code>$THEOS</code> is empty or the theos symlink in your project(s) points to a wrong path (not <code>$THEOS</code>).
To fix the former, run:
export THEOS=[ platform_dependent_path]
Remember to have this exported on every session, method depends on the terminal you use.
To fix the latter, run in each directory the symlink is "broken":
rm theos; ln -s $THEOS
=== Missing SDK ===
If you get this message:
<pre>".../theos/makefiles/targets/PPP/ *** first argument to 'word' function must be greater than 0. stop."</pre>
''PPP is the platform of the working machine.''
It means that you don't have SDKs in <code>$THEOS/sdks</code>. See [[Theos/Setup#Also_for_Linux_and_iOS_.28and_other_operating_systems_other_than_Mac_OS_X.29:_Retrieving_SDKs|this section]].
=== Small SDK ===
If you get this message:
<pre>ld: file too small (length=LLL) file. '.../theos/sdks/iPhoneOSX.Y.sdk/usr/ZZZ' for architecture armAAA.</pre>
''LLL is a size, potentially 0 on most cases, X & Y are sdk version, ZZZ is a file path, AAA is architecture suffix (v6, v7, v7s, 64).''
It probably means that you have a faulty SDK in some way. One common mistake, while using Theos on an iOS device, is to extract the SDK on a PC and then copy over the files. This usually results in various errors in the extraction that translate in not being able to compile. Instead, copy the SDK in the compressed form and extract it on the device. Do not worry if this takes time, it will preserve all file attributes.
=== Missing Substrate header ===
If you get this message:
<pre>FFF:LLL:10: fatal error: 'substrate.h' file not found
#include <substrate.h>
1 error generated.</pre>
''LLL is a line number, FFF is a file path.''
This means that you are missing the Substrate header (see [[Theos/Setup#On_Mac_OS_X_or_Linux|step #6 in setting up Theos for OS X or Linux]]). To fix this you need to copy <code>/Library/Frameworks/CydiaSubstrate.framework/Headers/CydiaSubstrate.h</code> to your local <code>$THEOS/include</code> folder and rename it to <code>substrate.h</code>.
=== Missing Substrate library ===
If you get either of these messages:
<pre>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</pre>
<pre>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</pre>
''XXX and YYY are architecture suffixes (v6, v7, v7s, 64).''
This means that you are missing the Substrate library to link with (see [[Theos/Setup#On_Mac_OS_X_or_Linux|step #6 in setting up Theos for OS X or Linux]]) or you have an old version of the library. Either way, get an up-to-date version of the file from the device at <code>/Library/Frameworks/CydiaSubstrate.framework/CydiaSubstrate</code>, copy it to your local <code>$THEOS/lib</code> folder, and rename it to <code>libsubstrate.dylib</code>.
'''More detail about how to fix this:'''
OS X and Linux users can use the following command to copy the file (using the [ scp program]), where '''<code>DEVICE_IP</code>''' should be replaced with the IP address of your device where you have Substrate installed:
<code>scp -P PORT root@[DEVICE_IP]:/Library/Frameworks/CydiaSubstrate.framework/CydiaSubstrate $THEOS/lib/libsubstrate.dylib</code>
Windows users can use [ WinSCP] to connect to the device's IP address to locate the file and copy it over to their Theos installation.
iOS users usually don't have this problem because they usually already have Substrate installed. However, they can have an outdated version of Substrate and need to update it.
=== Architecture (partial) incompatibility ===
If you get this error while attempting to run the Theos New Instance Creator ([[NIC]]):
<pre>Illegal instruction: 4</pre>
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:
<pre>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</pre>
=== Spaces in Path ===
While building a project mostly works even if the path to the project contains spaces, <code>make package</code> will fail. Make sure you don't have spaces in the project path.
=== Undefined platform ===
If you get this message:
<pre>theos/makefiles/ *** You did not specify a target, and the "" platform does not define a default target. Stop.</pre>
or this one:
<pre>theos/makefiles/ *** The "iphone" target is not supported on the "" platform. Stop.</pre>
It probably means you are using a platform unsupported by Theos. If you are using iOS as a platform and on a 64bit device, you are probably getting this error. To fix this, you can do the following:
<pre>sudo ln -s $THEOS/makefiles/platform/Darwin-arm{,64}.mk
sudo ln -s $THEOS/makefiles/targets/Darwin-arm{,64}</pre>
=== Undefined symbols ===
If you get this message:
<pre>Undefined symbols for architecture armXXX:
  "_OBJC_CLASS_$_SomeClass", referenced from:
ld: symbol(s) not found for architecture armXXX
It probably means that you are trying to use the SomeClass class directly. This usually happens when using private classes that exist in binaries and cannot be linked in the compilation of your tweak. To work around this one must get the class at runtime. There are at least three ways to do it:
* %c(SomeClass)
* objc_getClass("SomeClass")
* NSClassFromString(@"SomeClass")
If, however, the class in question exists in a public or private framework from the SDK you are missing said framework in your <code>XXX_FRAMEWORKS</code> or <code>XXX_PRIVATE_FRAMEWORKS</code> list.
Or if you get a message that looks like this:
<pre>ld: warning: ignoring file /.../theos/lib/libsubstrate.dylib, missing required architecture armXXX in file /.../theos/lib/libsubstrate.dylib (2 slices)
Undefined symbols for architecture armXXX:
ld: symbol(s) not found for architecture armXXX</pre>
That means the Substrate dylib you are using doesn't contain the architecture you are linking. To fix this, get an up-to-date version of Substrate from the device at <code>/Library/Frameworks/CydiaSubstrate.framework/CydiaSubstrate</code>, copy it to your local <code>$THEOS/lib</code> folder, and rename it to <code>libsubstrate.dylib</code> For more detail about how to fix this, see the suggested command at [[#Missing Substrate library]].
=== Incompatible package compression ===
While installing a package created with Theos, you may get the following error:
dpkg-deb: file `package.deb' contains ununderstood data member data.tar.xz, giving up
dpkg: error processing package.deb (--install):
subprocess dpkg-deb --fsys-tarfile returned error exit status 2
Errors were encountered while processing:
This is because <code>dpkg-deb</code> now uses xz to compress the package, but Telesphoreo's old version of dpkg doesn't support it. You can force it to use dpkg-deb with a command line argument. Open <code>$THEOS/makefiles/package/</code>. Find <code>$(FAKEROOT) -r dpkg-deb</code>, and after dpkg-deb, add <code>-Zlzma</code>. It should look similar this:
$(FAKEROOT) -r dpkg-deb -Zlzma -b ...

Latest revision as of 07:05, 8 January 2022

Soft redirect to:

This article is obsolete, and has been replaced by the website.

If you need historical installation instructions, you can find the last version of this article here.