TuT [Tutorial] How to setup/install Kirb's Theos on your iDevice!

Rook · October 19, 2015

In this tutorial, I will be showing you how to install Kirb's theos. Kirb's theos is a fork of the original theos by Dustin Howett but with more features!

(This list is sorted by the date the feature was added. The latest additions are at the bottom.)

Fallback/last resort headers can be placed at include/_fallback; this can be used to provide drop-in replacements for missing SDK headers. (rpetrich)
make update-theos, predictably enough, updates Theos to the latest commit. (rpetrich)
make package FINALPACKAGE=1 will optimise assets (runs pincrush on PNG images, and converts plists to binary format) and generate a package with a "clean" version (ie, no build number). Recommended when building a package you’re about to release. (rpetrich/kirb)
TWEAK_TARGET_PROCESSES = Preferences MobileMail is a shortcut for killing a process. (rpetrich)
Unlike rpetrich’s fork, the internal generator (using Objective-C runtime functions directly) is changed back to the Substrate generator (using Substrate’s wrappers around the runtime functions to assure future compatibility).
make do is a shortcut for make package install. (rpetrich)
Each architecture is compiled separately, rather than all being compiled at once. This avoids some issues with the original design of Theos. (rpetrich)
Different SDKs can be used for different architectures, making it possible to for instance use Xcode 4.4 for armv6 compilation alongside a newer Xcode for armv7/arm64. (rpetrich)
All generated files are stored in .theos, rather than many different directories in the root of the project. (rpetrich)
make clean-packages removes non-final packages. (rpetrich)
Makes dpkg-deb use lzma compression, because the current format dpkg-deb uses (xz) is not supported by Telesphoreo’s old dpkg build. (kirb)
Packages are output to a subdirectory called debs. (kirb)
Use hbang/headers as a submodule. (kirb)
Supports the iOS 7 simulator. (kirb)
Adds a %property directive that allows for creating a property on a hooked class. (eswick)
File.m_CFLAGS support, to have compiler flags on one particular file. (rpetrich)
Provides IS_IPAD and IN_SPRINGBOARD macros in the prefix header. (kirb)
Imports Cocoa and AppKit when targeting OS X. (kirb)
When using iOS SDK 7.0 or newer, and deploying to iOS 5 or newer, Theos defaults to building for armv7 and arm64. (rpetrich/kirb)
Adds simbltweak.mk to help in the building of SIMBL tweaks for OS X. (kirb)
Adds modern app and preference bundle templates. (kirb)
Adds %dtor { ... } directive to run code when the process is deconstructing. (uroboro)
Improves error handling when an SDK isn’t found. (uroboro)
Adds %hookf for hooking functions. Example (uroboro)
Supports building rpm packages. (rpetrich)
Adds STRIP=0 to not strip on release builds. (rpetrich)
Adds a stub libsubstrate.dylib binary so you don’t need to get one yourself. (kirb)
Kills Cydia if it’s open so you don’t get frustrated by dpkg status database locked errors. (kirb)
Fixes lack of a symlink that allows Theos to work on arm64. (kirb)
Supports Swift compilation and linking. Incomplete as it is uncertain whether Swift libraries are allowed to be distributed via Cydia. (kirb)
Deprecates NSLog in favor of more detailed log macros, HBLogDebug, HBLogInfo,HBLogWarn, and HBLogError. (kirb)
Makes debug builds the default. Use make DEBUG=0 or FORRELEASE=1 to build without debug. (kirb)
Bumps default deployment target to iOS 4.3 when using iOS SDK 6.0 and iOS 5.0 when using iOS SDK 7.0. (kirb)
Includes NIC templates from DHowett, conradev, WillFour20; uroboro; and bensge, kirb.
Supports building for iOS on Windows. (coolstar)
Theos symlinks are no longer made within projects. The $THEOS environment variable is used instead. (kirb)
instance_USE_SUBSTRATE = 0 can be used to switch tweaks to the internal generator and not link against Substrate. (kirb)
Default rules, variables, etc. can be set in ~/.theosrc (a makefile). (kirb)
make show opens the operating system’s file manager and highlights the latest package. (kirb)
A THEOS_INSTANCE_NAME constant is passed to the compiler so the current instance’s name can be used in the code. (kirb)
PREINSTALL_TARGET_PROCESSES and INSTALL_TARGET_PROCESSES can be set to a list of processes to kill before and after installation respectively. (rpetrich)
instance_LIBRARY_EXTENSION can be set to a custom file extension when building a library/tweak, or - for no extension. (kirb)
Output is colored so it’s easier to read at a glance. (kirb)
instance_WEAK_FRAMEWORKS and instance_WEAK_LIBRARIES allow you to weak linkagainst frameworks/libraries. (kirb)
Enables clang modules. Note that C++ modules are only enabled with iOS 8.4 and OS X 10.10 or newer, when building on OS X. (kirb)
Allows int argc, char **argv, char **envp arguments to be utilised in %ctor and%dtor. (uroboro)
Third party frameworks can be placed inside $THEOS/lib, and utilised withinstance_EXTRA_FRAMEWORKS. (kirb)
Adds backwards compatibility for nullability keywords when building with older versions of clang that don’t support it. (kirb)
Building for iOS Simulator now disables linking Substrate by default, allows linking against OS X binaries, and builds for only x86_64 by default (rather than both i386 and x86_64) when building for iOS 8.0 or newer. (kirb)
%hook nil class/selector errors will be logged by Logos (rather than Substrate, or in the case of the internal generator, failing silently). The source of the errors are therefore more obvious, and the class can be included in the log (which Substrate can’t do). (kirb)

TL;DR it’s pretty awesome, you should use it

More updates and features can be found in the GitHub page here.

Let's begin!

Requirements:
You will need these dependancies:
- CoolStar's repo: http://coolstar.org/publicrepo/
- iOS Toolchain
- Darwin CC Tools
- git (from Saurik's repo or cydia.radare.org)
- MobileTerminal / iOS Terminal / NewTerm or PuTTY on your PC.
- Apple File Conduit "2" (to transfer the archived SDK to your iDevice)
- iFile/Filza (to extract the zipped SDK. Not necessary if you'll be using Terminal)
- Perl (from CoolStar's repo)
- 10 minutes of your time

Setup Instructions:
Step 1: Make sure you have installed all the dependencies listed above. And then open a Terminal of your choice. We'll be using PuTTY on Windows.

login as: root
[email protected]'s password:
Ls-iPad:~ root#

Step 2: CD into the folder where you will setup theos on (/var/) and run this command to clone Kirb's theos:

cd /var && git clone --recursive git://github.com/kirb/theos.git

Ls-iPad:~ root# cd /var && git clone --recursive git://github.com/kirb/theos.git
Cloning into 'theos'...
remote: Counting objects: 6411, done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 6411 (delta 1), reused 0 (delta 0), pack-reused 6403
Receiving objects: 100% (6411/6411), 1.65 MiB | 547.00 KiB/s, done.
Resolving deltas: 100% (3281/3281), done.
Checking connectivity... done.
Ls-iPad:~ root#

The repository will also try to clone headers in /var/theos/include so if that fails then we will do it manually.

Failed message:

Submodule 'include' (https://github.com/hbang/headers.git) registered for path 'include'
Cloning into 'include'...
fatal: unable to access 'https://github.com/hbang/headers.git/': SSL certificate problem: unable to get local issuer certificate
Clone of 'https://github.com/hbang/headers.git' into submodule path 'include' failed

Fix:

Run this command one after another:

mkdir /var/theos/include && cd /var/theos/include && git clone git://github.com/hbang/headers.git

Output:

Ls-iPad:~ root# mkdir /var/theos/include && cd /var/theos/include && git clone git://github.com/hbang/headers.git
Cloning into 'headers'...
remote: Counting objects: 1222, done.
remote: Total 1222 (delta 0), reused 0 (delta 0), pack-reused 1222
Receiving objects: 100% (1222/1222), 509.51 KiB | 288.00 KiB/s, done.
Resolving deltas: 100% (457/457), done.
Checking connectivity... done.
Checking out files: 100% (380/380), done.

Step 3: After we have theos and headers cloned onto our system, we will now need the SDK.

cd /var/theos/

mkdir sdks

Now download the SDK from here (iOS 7.1 or 8.1 SDK is suggested) and send the .tbz2 archive to /var/theos/sdks.

Once that is there, we will need to unarchive the file. You can do this using iFile but we'll be using this command to extract it:

cd /var/theos/sdks

tar xvjf *.tbz2*

rm -rf *.tbz2*

The commands above extract the archive, and them removes the .tbz2 file from that directory since it's not needed anymore.

Now run NIC and enjoy!

Extra:
By default, Kirb's theos does not use the theos symlink to your newly created projects using NIC. To fix this, go to /var/theos/bin/nic.pl and edit the file and change this line:

my %CONFIG = (link_theos => 0);

To:

my %CONFIG = (link_theos => 1);

Save it and done.

---------

You can install DHowett's/Rpetrich's/CoolStar's theos alongside this also.

NitroxicDemon · October 19, 2015

this must have taken years to write

itzBacho · October 19, 2015

Thank You

Amuyea · October 19, 2015

Looks cool

castix · October 19, 2015

Beginners should still use the plain Theos from dhowett

Rook · October 19, 2015

Beginners should still use the plain Theos from dhowett

True but this is a good one also.

Diversityy · October 19, 2015

I'm going to semi restore

castix · October 19, 2015

/usr/libexec/git-core/git-submodule: line 153: 15599 Broken pipe: 13         ( git ls-files -z --error-unmatch --stage -- "$@" || echo "unmatched pathspec exists" )
     15600 Killed: 9               | /usr/bin/perl -e '
	my %unmerged = ();
	my ($null_sha1) = ("0" x 40);
	my @[member=Out] = ();
	my $unmatched = 0;
	$/ = "\0";
	while (<STDIN>) {
		if (/^unmatched pathspec/) {
			$unmatched = 1;
			next;
		}
		chomp;
		my ($mode, $sha1, $stage, $path) =
			/^([0-7]+) ([0-9a-f]{40}) ([0-3])\t(.*)$/;
		next unless $mode eq "160000";
		if ($stage ne "0") {
			if (!$unmerged{$path}++) {
				push @[member=Out], "$mode $null_sha1 U\t$path\n";
			}
			next;
		}
		push @[member=Out], "$_\n";
	}
	if ($unmatched) {
		print "#unmatched\n";
	} else {
		print for (@[member=Out]);
	}
	'
/usr/libexec/git-core/git-submodule: line 153: 15605 Broken pipe: 13         ( git ls-files -z --error-unmatch --stage -- "$@" || echo "unmatched pathspec exists" )
     15606 Killed: 9               | /usr/bin/perl -e '
	my %unmerged = ();
	my ($null_sha1) = ("0" x 40);
	my @[member=Out] = ();
	my $unmatched = 0;
	$/ = "\0";
	while (<STDIN>) {
		if (/^unmatched pathspec/) {
			$unmatched = 1;
			next;
		}
		chomp;
		my ($mode, $sha1, $stage, $path) =
			/^([0-7]+) ([0-9a-f]{40}) ([0-3])\t(.*)$/;
		next unless $mode eq "160000";
		if ($stage ne "0") {
			if (!$unmerged{$path}++) {
				push @[member=Out], "$mode $null_sha1 U\t$path\n";
			}
			next;
		}
		push @[member=Out], "$_\n";
	}
	if ($unmatched) {
		print "#unmatched\n";
	} else {
		print for (@[member=Out]);
	}
	'

ldid 1.2.1, iOS 9