Theos

From iPhone Development Wiki

Languages: English • Deutsch

Theos is a cross-platform suite of development tools for managing, developing, and deploying iOS software without the use of Xcode. It is an important tool for people building extensions (tweaks) for jailbroken iOS; most extension developers use Theos.

Overview

The Theos suite of tools consists of a handful of important components:

  • A project templating system (NIC), which creates ready-to-build empty projects for varying purposes
  • A robust build system driven by GNU Make, capable of directly creating .deb packages for distribution in Cydia
  • Logos, a built-in preprocessor-based library of directives designed to make MobileSubstrate extension development easy

Theos is primarily used for jailbreak-centric iOS development (such as MobileSubstrate extensions, PreferenceLoader bundles, and applications intended for distribution in Cydia), but can be used for other types of projects as well. This can be helpful for someone wishing to develop an iPhone SDK-based application without using Mac OS X or Xcode to do so, as Theos can be used on Linux and iOS as well.

Theos also includes Logify, which accepts a class header and generates a MobileSubstrate extension which hooks all of that class's methods, printing log messages when they are called. This helps a hook developer see when certain methods are invoked during use.

How to start using Theos

See Installation.

This Stack Overflow answer may also be helpful.

For reference, check out this Theos documentation by theiostream.

Theos variables

You can configure Theos by setting variables in a project's Makefile or having them exported as environment variables (affecting all your projects).

Appending export before a variable will cause the variable to affect all subprojects as well. This is very useful for certain variables such as SYSROOT and TARGET

This list is incomplete. You can help by expanding it. From here?

Building

Variable name Description Default value Notes
THEOS The directory where Theos is installed on your machine. It is platform dependent
PACKAGE_VERSION The current build's number $(THEOS_PACKAGE_BASE_VERSION)-$(VERSION.INC_BUILD_NUMBER) [1]

PACKAGE_VERSION=$(THEOS_PACKAGE_BASE_VERSION) Can be used to disable debug build numbers

ARCHS List of architectures to build for.

Possible values: i386 x86_64 armv6 armv7 armv7s armv7f armv7v arm64 arm64e

armv7 arm64 arm64e arm64e devices in most cases can run arm64 binaries.

PreferenceLoader, however, cannot typically load arm64 bundles on arm64e devices.

TARGET Target specification for the build. Some values can be excluded

Formatting: platform:compiler:sdk_version:deployment_version

SYSROOT Root directory of the SDK you want to build this project with.

e.g. $(THEOS)/sdks/iPhoneOS11.2.sdk

This value is only necessary if you need to build your project against a specific SDK

$(THEOS)/SDKs/iPhoneOS<sdk_version>.sdk
TWEAK_NAME In _Tweak_ projects, the name of this project. Theos will look for <TWEAK_NAME>.plist in your project directory, so ensure it shares the name defined here
$(TWEAK_NAME)_FILES A list of files to compile for the project. .x* files will be preprocessed via logos before compilation

Example value: Tweak.xm AnotherFileWithHooks.x MyCoolObjcClass.m

shellscript macros can be used to include large amounts of files without having to manually type all of them.
$(TWEAK_NAME)_GENERATOR Specify the hooking generator for Logos. Possible values are MobileSubstrate and internal and are case-sensitive.

Example:
$(TWEAK_NAME)_GENERATOR = internal

MobileSubstrate
THEOS_BUILD_DIR Packages will be placed in the specified directory .
DEBUG Set to 1 to enable debug mode. undefined

Installation

Variable name Description Default value Notes
THEOS_DEVICE_IP IP used to install packages to a remote device. (Can also be the name of a host defined in ~/.ssh/config)
THEOS_DEVICE_PORT Port used to install packages to a remote device.
INSTALL_TARGET_PROCESSES Specify a list of processes to reload upon installation.

Example:
INSTALL_TARGET_PROCESSES = SpringBoard Spotlight

TARGET_INSTALL_REMOTE Should Packages be installed locally? 1, if THEOS_DEVICE_IP is set Leaving THEOS_DEVICE_IP blank when building on-device should install packages locally.
THEOS_DEVICE_USER User to log in as when installing the package root You shouldn't ever need to worry about this.
PREINSTALL_TARGET_PROCESSES Space delimited list of processes to unload before installation

Theos directories

This list is incomplete. You can help by expanding it. From here?

Path Description Notes
layout Acts as the root directory for the target device. Useful for Maintainer scripts and placing resources outside the project install path.
layout/DEBIAN Directory inside layout folder where one can place maintainer scripts to execute commands upon installation or removal. See https://wiki.debian.org/MaintainerScripts